Index: Makefile
===================================================================
--- Makefile (nonexistent)
+++ Makefile (revision 5)
@@ -0,0 +1,56 @@
+
+COMPONENT_TARGETS = $(HARDWARE_NOARCH)
+
+
+include ../../../../build-system/constants.mk
+
+
+url = $(DOWNLOAD_SERVER)/sources/X.org/lib/libX11
+
+versions = 1.8.3
+pkgname = libX11
+suffix = tar.xz
+
+tarballs = $(addsuffix .$(suffix), $(addprefix $(pkgname)-, $(versions)))
+sha1s = $(addsuffix .sha1sum, $(tarballs))
+
+patches = $(CURDIR)/patches/libX11-1.8.3-docbook.patch
+
+.NOTPARALLEL: $(patches)
+
+
+BUILD_TARGETS = $(tarballs) $(sha1s) $(patches)
+
+
+include ../../../../build-system/core.mk
+
+
+.PHONY: download_clean
+
+
+$(tarballs):
+ @echo -e "\n======= Downloading source tarballs =======" ; \
+ for tarball in $(tarballs) ; do \
+ echo "$(url)/$$tarball" | xargs -n 1 -P 100 wget $(WGET_OPTIONS) - & \
+ done ; wait
+
+$(sha1s): $(tarballs)
+ @for sha in $@ ; do \
+ echo -e "\n======= Downloading '$$sha' signature =======\n" ; \
+ echo "$(url)/$$sha" | xargs -n 1 -P 100 wget $(WGET_OPTIONS) - & wait %1 ; \
+ touch $$sha ; \
+ echo -e "\n======= Check the '$$sha' sha1sum =======\n" ; \
+ sha1sum --check $$sha ; ret="$$?" ; \
+ if [ "$$ret" == "1" ]; then \
+ echo -e "\n======= ERROR: Bad '$$sha' sha1sum =======\n" ; \
+ exit 1 ; \
+ fi ; \
+ done
+
+$(patches): $(sha1s)
+ @echo -e "\n======= Create Patches =======\n" ; \
+ ( cd create-1.8.3-docbook-patch ; ./create.patch.sh ) ; \
+ echo -e "\n"
+
+download_clean:
+ @rm -f $(tarballs) $(sha1s) $(patches)
Index: create-1.8.3-docbook-patch/create.patch.sh
===================================================================
--- create-1.8.3-docbook-patch/create.patch.sh (nonexistent)
+++ create-1.8.3-docbook-patch/create.patch.sh (revision 5)
@@ -0,0 +1,15 @@
+#!/bin/sh
+
+VERSION=1.8.3
+
+tar --files-from=file.list -xJvf ../libX11-$VERSION.tar.xz
+mv libX11-$VERSION libX11-$VERSION-orig
+
+cp -rf ./libX11-$VERSION-new ./libX11-$VERSION
+
+diff --unified -Nr libX11-$VERSION-orig libX11-$VERSION > libX11-$VERSION-docbook.patch
+
+mv libX11-$VERSION-docbook.patch ../patches
+
+rm -rf ./libX11-$VERSION
+rm -rf ./libX11-$VERSION-orig
Property changes on: create-1.8.3-docbook-patch/create.patch.sh
___________________________________________________________________
Added: svn:executable
## -0,0 +1 ##
+*
\ No newline at end of property
Index: create-1.8.3-docbook-patch/file.list
===================================================================
--- create-1.8.3-docbook-patch/file.list (nonexistent)
+++ create-1.8.3-docbook-patch/file.list (revision 5)
@@ -0,0 +1,18 @@
+libX11-1.8.3/specs/XIM/xim.xml
+libX11-1.8.3/specs/XKB/ch09.xml
+libX11-1.8.3/specs/XKB/ch10.xml
+libX11-1.8.3/specs/XKB/ch12.xml
+libX11-1.8.3/specs/i18n/localedb/localedb.xml
+libX11-1.8.3/specs/i18n/trans/trans.xml
+libX11-1.8.3/specs/libX11/AppC.xml
+libX11-1.8.3/specs/libX11/CH01.xml
+libX11-1.8.3/specs/libX11/CH02.xml
+libX11-1.8.3/specs/libX11/CH03.xml
+libX11-1.8.3/specs/libX11/CH04.xml
+libX11-1.8.3/specs/libX11/CH06.xml
+libX11-1.8.3/specs/libX11/CH08.xml
+libX11-1.8.3/specs/libX11/CH09.xml
+libX11-1.8.3/specs/libX11/CH10.xml
+libX11-1.8.3/specs/libX11/CH12.xml
+libX11-1.8.3/specs/libX11/CH14.xml
+libX11-1.8.3/specs/libX11/glossary.xml
Index: create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/XIM/xim.xml
===================================================================
--- create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/XIM/xim.xml (nonexistent)
+++ create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/XIM/xim.xml (revision 5)
@@ -0,0 +1,3940 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
+[
+<!ENTITY % defs SYSTEM "defs.ent"> %defs;
+]>
+
+
+<!-- lifted from troff+ms+XMan by doclifter -->
+<article class="specification" id="xim">
+
+<articleinfo>
+ <title>The Input Method Protocol</title>
+ <subtitle>X Consortium Standard</subtitle>
+ <releaseinfo>X Version 11, Release &fullrelvers;</releaseinfo>
+ <releaseinfo>Version 1.0</releaseinfo>
+ <authorgroup>
+ <author>
+ <firstname>Masahiko</firstname><surname>Narita</surname>
+ <affiliation><orgname>FUJITSU Limited.</orgname></affiliation>
+ </author>
+ <author>
+ <firstname>Hideki</firstname><surname>Hiura</surname>
+ <affiliation><orgname>SunSoft, Inc.</orgname></affiliation>
+ </author>
+ </authorgroup>
+ <copyright><year>1993</year><year>1994</year>
+ <holder>FUJITSU LIMITED</holder>
+ <holder>Oracle and/or its affiliates</holder>
+ </copyright>
+
+<abstract>
+<para>
+This specifies a protocol between IM library and IM (Input Method) Server for internationalized text input, which is independent from any specific language, any specific input method and the transport layer used in communication between the IM library and the IM Server, and uses a client-server model. This protocol allows user to use his/her favorite method for all applications within the stand-along distributed environment.
+</para>
+</abstract>
+
+<legalnotice>
+<para>Permission to use, copy and distribute this documentation for any purpose
+and without fee is hereby granted, provided that the above copyright notice
+and this permission notice appear in all copies. Fujitsu and Sun Microsystems
+make no representation about the suitability for any purpose of the information in this document.
+This documentation is provided as is without express implied warranty.
+</para>
+</legalnotice>
+
+<legalnotice>
+<para role="multiLicensing">Copyright © 1993, 1994 X Consortium</para>
+<para>Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+</para>
+<para>The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.</para>
+<para>THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE X
+CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+</para>
+<para>
+Except as contained in this notice, the name of the X Consortium shall not be
+used in advertising or otherwise to promote the sale, use or other dealings in
+this Software without prior written authorization from the X Consortium.
+</para>
+<para>X Window System is a trademark of The Open Group.</para>
+</legalnotice>
+
+</articleinfo>
+
+<sect1 id="Introduction">
+<title>Introduction</title>
+<sect2 id="Scope">
+<title>Scope</title>
+<!-- .XS -->
+<!-- (SN Scope -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The internationalization in the
+X Window System
+Version 11, Release 5 (X11R5) provides a common API which application
+developers can use to create portable internationalized programs and to
+adapt them to the requirements of different native languages, local customs,
+and character string encodings (this is called "localization").
+As one of its internationalization mechanisms X11R5 has defined a functional
+interface for internationalized text input, called XIM (X Input Method).
+</para>
+<para>
+<!-- .LP -->
+When a client-server model is used with an IM (Input Method) implementation,
+a protocol must be established between the client and the server.
+However, the protocol used to interface Input Method Servers (IM Servers)
+with the Input Method libraries (IM libraries) to which applications are
+linked was not addressed in X11R5.
+This led application developers to depend on vendor-specific input methods,
+decreased the user's choice of available input methods, and made it more
+difficult for developers to create portable applications. This paper describes
+the Input Method Protocol developed for X11R6 to resolve the above problems
+and to address the requirements of existing and future input methods.
+</para>
+<para>
+<!-- .LP -->
+The Input Method Protocol is independent from the transport layer used in
+communication between the IM library and the IM Server.
+Thus, the input method protocol can be built on any inter-process
+communication mechanism, such as TCP/IP or the X protocol.
+</para>
+<para>
+In addition, the protocol provides for future extensions such as differing
+input model types.
+</para>
+</sect2>
+
+<sect2 id="Background">
+<title>Background</title>
+<!-- .XS -->
+<!-- (SN Background -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Text input is much more simple for some languages than
+others. English, for instance, uses an alphabet of a manageable size,
+and input consists of pressing the corresponding key on a keyboard,
+perhaps in combination with a shift key for capital letters or special
+characters.
+</para>
+<para>
+<!-- .LP -->
+Some languages have larger alphabets, or modifiers such as accents,
+which require the addition of special key combinations in order to enter
+text. These input methods may require "dead-keys" or "compose-keys"
+which, when followed by different combinations of key strokes,
+generate different characters.
+</para>
+<para>
+<!-- .LP -->
+Text input for ideographic languages is much less simple. In these
+languages, characters represent actual objects rather than phonetic
+sounds used in pronouncing a word, and the number of characters
+in these languages may continue to grow. In Japanese, for instance, most
+text input methods involve entering characters in a phonetic alphabet,
+after which the input method searches a dictionary for possible
+ideographic equivalents (of which there may be many). The input method then
+presents the candidate characters for the user to choose from.
+</para>
+<para>
+<!-- .LP -->
+In Japanese, either Kana (phonetic symbols) or Roman letters are
+typed and then a region is selected 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.
+</para>
+<para>
+<!-- .LP -->
+These complicated input methods must present state information (Status Area),
+text entry and edit space (Preedit Area), and menu/choice presentations
+(Auxiliary Area). Much of the protocol between the IM library and the IM
+Server involves managing these IM areas.
+Because of the size and complexity of these input methods, and because
+of how widely they vary from one language or locale to another, they are
+usually implemented as separate processes which can serve many client
+processes on the same computer or network.
+</para>
+<para>
+<!-- .LP -->
+</para>
+</sect2>
+<sect2 id="Input_Method_Styles">
+<title>Input Method Styles</title>
+<!-- .XS -->
+<!-- (SN Input Method Styles -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+X11 internationalization support includes the following four types of
+input method:
+<!-- .RS -->
+</para>
+
+<variablelist>
+ <varlistentry>
+ <term>- on-the-spot:</term>
+ <listitem>
+ <para>
+The client application is directed by the IM Server to display all
+pre-edit data at the site of text insertion. The client registers
+callbacks invoked by the input method during pre-editing.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>- off-the-spot:</term>
+ <listitem>
+ <para>
+The client application provides display windows for the pre-edit data
+to the input method which displays into them directly.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>- over-the-spot:</term>
+ <listitem>
+ <para>
+The input method displays pre-edit data in a window which it brings up
+directly over the text insertion position.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>- root-window:</term>
+ <listitem>
+ <para>
+The input method displays all pre-edit data in a separate area of the
+screen in a window specific to the input method.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+Client applications must choose from the available input methods
+supported by the IM Server and provide the display areas and callbacks
+required by the input method.
+</para>
+</sect2>
+
+</sect1>
+<sect1 id="Architecture">
+<title>Architecture</title>
+<!-- .XS -->
+<!-- (SN Architecture -->
+<!-- .XE -->
+<sect2 id="Implementation_Model">
+<title>Implementation Model</title>
+<!-- .XS -->
+<!-- (SN Implementation Model -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Within the X Window System environment, the following two typical
+architectural models can be used as an input method's implementation
+model.
+</para>
+
+<variablelist>
+ <varlistentry>
+ <term>- Client/Server model:</term>
+ <listitem>
+ <para>
+A separate process, the IM Server, processes input and handles preediting,
+converting, and committing. The IM library within the application, acting
+as client to the IM Server, simply receives the committed string from the
+IM Server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>- Library model:</term>
+ <listitem>
+ <para>
+All input is handled by the IM library within the application. The
+event process is closed within the IM library and a separate IM Server
+process may not be required.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+Most languages which need complex preediting, such as Asian languages,
+are implemented using the Client/Server IM model. Other languages
+which need only dead key or compose key processing, such as European
+languages, are implemented using the Library model.
+</para>
+<para>
+<!-- .LP -->
+In this paper, we discuss mainly the Client/Server IM model and the
+protocol used in communication between the IM library (client) and the IM
+Server.
+</para>
+</sect2>
+
+<sect2 id="Structure_of_IM">
+<title>Structure of IM</title>
+<!-- .XS -->
+<!-- (SN Structure of IM -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+When the client connects or disconnects to the IM Server, an open or close
+operation occurs between the client and the IM Server.
+</para>
+<para>
+<!-- .LP -->
+The IM can be specified at the time of XOpenIM() by setting the locale
+of the client and a locale modifier. Since the IM remembers
+the locale at the time of creation XOpenIM() can be called
+multiple times (with the
+setting for the locale and the locale modifier changed) to support
+multiple languages.
+</para>
+<para>
+<!-- .LP -->
+In addition, the supported IM type can be obtained using XGetIMValues().
+</para>
+<para>
+<!-- .LP -->
+The client usually holds multiple input (text) fields. Xlib provides a
+value type called the "Input Context" (IC) to manage each individual
+input field. An IC can be created by specifying XIM using XCreateIC(),
+and it can be destroyed using XDestroyIC().
+</para>
+<para>
+<!-- .LP -->
+The IC can specify the type of IM which is supported by XIM for each
+input field, so each input field can handle a different type of IM.
+</para>
+<para>
+<!-- .LP -->
+Most importantly information such as the committed string sent from
+the IM Server to the client, is exchanged based on each IC.
+</para>
+<para>
+<!-- .LP -->
+Since each IC corresponds to an input field, the focused input field
+should be announced to the IM Server using XSetICFocus(). (XUnsetICFocus()
+can also be used to change the focus.)
+</para>
+<para>
+<!-- .LP -->
+</para>
+</sect2>
+<sect2 id="Event_Handling_Model">
+<title>Event Handling Model</title>
+<!-- .XS -->
+<!-- (SN Event Handling Model -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Existing input methods support either the FrontEnd method, the BackEnd method,
+or both. This protocol specifically supports the BackEnd method as
+the default method, but also supports the FrontEnd method as an optional
+IM Server extension.
+</para>
+<para>
+<!-- .LP -->
+The difference between the FrontEnd and BackEnd methods is in how
+events are delivered to the IM Server. (Fig. 1) <!-- xref -->
+</para>
+
+<sect3 id="BackEnd_Method">
+<title>BackEnd Method</title>
+<!-- .XS -->
+<!-- (SN BackEnd Method -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+In the BackEnd method, client window input events are always delivered
+to the IM library, which then passes them to the IM Server. Events are
+handled serially in the order delivered, and therefore there is no
+synchronization problem between the IM library and the IM Server.
+</para>
+<para>
+<!-- .LP -->
+Using this method, the IM library forwards all KeyPress and KeyRelease
+events to the IM Server (as required by the Event Flow Control model
+described in
+<xref linkend='Event_Flow_Control' xrefstyle='select: title'/>)
+and synchronizes with the IM Server (as described in
+<xref linkend='Filtering_Events' xrefstyle='select: title'/>).
+
+</para>
+</sect3>
+
+<sect3 id="FrontEnd_Method">
+<title>FrontEnd Method</title>
+<!-- .XS -->
+<!-- (SN FrontEnd Method -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+In the FrontEnd method, client window input events are delivered by the
+X server directly to both the IM Server and the IM library. Therefore this
+method provides much better interactive performance while preediting
+(particularly in cases such as when the IM Server is running locally on
+the user's workstation and the client application is running on another
+workstation over a relatively slow network).
+</para>
+<para>
+<!-- .LP -->
+However, the FrontEnd model may have synchronization problems between
+the key events handled in the IM Server and other events handled in the
+client, and these problems could possibly cause the loss or duplication
+of key events. For this reason, the BackEnd method is the core method
+supported, and the FrontEnd method is made available as an extension for
+performance purposes. (Refer to
+<xref linkend="common_extensions" xrefstyle='select: title'/>
+for more information.)
+</para>
+
+<mediaobject id="flow_of_events">
+ <imageobject>
+ <imagedata format="SVG" fileref="eventflow.svg"/>
+ </imageobject>
+ <caption>The flow of events</caption>
+</mediaobject>
+
+<!--
+<para>
+Fig.1 The Flow of Events
+</para>
+-->
+
+</sect3>
+</sect2>
+
+<sect2 id='Event_Flow_Control'>
+<title>Event Flow Control</title>
+<!-- .XS -->
+<!-- (SN Event Flow Control -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+This protocol supports two event flow models for communication between the
+IM library and the IM Server (Static and Dynamic).
+</para>
+<para>
+<!-- .LP -->
+Static Event Flow requires that input events always be sent to the IM
+Server from the client.
+</para>
+<para>
+<!-- .LP -->
+Dynamic Event Flow, however, requires only that those input events which
+need to be processed (converted) be sent to the IM Server from the client.
+</para>
+<para>
+<!-- .LP -->
+For instance, in the case of inputing a combination of ASCII characters
+and Chinese characters, ASCII characters do not need to be processed in
+the IM Server, so their key events do not have to be sent to the IM
+Server. On the other hand, key events necessary for composing Chinese
+characters must be sent to the IM Server.
+</para>
+<para>
+<!-- .LP -->
+Thus, by adopting the Dynamic Event Flow, the number of requests among the
+X Server, the client, and the IM Server is significantly reduced, and the
+number of context switches is also reduced, resulting in improved performance.
+The IM Server can send
+<function>XIM_REGISTER_TRIGGERKEYS </function>
+message in order to switch the event flow in the Dynamic Event Flow.
+</para>
+<para>
+<!-- .LP -->
+The protocol for this process is described in
+<xref linkend='Event_Flow_Control_2' xrefstyle='select: title'/>.
+</para>
+</sect2>
+</sect1>
+
+<sect1 id="Default_Preconnection_Convention">
+<title>Default Preconnection Convention</title>
+<!-- .XS -->
+<!-- (SN Default Preconnection Convention -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+IM Servers are strongly encouraged to register their symbolic
+names as the ATOM names into the IM Server directory property,
+<function>XIM_SERVERS,</function>
+on the root window of the screen_number 0.
+This property can contain a list of ATOMs, and the each ATOM represents
+each possible IM Server.
+IM Server names are restricted to POSIX Portable Filename Character Set.
+To discover if the IM Server is active, see if there is an owner for
+the selection with that atom name. To learn the address of that IM Server,
+convert the selection target
+<function>TRANSPORT,</function>
+which will return a string form of the transport address(es).
+To learn the supported locales of that IM Server, convert the selection target
+<function>LOCALES,</function>
+which will return a set of names of the supported locales in the syntax
+X/Open defines.
+</para>
+<para>
+<!-- .LP -->
+The basic semantics to determine the IM Server if there are
+multiple ATOMs are found in
+<function>XIM_SERVERS</function>
+property, is first fit if the IM Server name is not given as
+a X modifier's category
+<function>im.</function>
+</para>
+<para>
+<!-- .LP -->
+The address information retrievable from the
+<function>TRANSPORT</function>
+target is a transport-specific name.
+The preregistered formats for transport-specific names are listed in
+<xref linkend="transport_list" xrefstyle='select: title'/>.
+Additional transport-specific names may be registered with X Consortium.
+</para>
+
+<para>
+For environments that lack X connections, or for IM Servers which
+do not use the X Window System, the preconnection convention with IM Server
+may be given outside the X Window system (e.g. using a Name Service).
+</para>
+</sect1>
+
+<sect1 id="Protocol">
+<title>Protocol</title>
+<!-- .XS -->
+<!-- (SN Protocol -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The protocol described below uses the bi-directional
+synchronous/asynchronous request/reply/error model and is specified
+using the same conventions outlined in Section 2 of the core X Window
+System protocol [1]:
+</para>
+
+<sect2 id="Basic_Requests_Packet_Format">
+<title>Basic Requests Packet Format</title>
+<!-- .XS -->
+<!-- (SN Basic Requests Packet Format -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+This section describes the requests that may be exchanged between the client
+and the IM Server.
+</para>
+<para>
+<!-- .LP -->
+The basic request packet header format is as follows.
+</para>
+<literallayout class="monospaced">
+ major-opcode: CARD8
+ minor-opcode: CARD8
+ length: CARD16
+</literallayout>
+
+<para>
+The MAJOR-OPCODE specifies which core request or extension package this
+packet represents. If the MAJOR-OPCODE corresponds to a core request,
+the MINOR-OPCODE contains 8 bits of request-specific data.
+(If the MINOR-OPCODE is not used, it is 0.)
+Otherwise, the MAJOR-OPCODE and the MINOR-OPCODE are specified by
+<function>XIM_QUERY_EXTENSION</function>
+message. (Refer to 4.7. Query the supported extension protocol list.)
+The LENGTH field specifies the number of 4 bytes elements following the
+header. If no additional data is followed by the header, the LENGTH field
+will be 0.
+</para>
+</sect2>
+
+<sect2 id="Data_Types">
+<title>Data Types</title>
+<!-- .XS -->
+<!-- (SN Data Types -->
+<!-- .XE -->
+<para>
+The following data types are used in the core X IM Server protocol:
+</para>
+
+<literallayout class="monospaced">
+BITMASK16
+ CARD16
+BITMASK32
+ CARD32
+PADDING FORMAT
+ Where N is some expression, and Pad(N) is the number of bytes needed to round N up to a
+
+ Pad(N) = (4 - (N mod 4)) mod 4
+
+LPCE
+ 1 A character from the4 X Portable Character Set in Latin Portable
+ Character Encoding
+
+STRING
+ 2 n length of string in bytes
+ n LISTofLPCE string
+ p unused, p=Pad(2+n)
+
+STR
+ 1 n length of name in bytes
+ n STRING8 name
+
+XIMATTR
+ 2 CARD16 attribute ID (*1)
+ 2 CARD16 type of the value (*2)
+ 2 n length of im-attribute
+ n STRING8 im-attribute
+ p unused, p = Pad(2+n)
+
+The im-attribute argument specifies XIM values such as XNQueryInputStyle.
+
+XICATTR
+ 2 CARD16 attribute ID (*1)
+ 2 CARD16 type of the value (*2)
+ 2 n length of ic-attribute
+ n STRING8 ic-attribute
+ p unused, p = Pad(2+n)
+
+(*1) XIMATTR and XICATTR are used during the setup stage and XIMATTRIBUTE and
+ XICATTRIBUTE are used after each attribute ID has been recognized by
+ the IM Server and the IM library.
+
+(*2) The value types are defined as follows:
+</literallayout>
+<informaltable id="valuetypes" frame="topbot">
+ <?dbfo keep-together="auto" ?>
+ <tgroup cols="5" align='left' colsep='0' rowsep='0'>
+ <colspec colname="col1" colwidth="0.9*"/>
+ <colspec colname="col2" colwidth="3.0*"/>
+ <colspec colname="col3" colwidth="3.2*"/>
+ <colspec colname="col4" colwidth="2.9*"/>
+ <colspec colname="col5" colwidth="2.9*"/>
+ <spanspec namest="col3" nameend="col5" spanname="span-horiz" align="center"/>
+ <thead>
+ <row rowsep='1'>
+ <entry>values</entry>
+ <entry>data</entry>
+ <entry>format</entry>
+ <!-- <entry spanname="span-horiz">format</entry> -->
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>#0</entry>
+ <entry>Separator of NestedList</entry>
+ <entry>-----(*3)</entry>
+ </row>
+ <row>
+ <entry>#1</entry>
+ <entry>byte data</entry>
+ <entry>CARD8</entry>
+ </row>
+ <row>
+ <entry>#2</entry>
+ <entry>word data</entry>
+ <entry>CARD16</entry>
+ </row>
+ <row>
+ <entry>#3</entry>
+ <entry>long data</entry>
+ <entry>CARD32</entry>
+ </row>
+ <row>
+ <entry>#4</entry>
+ <entry>char data</entry>
+ <entry>STRING8</entry>
+ </row>
+ <row>
+ <entry>#5</entry>
+ <entry>Window</entry>
+ <entry>CARD32</entry>
+ </row>
+ <row>
+ <entry>#10</entry>
+ <entry>XIMStyles</entry>
+ <entry>2</entry>
+ <entry>n</entry>
+ <entry>number of XIMStyle list</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry></entry>
+ <entry>2</entry>
+ <entry></entry>
+ <entry>unused</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry></entry>
+ <entry>n</entry>
+ <entry>CARD32</entry>
+ <entry>XIMStyle list</entry>
+ </row>
+ <row>
+ <entry>#11</entry>
+ <entry>XRectangle</entry>
+ <entry>2</entry>
+ <entry>INT16</entry>
+ <entry>X</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry></entry>
+ <entry>2</entry>
+ <entry>INT16</entry>
+ <entry>Y</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry></entry>
+ <entry>2</entry>
+ <entry>CARD16</entry>
+ <entry>width</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry></entry>
+ <entry>2</entry>
+ <entry>CARD16</entry>
+ <entry>height</entry>
+ </row>
+ <row>
+ <entry>#12</entry>
+ <entry>XPoint</entry>
+ <entry>2</entry>
+ <entry>INT16</entry>
+ <entry>X</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry></entry>
+ <entry>2</entry>
+ <entry>INT16</entry>
+ <entry>Y</entry>
+ </row>
+ <row>
+ <entry>#13</entry>
+ <entry>XFontSet</entry>
+ <entry>2</entry>
+ <entry>n</entry>
+ <entry>length of Base font name</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry></entry>
+ <entry>n</entry>
+ <entry>STRING8</entry>
+ <entry>Base font name list</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry></entry>
+ <entry>p</entry>
+ <entry></entry>
+ <entry>unused, p = Pad(2+n)</entry>
+ </row>
+ <row>
+ <entry>#15</entry>
+ <entry>XIMHotKeyTriggers</entry>
+ <entry>4</entry>
+ <entry>n</entry>
+ <entry>number of XIMTRIGGERKEY list (*4)</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry></entry>
+ <entry>n</entry>
+ <entry>XIMTRIGGERKEY</entry>
+ <entry>XIMHotkeyTrigger list</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry></entry>
+ <entry>n</entry>
+ <entry>XIMHOTKEYSTATE</entry>
+ <entry>HotKey processing state</entry>
+ </row>
+ <row>
+ <entry>#17</entry>
+ <entry>XIMStringConversion</entry>
+ <entry>XIMSTRCONVTEXT</entry>
+ <entry></entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry>#18</entry>
+ <entry>XIMPreeditState</entry>
+ <entry>XIMPREEDITSTATE</entry>
+ </row>
+ <row>
+ <entry>#19</entry>
+ <entry>XIMResetState</entry>
+ <entry>XIMRESETSTATE</entry>
+ </row>
+ <row>
+ <entry>#x7fff</entry>
+ <entry>NestedList</entry>
+ <entry>-----</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<literallayout class="monospaced">
+(*3) The IC value for the separator of NestedList is defined as follows,
+ #define XNSeparatorofNestedList "separatorofNestedList"
+ , which is registered in X Consortium and cannot be used for any other purpose.
+
+(*4) LISTofFOO
+ A Type name of the form LISTof FOO means a counted list of elements of type FOO.
+ The size of the length field may vary (it is not necessarily the same
+ size as a FOO), and in some cases, it may be implicit.
+XIMTRIGGERKEY
+ 4 CARD32 keysym
+ 4 CARD32 modifier
+ 4 CARD32 modifier mask
+
+ENCODINGINFO
+ 2 n length of encoding info
+ n STRING8 encoding info
+ p unused, p=Pad(2+n)
+
+EXT
+ 1 CARD8 extension major-opcode
+ 1 CARD8 extension minor-opcode
+ 2 n length of extension name
+ n STRING8 extension name
+ p unused, p = Pad(n)
+
+XIMATTRIBUTE
+ 2 CARD16 attribute ID
+ 2 n value length
+ n value
+ p unused, p = Pad(n)
+
+XICATTRIBUTE
+ 2 CARD16 attribute ID
+ 2 n value length
+ n value
+ p unused, p = Pad(n)
+
+
+
+XIMSTRCONVTEXT
+ 2 CARD16 XIMStringConversionFeedback
+ #x0000001 XIMStringConversionLeftEdge
+ #x0000002 XIMStringConversionRightEdge
+ #x0000004 XIMStringConversionTopEdge
+ #x0000008 XIMStringConversionBottomEdge
+ #x0000010 XIMStringConversionConvealed
+ #x0000020 XIMStringConversionWrapped
+ 2 n byte length of the retrieved string
+ n STRING8 retrieved string
+ p unused, p = Pad(n)
+ 2 m byte length of feedback array
+ 2 unused
+ m LISTofXIMSTRCONVFEEDBACK feedback array(*1)
+
+(*1) This field is reserved for future use.
+
+XIMFEEDBACK
+ 4 CARD32 XIMFeedback
+ #x000001 XIMReverse
+ #x000002 XIMUnderline
+ #x000004 XIMHighlight
+ #x000008 XIMPrimary
+ #x000010 XIMSecondary
+ #x000020 XIMTertiary
+ #x000040 XIMVisibleToForward
+ #x000080 XIMVisibleToBackward
+ #x000100 XIMVisibleCenter
+
+XIMHOTKEYSTATE
+ 4 CARD32 XIMHotKeyState
+ #x0000001 XIMHotKeyStateON
+ #x0000002 XIMHotKeyStateOFF
+
+XIMPREEDITSTATE
+ 4 CARD32 XIMPreeditState
+ #x0000001 XIMPreeditEnable
+ #x0000002 XIMPreeditDisable
+
+XIMRESETSTATE
+ 4 CARD32 XIMResetState
+ #x0000001 XIMInitialState
+ #x0000002 XIMPreserveState
+</literallayout>
+</sect2>
+
+<sect2 id="Error_Notification">
+<title>Error Notification</title>
+<!-- .XS -->
+<!-- (SN Error Notification -->
+<!-- .XE -->
+<para>
+Both the IM Server and the IM library return
+<function>XIM_ERROR</function>
+messages instead of the corresponding reply messages if any errors occur
+during data processing.
+</para>
+
+<para>
+At most one error is generated per request. If more than one error condition
+is encountered in processing a request, the choice of which error is returned
+is implementation-dependent.
+</para>
+
+<literallayout class="monospaced">
+XIM_ERROR (IM Server <--> IM library)
+<!-- .sp 6p -->
+ 2 CARD16 input-method-ID
+ 2 CARD16 input-context-ID
+ 2 BITMASK16 flag (*1)
+ #0000 Both Input-Method-ID and Input-Context-ID are invalid
+ #0001 Input-Method-ID is valid
+ #0002 Input-Context-ID is valid
+ 2 CARD16 Error Code
+ #1 BadAlloc
+ #2 BadStyle
+ #3 BadClientWindow
+ #4 BadFocusWindow
+ #5 BadArea
+ #6 BadSpotLocation
+ #7 BadColormap
+ #8 BadAtom
+ #9 BadPixel
+ #10 BadPixmap
+ #11 BadName
+ #12 BadCursor
+ #13 BadProtocol
+ #14 BadForeground
+ #15 BadBackground
+ #16 LocaleNotSupported
+ #999 BadSomething (*2)
+ 2 n byte length of error detail.
+ 2 CARD16 type of error detail (*3)
+ n STRING8 error detail (*4)
+ p unused, p = Pad(n)
+
+(*1) Before an IM is created, both Input-Method-ID and
+ Input-Context-ID are invalid.
+ Before an IC is created, only Input-Method-ID is valid.
+ After that, both of Input-Method-ID and Input-Context-ID are valid.
+
+(*2) Unspecific error, for example "language engine died"
+
+(*3) This field is reserved for future use.
+
+(*4) Vendor defined detail error message
+</literallayout>
+</sect2>
+
+<sect2 id="Connection_Establishment">
+<title>Connection Establishment</title>
+<!-- .XS -->
+<!-- (SN Connection Establishment -->
+<!-- .XE -->
+<para>
+<function>XIM_CONNECT</function>
+message requests to establish a connection over a mutually-understood virtual
+stream.
+</para>
+
+<literallayout class="monospaced">
+XIM_CONNECT (IM library -> IM Server)
+ 1 byte order
+ #x42 MSB first
+ #x6c LSB first
+ 1 unused
+ 2 CARD16 client-major-protocol-version (*1)
+ 2 CARD16 client-minor-protocol-version (*1)
+ 2 CARD16 number of client-auth-protocol-names
+ n LISTofSTRING client-auth-protocol-names
+
+(*1) Specify the version of IM Protocol that the client supports.
+</literallayout>
+
+<para>
+A client must send
+<function>XIM_CONNECT</function>
+message as the first message on the connection.
+The list specifies the names of authentication protocols the sending
+IM Server is willing to perform.
+(If the client need not authenticate, the list may be omitted.)
+</para>
+
+<para>
+<function>XIM_AUTH_REQUIRED </function>
+message is used to send the authentication protocol name and protocol-specific
+data.
+</para>
+
+<literallayout class="monospaced">
+XIM_AUTH_REQUIRED (IM library <--> IM Server)
+
+ 1 CARD8 auth-protocol-index
+ 3 unused
+ 2 n length of authentication data
+ 2 unused
+ n <varies> data
+ p unused, p = Pad(n)
+</literallayout>
+
+<para>
+The auth-protocol is specified by an index into the list of names
+given in the
+<function>XIM_CONNECT</function>
+or
+<function>XIM_AUTH_SETUP</function>
+message. Any protocol-specific data that might be required is also sent.
+</para>
+
+<para>
+The IM library sends
+<function>XIM_AUTH_REPLY</function>
+message as the reply to
+<function>XIM_AUTH_REQUIRED</function>
+message, if the IM Server is authenticated.
+</para>
+
+<literallayout class="monospaced">
+XIM_AUTH_REPLY (IM library -> IM Server)
+ 2 n length of authentication data
+ 2 unused
+ 2 n length of authentication data
+ 2 unused
+ n <varies> data
+ p unused, p = Pad(n)
+</literallayout>
+
+<para>
+The auth data is specific to the authentication protocol in use.
+</para>
+<para>
+<!-- .LP -->
+<function>XIM_AUTH_NEXT </function>
+message requests to send more auth data.
+</para>
+
+<literallayout class="monospaced">
+XIM_AUTH_NEXT (IM library <--> IM Server)
+ 2 n length of authentication data
+ 2 unused
+ n <varies> data
+ p unused, p = Pad(n)
+</literallayout>
+<para>
+The auth data is specific to the authentication protocol in use.
+</para>
+
+<para>
+<!-- .LP -->
+The IM Server sends
+<function>XIM_AUTH_SETUP</function>
+message to authenticate the client.
+</para>
+
+<literallayout class="monospaced">
+XIM_AUTH_SETUP (IM Server -> IM library)
+ 2 CARD16 number of client-auth-protocol-names
+ 2 unused
+ n LISTofSTRING server-auth-protocol-names
+</literallayout>
+
+<para>
+The list specifies the names of authentication protocols the
+client is willing to perform.
+</para>
+
+<para>
+<function>XIM_AUTH_NG</function>
+message requests to give up the connection.
+</para>
+
+<para>
+XIM_AUTH_NG (IM library <--> IM Server)
+</para>
+
+<para>
+The IM Server sends
+<function>XIM_CONNECT_REPLY</function>
+message as the reply to
+<function>XIM_CONNECT</function>
+or
+<function>XIM_AUTH_REQUIRED</function>
+message.
+</para>
+
+<literallayout class="monospaced">
+XIM_CONNECT_REPLY (IM Server -> IM library)
+ 2 CARD16 server-major-protocol-version (*1)
+ 2 CARD16 server-minor-protocol-version (*1)
+
+(*1) Specify the version of IM Protocol that the IM Server supports.
+This document specifies major version one, minor version zero.
+</literallayout>
+
+<para>
+Here are the state diagrams for the client and the IM Server.
+</para>
+
+<para>
+State transitions for the client
+</para>
+
+<variablelist>
+ <varlistentry>
+ <term><emphasis remap='I'>init_status</emphasis>:</term>
+ <listitem>
+ <para>
+Use authorization function -> <emphasis remap='I'>client_ask</emphasis>
+ </para>
+ <para>
+Not use authorization function -> <emphasis remap='I'>client_no_check</emphasis>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis remap='I'>start</emphasis>:</term>
+ <listitem>
+ <para>
+Send <function>XIM_CONNECT</function>
+ </para>
+ <para>
+If <emphasis remap='I'>client_ask</emphasis> -> <emphasis remap='I'>client_wait1</emphasis>
+ </para>
+ <para>
+If <emphasis remap='I'>client_no_check</emphasis>,
+client-auth-protocol-names may be omitted -> <emphasis remap='I'>client_wait2</emphasis>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis remap='I'>client_wait1</emphasis>:</term>
+ <listitem>
+ <para>
+Receive <function>XIM_AUTH_REQUIRED</function>
+-> <emphasis remap='I'>client_check</emphasis>
+ </para>
+ <para>
+Receive <other> -> <emphasis remap='I'>client_NG</emphasis>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis remap='I'>client_check</emphasis>:</term>
+ <listitem>
+ <para>
+If no more auth needed, send <function>XIM_AUTH_REPLY</function>
+-> <emphasis remap='I'>client_wait2</emphasis>
+ </para>
+ <para>
+If good auth data, send <function>XIM_AUTH_NEXT</function>
+-> <emphasis remap='I'>client_wait1</emphasis>
+ </para>
+ <para>
+If bad auth data, send <function>XIM_AUTH_NG</function>
+-> give up on this protocol
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis remap='I'>client_wait2</emphasis>:</term>
+ <listitem>
+ <para>
+Receive <function>XIM_CONNECT_REPLY</function>
+-> connect Receive
+<function>XIM_AUTH_SETUP </function>
+-> <emphasis remap='I'>client_more</emphasis>
+ </para>
+ <para>
+Receive <function>XIM_AUTH_NEXT</function>
+-> <emphasis remap='I'>client_more</emphasis>
+ </para>
+ <para>
+Receive <function>XIM_AUTH_NG</function>
+-> give up on this protocol
+ </para>
+ <para>
+Receive <other> -> <emphasis remap='I'>client_NG</emphasis>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis remap='I'>client_more</emphasis>:</term>
+ <listitem>
+ <para>
+Send <function>XIM_AUTH_REQUIRED</function>
+-> <emphasis remap='I'>client_wait2</emphasis>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis remap='I'>client_NG</emphasis>:</term>
+ <listitem>
+ <para>
+Send <function>XIM_AUTH_NG</function>
+-> give up on this protocol
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+State transitions for the IM Server
+</para>
+
+<variablelist>
+ <varlistentry>
+ <term><emphasis remap='I'>init_status</emphasis>:</term>
+ <listitem>
+ <para>
+Use authorization function -> <emphasis remap='I'>server_ask</emphasis>
+ </para>
+ <para>
+Not use authorization function -> <emphasis remap='I'>server_no_check</emphasis>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis remap='I'>start</emphasis>:</term>
+ <listitem>
+ <para>
+Receive <function>XIM_CONNECT</function>
+ </para>
+ <para>
+-> <emphasis remap='I'>start2</emphasis>
+Receive <other> -> <emphasis remap='I'>server_NG</emphasis>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis remap='I'>start2</emphasis>:</term>
+ <listitem>
+ <para>
+If <emphasis remap='I'>client_ask</emphasis>, send
+<function>XIM_AUTH_REQUIRED</function>
+-> <emphasis remap='I'>server_wait1</emphasis>
+ </para>
+ <para>
+If <emphasis remap='I'>client_no_check</emphasis> and
+<emphasis remap='I'>server_ask</emphasis>, send
+<function>XIM_AUTH_SETUP</function>
+-> <emphasis remap='I'>server_wait2</emphasis>
+ </para>
+ <para>
+If <emphasis remap='I'>client_no_check</emphasis> and
+<emphasis remap='I'>server_no_check</emphasis>, send
+<function>XIM_CONNECT_REPLY</function>
+-> connect
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis remap='I'>server_wait1</emphasis>:</term>
+ <listitem>
+ <para>
+Receive
+<function>XIM_AUTH_REPLY</function>
+-> <emphasis remap='I'>server2</emphasis>
+ </para>
+ <para>
+Receive
+<function>XIM_AUTH_NEXT</function>
+-> <emphasis remap='I'>server_more</emphasis>
+ </para>
+ <para>
+Receive <other> -> <emphasis remap='I'>server_NG</emphasis>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis remap='I'>server_more</emphasis></term>
+ <listitem>
+ <para>
+Send
+<function>XIM_AUTH_REQUIRED</function>
+-> <emphasis remap='I'>server_wait1</emphasis>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis remap='I'>server2</emphasis></term>
+ <listitem>
+ <para>
+If <emphasis remap='I'>server_ask</emphasis>, send
+<function>XIM_AUTH_SETUP</function>
+-> <emphasis remap='I'>server_wait2</emphasis>
+ </para>
+ <para>
+If <emphasis remap='I'>server_no_check</emphasis>, send
+<function>XIM_CONNECT_REPLY </function>
+-> connect
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis remap='I'>server_wait2</emphasis></term>
+ <listitem>
+ <para>
+Receive
+<function>XIM_AUTH_REQUIRED</function>
+-> <emphasis remap='I'>server_check</emphasis>
+ </para>
+ <para>
+Receive <other> -> <emphasis remap='I'>server_NG</emphasis>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis remap='I'>server_check</emphasis></term>
+ <listitem>
+ <para>
+If no more auth data, send
+<function>XIM_CONNECT_REPLY</function>
+-> connect
+ </para>
+ <para>
+If bad auth data, send
+<function>XIM_AUTH_NG</function>
+-> give up on this protocol
+ </para>
+ <para>
+If good auth data, send
+<function>XIM_AUTH_NEXT</function>
+-> <emphasis remap='I'>server_wait2</emphasis>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis remap='I'>server_NG</emphasis></term>
+ <listitem>
+ <para>
+Send
+<function>XIM_AUTH_NG</function>
+-> give up on this protocol
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<function>XIM_DISCONNECT </function>
+message requests to shutdown the connection over a mutually-understood
+virtual stream.
+</para>
+
+<para>
+XIM_DISCONNECT (IM library -> IM Server)
+</para>
+
+<para>
+<function>XIM_DISCONNECT</function>
+is a synchronous request. The IM library should wait until it receives
+either an
+<function>XIM_DISCONNECT_REPLY</function>
+packet or an <function>XIM_ERROR</function> packet.
+</para>
+
+<para>
+XIM_DISCONNECT_REPLY (IM Server -> IM library)
+</para>
+
+<para>
+<function>XIM_OPEN</function>
+requests to establish a logical connection between the IM library and the IM
+Server.
+</para>
+
+<literallayout class="monospaced">
+XIM_OPEN (IM library -> IM Server)
+ n STR locale name
+ p unused, p = Pad(n)
+</literallayout>
+
+<para>
+<function>XIM_OPEN</function>
+is a synchronous request. The IM library should wait until receiving
+either an <function>XIM_OPEN_REPLY</function>
+packet or an <function>XIM_ERROR </function> packet.
+</para>
+
+<literallayout class="monospaced">
+XIM_OPEN_REPLY (IM Server -> IM library)
+ 2 CARD16 input-method-ID
+ 2 n byte length of IM attributes supported
+ n LISTofXIMATTR IM attributes supported
+ 2 m byte length of IC attributes supported
+ 2 CARD16 unused
+ m LISTofXICATTR IC attributes supported
+</literallayout>
+
+<para>
+<function>XIM_OPEN_REPLY</function>
+message returns all supported IM and IC attributes in LISTofXIMATTR and
+LISTofXICATTR. These IM and IC attribute IDs are used to reduce the amount
+of data which must be transferred via the network. In addition, this
+indicates to the IM library what kinds of IM/IC attributes can be used
+in this session, and what types of data will be exchanged. This allows
+the IM Server provider and application writer to support IM system
+enhancements with new IM/IC attributes, without modifying Xlib.
+The IC value for the separator of NestedList must be included in the
+LISTofXICATTR.
+</para>
+
+<para>
+<function>XIM_CLOSE </function>
+message requests to shutdown the logical connection between the IM library
+and the IM Server.
+</para>
+
+<literallayout class="monospaced">
+XIM_CLOSE (IM library -> IM Server)
+ 2 CARD16 input-method-ID
+ 2 unused
+</literallayout>
+
+<para>
+<function>XIM_CLOSE</function>
+is a synchronous request. The IM library should wait until receiving
+either an <function>XIM_CLOSE_REPLY</function>
+packet or an <function>XIM_ERROR</function> packet.
+</para>
+
+<literallayout class="monospaced">
+XIM_CLOSE_REPLY (IM Server -> IM library)
+ 2 CARD16 input-method-ID
+ 2 unused
+</literallayout>
+
+</sect2>
+
+<sect2 id='Event_Flow_Control_2'>
+<title>Event Flow Control</title>
+<!-- .XS -->
+<!-- (SN Event Flow Control -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+An IM Server must send
+<function>XIM_SET_EVENT_MASK </function>
+message to the IM library in order for events to be forwarded to the IM
+Server, since the IM library initially doesn't forward any events to the
+IM Server. In the protocol, the IM Server will specify masks of X events
+to be forwarded and which need to be synchronized by the IM library.
+</para>
+
+<literallayout class="monospaced">
+XIM_SET_EVENT_MASK (IM Server -> IM library)
+ 2 CARD16 input-method-ID
+ 2 CARD16 input-context-ID
+ 4 EVENTMASK forward-event-mask (*1)
+ 4 EVENTMASK synchronous-event-mask (*2)
+
+(*1) Specify all the events to be forwarded to the IM Server by the IM library.
+(*2) Specify the events to be forwarded with synchronous flag on by the IM library.
+</literallayout>
+
+<para>
+<function>XIM_SET_EVENT_MASK </function>
+is an asynchronous request. The event masks are valid immediately after
+they are set until changed by another
+<function>XIM_SET_EVENT_MASK</function>
+message. If input-context-ID is set to zero, the default value of the
+input-method-ID will be changed to the event masks specified in the request.
+That value will be used for the IC's which have no individual values.
+</para>
+
+<para>
+Using the Dynamic Event Flow model, an IM Server sends
+<function>XIM_REGISTER_TRIGGERKEYS </function>
+message to the IM library before sending
+<function>XIM_OPEN_REPLY</function>
+message.
+Or the IM library may suppose that the IM Server uses the Static Event Flow
+model.
+</para>
+
+<literallayout class="monospaced">
+XIM_REGISTER_TRIGGERKEYS (IM Server -> IM library)
+<!-- .sp 6p -->
+ 2 CARD16 input-method-ID
+ 2 unused
+ 4 n byte length of on-keys
+ n LISTofXIMTRIGGERKEY on-keys list
+ 4 m byte length of off-keys
+ m LISTofXIMTRIGGERKEY off-keys list
+</literallayout>
+
+<para>
+<function>XIM_REGISTER_TRIGGERKEYS</function>
+is an asynchronous request.
+The IM Server notifys the IM library of on-keys and off-keys lists with
+this message.
+</para>
+
+<para>
+The IM library notifys the IM Server with
+<function>XIM_TRIGGER_NOTIFY </function>
+message that a key event matching either on-keys or off-keys has been occurred.
+</para>
+
+<literallayout class="monospaced">
+XIM_TRIGGER_NOTIFY (IM library -> IM Server)
+ 2 CARD16 input-method-ID
+ 2 CARD16 input-context-ID
+ 4 CARD32 flag
+ #0 on-keys list
+ #1 off-keys list
+ 4 CARD32 index of keys list
+ 4 EVENTMASK client-select-event-mask (*1)
+
+(*1) Specify the events currently selected by the IM library with XSelectInput.
+
+</literallayout>
+
+<para>
+<function>XIM_TRIGGER_NOTIFY </function>
+is a synchronous request. The IM library should wait until receiving
+either an <function>XIM_TRIGGER_NOTIFY_REPLY</function>
+packet or an <function>XIM_ERROR</function> packet.
+</para>
+
+<literallayout class="monospaced">
+XIM_TRIGGER_NOTIFY_REPLY (IM Server -> IM library)
+ 2 CARD16 input-method-ID
+ 2 CARD16 input-context-ID
+</literallayout>
+
+</sect2>
+
+<sect2 id="Encoding_Negotiation">
+<title>Encoding Negotiation</title>
+<para>
+<function>XIM_ENCODING_NEGOTIATION</function>
+message requests to decide which encoding to be sent across the wire.
+When the negotiation fails, the fallback default encoding is Portable
+Character Encoding.
+</para>
+
+<literallayout class="monospaced">
+XIM_ENCODING_NEGOTIATION (IM library -> IM Server).sp 6p
+ 2 CARD16 input-method-ID
+ 2 n byte length of encodings listed by name
+ n LISTofSTR list of encodings supported in the IM library.
+ p unused, p = Pad(n)
+ 2 m byte length of encodings listed by detailed data
+ 2 unused
+ m LISTofENCODINGINFO list of encodings supported in the IM library
+</literallayout>
+
+<para>
+The IM Server must choose one encoding from the list sent by the IM library.
+If index of the encoding determined is -1 to indicate that the negotiation
+is failed, the fallback default encoding is used.
+The message must be issued after sending
+<function>XIM_OPEN</function> message via XOpenIM().
+The name of encoding may be registered with X Consortium.
+</para>
+
+<para>
+<function>XIM_ENCODING_NEGOTIATION</function>
+is a synchronous request. The IM library should wait until receiving
+either an <function>XIM_ENCODING_NEGOTIATION_REPLY</function>
+packet or an <function>XIM_ERROR</function> packet.
+</para>
+
+
+<literallayout class="monospaced">
+XIM_ENCODING_NEGOTIATION_REPLY (IM Server -> IM library)
+ 2 CARD16 input-method-ID
+ 2 CARD16 category of the encoding determined.
+ #0 name
+ #1 detailed data
+ 2 INT16 index of the encoding determined.
+ 2 unused
+</literallayout>
+
+</sect2>
+
+<sect2 id="Query_the_supported_extension_protocol_list">
+<title>Query the supported extension protocol list</title>
+<para>
+<function>XIM_QUERY_EXTENSION</function>
+message requests to query the IM extensions supported by the IM Server to
+which the client is being connected.
+</para>
+
+<literallayout class="monospaced">
+XIM_QUERY_EXTENSION (IM library -> IM Server)
+ 2 CARD16 input-method-ID
+ 2 n byte length of extensions supported by the IM library
+ n LISTofSTR extensions supported by the IM library
+ p unused, p = Pad(n)
+</literallayout>
+
+<para>
+An example of a supported extension is FrontEnd.
+The message must be issued after sending
+<function>XIM_OPEN </function> message via XOpenIM().
+</para>
+
+<para>
+If n is 0, the IM library queries the IM Server for all extensions.
+</para>
+
+<para>
+If n is not 0, the IM library queries whether the IM Server supports the
+contents specified in the list.
+</para>
+
+<para>
+If a client uses an extension request without previously having issued a
+<function>XIM_QUERY_EXTENSION</function>
+message for that extension, the IM Server responds with a
+<function>BadProtocol</function>
+error. If the IM Server encounters a request with an unknown MAJOR-OPCODE
+or MINOR-OPCODE, it responds with a
+<function>BadProtocol</function> error.
+</para>
+
+<para>
+<function>XIM_QUERY_EXTENSION</function>
+is a synchronous request. The IM library should wait until receiving
+either an <function>XIM_QUERY_EXTENSION_REPLY</function>
+packet or an <function>XIM_ERROR</function> packet.
+</para>
+
+<literallayout class="monospaced">
+XIM_QUERY_EXTENSION_REPLY (IM Server -> IM library)
+ 2 CARD16 input-method-ID
+ 2 n byte length of extensions supported by both the IM library and the IM Server
+ n LISTofEXT list of extensions supported by both the IM library and the IM Server
+
+</literallayout>
+
+<para>
+<function>XIM_QUERY_EXTENSION_REPLY</function>
+message returns the list of extensions supported by both the IM library and
+the IM Server. If the list passed in
+<function>XIM_QUERY_EXTENSION</function>
+message is NULL, the IM Server returns the full list of extensions supported
+by the IM Server. If the list is not NULL, the IM Server returns the
+extensions in the list that are supported by the IM Server.
+</para>
+
+<para>
+<!-- .LP -->
+A zero-length string is not a valid extension name. The IM library should
+disregard any zero-length strings that are returned in the extension list.
+The IM library does not use the requests which are not supported by the IM
+Server.
+</para>
+
+</sect2>
+
+<sect2 id="Setting_IM_Values">
+<title>Setting IM Values</title>
+<para>
+<function>XIM_SET_IM_VALUES </function>
+requests to set attributes to the IM.
+</para>
+
+<literallayout class="monospaced">
+XIM_SET_IM_VALUES (IM library -> IM Server)
+ 2 CARD16 input-method-ID
+ 2 n byte length of im-attribute
+ n LISTofXIMATTRIBUTE im-attributes
+</literallayout>
+
+<para>
+The im-attributes in
+<function>XIM_SET_IM_VALUES</function>
+message are specified as a LISTofXIMATTRIBUTE, specifying the attributes
+to be set. Attributes other than the ones returned by
+<function>XIM_OPEN_REPLY</function>
+message should not be specified.
+</para>
+
+<para>
+<function>XIM_SET_IM_VALUES </function>
+is a synchronous request. The IM library should wait until receiving
+either an
+<function>XIM_SET_IM_VALUES_REPLY</function>
+packet or an
+<function>XIM_ERROR</function>
+packet, because it must receive the error attribute if
+<function>XIM_ERROR</function> message is returned.
+</para>
+
+<literallayout class="monospaced">
+XIM_SET_IM_VALUES_REPLY (IM Server -> IM library)
+ 2 CARD16 input-method-ID
+ 2 unused
+</literallayout>
+
+<para>
+<function>XIM_SET_IM_VALUES_REPLY</function>
+message returns the input-method-ID to distinguish replies from multiple IMs.
+</para>
+
+</sect2>
+<sect2 id="Getting_IM_Values">
+<title>Getting IM Values</title>
+<para>
+<function>XIM_GET_IM_VALUES </function>
+requests to query IM values supported by the IM Server currently being
+connected.
+</para>
+
+<literallayout class="monospaced">
+XIM_GET_IM_VALUES (IM library -> IM Server)
+ 2 CARD16 input-method-ID
+ 2 n byte length of im-attribute-id
+ n LISTofCARD16 im-attribute-id
+ p unused, p=Pad(n)
+</literallayout>
+
+<para>
+<function>XIM_GET_IM_VALUES</function>
+is a synchronous request. The IM library should wait until it receives
+either an
+<function>XIM_GET_IM_VALUES_REPLY</function>
+packet or an <function>XIM_ERROR</function> packet.
+</para>
+
+<literallayout class="monospaced">
+XIM_GET_IM_VALUES_REPLY (IM Server -> IM library)
+ 2 CARD16 input-method-ID
+ 2 n byte length of im-attributes returned
+ n LISTofXIMATTRIBUTE im-attributes returned
+</literallayout>
+
+<para>
+The IM Server returns IM values with
+<function>XIM_GET_IM_VALUES_REPLY</function>
+message. The order of the returned im-attribute values corresponds directly
+to that of the list passed with the
+<function>XIM_GET_IM_VALUES</function> message.
+</para>
+
+</sect2>
+<sect2 id="Creating_an_IC">
+<title>Creating an IC</title>
+<para>
+<function>XIM_CREATE_IC</function> message requests to create an IC.
+</para>
+
+<literallayout class="monospaced">
+XIM_CREATE_IC (IM library -> IM Server)
+ 2 CARD16 input-method-ID
+ 2 n byte length of ic-attributes
+ n LISTofXICATTRIBUTE ic-attributes
+</literallayout>
+
+<para>
+The input-context-id is specified by the IM Server to identify the client
+(IC). (It is not specified by the client in
+<function>XIM_CREATE_IC</function>
+message.), and it should not be set to zero.
+</para>
+
+<para>
+<function>XIM_CREATE_IC</function>
+is a synchronous request which returns the input-context-ID.
+The IM library should wait until it receives either an
+<function>XIM_CREATE_IC_REPLY</function>
+packet or an
+<function>XIM_ERROR</function>
+packet.
+</para>
+
+<literallayout class="monospaced">
+XIM_CREATE_IC_REPLY (IM Server -> IM library)
+ 2 CARD16 input-method-ID
+ 2 CARD16 input-context-ID
+</literallayout>
+
+</sect2>
+<sect2 id="Destroying_the_IC">
+<title>Destroying the IC</title>
+<para>
+<function>XIM_DESTROY_IC</function>
+message requests to destroy the IC.
+</para>
+
+<literallayout class="monospaced">
+XIM_DESTROY_IC (IM library -> IM Server)
+ 2 CARD16 input-method-ID
+ 2 CARD16 input-context-ID
+</literallayout>
+
+<para>
+<function>XIM_DESTROY_IC </function>
+is a synchronous request. The IM library should not free its resources
+until it receives an
+<function>XIM_DESTROY_IC_REPLY</function>
+message because <function>XIM_DESTROY_IC</function>
+message may result in Callback packets such as
+<function>XIM_PREEDIT_DRAW</function>
+and <function>XIM_PREEDIT_DONE.</function>
+</para>
+
+<literallayout class="monospaced">
+XIM_DESTROY_IC_REPLY (IM Server -> IM library)
+ 2 CARD16 input-method-ID
+ 2 CARD16 input-context-ID
+</literallayout>
+
+</sect2>
+
+<sect2 id="Setting_IC_Values">
+<title>Setting IC Values</title>
+<para>
+<function>XIM_SET_IC_VALUES</function>
+messages requests to set attributes to the IC.
+</para>
+
+
+<literallayout class="monospaced">
+XIM_SET_IC_VALUES (IM library -> IM Server)
+ 2 CARD16 input-method-ID
+ 2 CARD16 input-context-ID
+ 2 n byte length of ic-attributes
+ 2 unused
+ n LISTofXICATTRIBUTE ic-attributes
+</literallayout>
+
+<para>
+The ic-attributes in
+<function>XIM_SET_IC_VALUES</function>
+message are specified as a LISTofXICATTRIBUTE, specifying the attributes
+to be set. Attributes other than the ones returned by
+<function>XIM_OPEN_REPLY</function> message should not be specified.
+</para>
+
+<para>
+<function>XIM_SET_IC_VALUES </function>
+is a synchronous request. The IM library should wait until receiving
+either an <function>XIM_SET_IC_VALUES_REPLY </function>
+packet or an <function>XIM_ERROR</function>
+packet, because it must receive the error attribute if
+<function>XIM_ERROR</function> message is returned.
+</para>
+
+
+<literallayout class="monospaced">
+XIM_SET_IC_VALUES_REPLY (IM Server -> IM library)
+<!-- .sp 6p -->
+ 2 CARD16 input-method-ID
+ 2 CARD16 input-context-ID
+</literallayout>
+
+</sect2>
+<sect2 id="Getting_IC_Values">
+<title>Getting IC Values</title>
+<para>
+<function>XIM_GET_IC_VALUES</function>
+message requests to query IC values supported by the IM Server currently
+being connected.
+</para>
+
+
+<literallayout class="monospaced">
+XIM_GET_IC_VALUES (IM library -> IM Server)
+<!-- .sp 6p -->
+ 2 CARD16 input-method-ID
+ 2 CARD16 input-context-ID
+ 2 n byte length of ic-attribute-id
+ n LISTofCARD16 ic-attribute-id
+ p unused, p=Pad(2+n)
+</literallayout>
+
+<para>
+In LISTofCARD16, the appearance of the ic-attribute-id for the separator
+of NestedList shows the end of the heading nested list.
+</para>
+
+<para>
+<function>XIM_GET_IC_VALUES</function>
+is a synchronous request and returns each attribute with its values to
+show the correspondence. The IM library should wait until receiving
+either an <function>XIM_GET_IC_VALUES_REPLY</function>
+packet or an <function>XIM_ERROR</function> packet.
+</para>
+
+<literallayout class="monospaced">
+XIM_GET_IC_VALUES_REPLY (IM Server -> IM library)
+ 2 CARD16 input-method-ID
+ 2 CARD16 input-context-ID
+ 2 n byte length of ic-attribute
+ 2 unused
+ n LISTofXICATTRIBUTE ic-attribute
+</literallayout>
+
+</sect2>
+<sect2 id="Setting_IC_Focus">
+<title>Setting IC Focus</title>
+<para>
+<function>XIM_SET_IC_FOCUS</function>
+message requests to set the focus to the IC.
+</para>
+
+<literallayout class="monospaced">
+XIM_SET_IC_FOCUS (IM library -> IM Server)
+ 2 CARD16 input-method-ID
+ 2 CARD16 input-context-ID
+</literallayout>
+
+<para>
+<function>XIM_SET_IC_FOCUS</function> is an asynchronous request.
+</para>
+
+</sect2>
+<sect2 id="Unsetting_IC_Focus">
+<title>Unsetting IC Focus</title>
+<para>
+<function>XIM_UNSET_IC_FOCUS</function>
+message requests to unset the focus to the focused IC.
+</para>
+
+<literallayout class="monospaced">
+XIM_UNSET_IC_FOCUS (IM library -> IM Server)
+ 2 CARD16 input-method-ID
+ 2 CARD16 input-context-ID
+</literallayout>
+
+<para>
+<function>XIM_UNSET_IC_FOCUS</function>
+is an asynchronous request.
+</para>
+
+</sect2>
+
+<sect2 id='Filtering_Events'>
+<title>Filtering Events</title>
+<para>
+Event filtering is mainly provided for BackEnd method to allow input method
+to capture X events transparently to clients.
+</para>
+
+<para>
+X Events are forwarded by
+<function>XIM_FORWARD_EVENT</function> message.
+This message can be operated both synchronously and asynchronously.
+If the requester sets the synchronous flag, the receiver must send
+<function>XIM_SYNC_REPLY</function>
+message back to the requester when all the data processing is done.
+</para>
+<para>
+Protocol flow of BackEnd model
+</para>
+
+<para>
+With BackEnd method, the protocol flow can be classified into two
+methods in terms of synchronization, depending on the synchronous-eventmask
+of <function>XIM_SET_EVENT_MASK</function>
+message. One can be called on-demand-synchronous method and another
+can be called as full-synchronous method.
+</para>
+
+<para>
+In on-demand-synchronous method, the IM library always receives
+<function>XIM_FORWARD_EVENT</function>
+or
+<function>XIM_COMMIT</function>
+message as a synchronous request. Also, the IM Server needs to synchronously
+process the correspondent reply from the IM library and the following
+<function>XIM_FORWARD_EVENT</function>
+message sent from the IM library when any of the event causes the IM Server
+to send
+<function>XIM_FORWARD_EVENT</function>
+or
+<function>XIM_COMMIT</function>
+message to the IM library, so that the input service is consistent. If the
+IM library gets the control back from the application after receiving the
+synchronous request, the IM library replies for the synchronous request before
+processing any of the events. In this time, the IM Server blocks
+<function>XIM_FORWARD_EVENT</function>
+message which is sent by the IM library, and handles it after receiving the
+reply. However, the IM Server handles the other protocols at any time.
+</para>
+
+<para>
+In full-synchronous method, the IM library always sends
+<function>XIM_FORWARD_EVENT</function>
+message to the IM Server as a synchronous request. Therefore, the reply to it
+from the IM Server will be put between the
+<function>XIM_FORWARD_EVENT</function> message and its
+<function>XIM_SYNC_REPLY</function> message. In case of sending
+<function>XIM_FORWARD_EVENT</function> or
+<function>XIM_COMMIT</function>
+message, the IM Server should set the synchronous flag off. Because the
+synchronization can be done by the following
+<function>XIM_SYNC_REPLY</function> message.
+</para>
+
+<para>
+Following chart shows one of the simplest protocol flow which only
+deals with keyevents for preediting operation.
+</para>
+
+<mediaobject id="sampleprotocolflow">
+ <imageobject>
+ <imagedata format="SVG" fileref="sampleprotocolflow1.svg"/>
+ </imageobject>
+ <caption>Sample Protocol Flow</caption>
+</mediaobject>
+
+
+<para>
+Following chart shows one of the complex protocol flow, which deals
+with multiple focus windows and button press event as well as keyevent,
+and the focus is moved by the application triggered by both of keyevent
+and button press event.
+</para>
+<mediaobject id="sampleprotocolflow2">
+ <imageobject>
+ <imagedata format="SVG" fileref="sampleprotocolflow2.svg"/>
+ </imageobject>
+ <caption>Sample Protocol Flow 2</caption>
+</mediaobject>
+
+<literallayout class="monospaced">
+XIM_FORWARD_EVENT (IM library <--> IM Server)
+ 2 CARD16 input-method-ID
+ 2 CARD16 input-context-ID
+ 2 BITMASK16 flag
+ #0001 synchronous
+ #0002 request filtering (*1)
+ #0004 request lookupstring (*2)
+ 2 CARD16 serial number
+ XEVENT X event
+
+(*1) Indicate the receiver should filter events and possible preedit may be invoked.
+
+(*2) Indicate the receiver should only do lookup string. The IM Server is expected
+to just do a conversion of the key event to the best candidate. This bit may
+affect the state of the preedit state (e.g. compose of dead key sequences).
+</literallayout>
+
+<para>
+XEVENT format is same as the X Protocol event format(xEvent).
+As the value of xEvent's sequenceNumber is the bottom of 16 bit of XEvent's
+xany.serial, the top of 16 bit is sent by serial number(INT16).
+</para>
+
+<para>
+<function>XIM_FORWARD_EVENT</function>
+message is used for forwarding the events from the IM library to the IM Server
+in order for IM to be able to filter the event. On the other hand, this
+message is also used for forwarding the events from the IM Server to the IM
+library if the event forwarded from the IM library is not filtered.
+The IM Server, which receives
+<function>XIM_FORWARD_EVENT</function>
+message without synchronous bit, should set synchronous bit.
+If both "request event filtering" and "request lookupstring" flag are
+set, then both filtering and lookup should be done for the same event.
+</para>
+
+</sect2>
+
+<sect2 id="Synchronizing_with_the_IM_Server">
+<title>Synchronizing with the IM Server</title>
+
+<para>
+<function>XIM_SYNC</function>
+message requests to synchronize the IM library and the IM Server.
+</para>
+
+<literallayout class="monospaced">
+XIM_SYNC (IM library <--> IM Server)
+ 2 CARD16 input-method-ID
+ 2 CARD16 input-context-ID
+</literallayout>
+
+<para>
+This synchronization can be started either on the IM library side or on the
+IM Server side. The side which receives
+<function>XIM_SYNC</function>
+message should process all XIM requests before replying. The input-context-ID
+is necessary to distinguish the IC with which the IM library and the IM
+Server are synchronized.
+</para>
+
+<literallayout class="monospaced">
+XIM_SYNC_REPLY (IM Server <--> IM library)
+ 2 CARD16 input-method-ID
+ 2 CARD16 input-context-ID
+</literallayout>
+
+
+
+<para>
+The side which receives
+<function>XIM_FORWARD_EVENT, </function>
+<function>XIM_COMMIT</function>
+or any other message with synchronous bit, should process all XIM request
+before replying, and send
+<function>XIM_SYNC_REPLY</function>
+message as the reply to the previous message.
+</para>
+
+</sect2>
+
+<sect2 id="Sending_a_committed_string">
+<title>Sending a committed string</title>
+<para>
+When the IM Server commits a string, the IM Server sends either the committed
+string or list of KeySym, or both, by
+<function>XIM_COMMIT</function>
+message.
+</para>
+
+<literallayout class="monospaced">
+XIM_COMMIT (IM Server -> IM library)
+
+ 2 CARD16 input-method-ID
+ 2 CARD16 input-context-ID
+ 2 BITMASK16 flag
+ #0001 synchronous
+ #0002 XLookupChars
+ #0004 XLookupKeySym
+ #0006 XLookupBoth = XLookupChars | XLookupKeySym
+</literallayout>
+
+<para>
+If flag is XLookupKeySym, the arguments continue as follows:
+</para>
+
+<literallayout class="monospaced">
+ 2 unused
+ 4 KEYSYM KeySym
+</literallayout>
+
+<para>
+If flag is XLookupChars, the arguments continue as follows
+</para>
+
+<literallayout class="monospaced">
+ 2 m byte length of committed string
+ m LISTofBYTE committed string
+ p unused, p = Pad(m)
+</literallayout>
+
+<para>
+If flag is XLookupBoth, the arguments continue as follows
+</para>
+
+<literallayout class="monospaced">
+ 2 unused
+ 4 KEYSYM KeySym
+ 2 n byte length of committed string
+ n LISTofBYTE committed string
+ p unused, p = Pad(2+n)
+</literallayout>
+
+<para>
+The IM Server which receives
+<function>XIM_COMMIT</function>
+message without synchronous bit should set synchronous bit.
+</para>
+
+</sect2>
+
+<sect2 id="Reset_IC">
+<title>Reset IC</title>
+<para>
+<function>XIM_RESET_IC</function>
+message requests to reset the status of IC in the IM Server.
+</para>
+
+<literallayout class="monospaced">
+XIM_RESET_IC (IM library -> IM Server)
+ 2 CARD16 input-method-ID
+ 2 CARD16 input-context-ID
+</literallayout>
+
+
+<para>
+<function>XIM_RESET_IC</function>
+is a synchronous request. The IM library should wait until receiving either an
+<function>XIM_RESET_IC_REPLY</function> packet or an
+<function>XIM_ERROR</function> packet.
+</para>
+
+<literallayout class="monospaced">
+XIM_RESET_IC_REPLY (IM Server -> IM library)
+
+ 2 CARD16 input-method-ID
+ 2 CARD16 input-context-ID
+ 2 n byte length of preedit string
+ n LISTofBYTE preedit string
+ p unused, p = Pad(2+n)
+</literallayout>
+
+<para>
+<function>XIM_RESET_IC_REPLY </function>
+message returns the input-context-ID to distinguish replies from multiple ICs.
+</para>
+
+</sect2>
+<sect2 id="Callbacks">
+<title>Callbacks</title>
+<para>
+If XIMStyle has XIMPreeditArea or XIMStatusArea set, XIMGeometryCallback
+may be used, and if XIMPreeditCallback and/or XIMStatusCallback are set,
+corresponding callbacks may be used.
+</para>
+
+<para>
+Any callback request may be sent from an IM Server to an IM client
+asynchronously in response to any request previously sent by the IM client
+to the IM Server.
+</para>
+
+<para>
+When an IM Server needs to send a callback request synchronously with
+the request previously sent by an IM client, the IM Server sends it
+before replying to the previous request.
+</para>
+
+<sect3 id="Negotiating_geometry">
+<title>Negotiating geometry</title>
+<para>
+The IM Server sends
+<function>XIM_GEOMETRY </function>
+message to start geometry negotiation, if XIMStyle has XIMPreeditArea or
+XIMStatusArea set.
+</para>
+
+
+<literallayout class="monospaced">
+XIM_GEOMETRY (IM Server -> IM library)
+
+ 2 CARD16 input-method-ID
+ 2 CARD16 input-context-ID
+</literallayout>
+
+<para>
+There is always a single Focus Window, even if some input fields have only
+one IC.
+</para>
+
+</sect3>
+
+<sect3 id="Converting_a_string">
+<title>Converting a string</title>
+
+<literallayout class="monospaced">
+XIM_STR_CONVERSION (IM Server -> IM library)
+
+ 2 CARD16 input-method-ID
+ 2 CARD16 input-context-ID
+ 2 CARD16 XIMStringConversionPosition
+ 2 unused
+ 4 CARD32 XIMCaretDirection
+ #0 XIMForwardChar
+ #1 XIMBackwardChar
+ #2 XIMForwardWord
+ #3 XIMBackwardWord
+ #4 XIMCaretUp
+ #5 XIMCaretDown
+ #6 XIMNextLine
+ #7 XIMCPreviousLine
+ #8 XIMLineStart
+ #9 XIMLineEnd
+ #10 XIMAbsolutePosition
+ #11 XIMDontChange
+ 2 CARD16 factor
+ 2 CARD16 XIMStringConversionOperation
+ #0001 XIMStringConversionSubstitution
+ #0002 XIMStringConversionRetrieval
+ 2 INT16 byte length to multiply the XIMStringConversionType
+</literallayout>
+
+<para>
+<function>XIM_STR_CONVERSION </function>
+message may be used to start the string conversion from the IM Server.
+</para>
+
+<literallayout class="monospaced">
+XIM_STR_CONVERSION_REPLY (IM library -> IM Server)
+
+ 2 CARD16 input-method-ID
+ 2 CARD16 input-context-ID
+ 4 CARD32 XIMStringConversionFeedback
+ XIMSTRCONVTEXT XIMStringConversionText
+</literallayout>
+
+<para>
+<function>XIM_STR_CONVERSION_REPLY </function>
+message returns the string to be converted and the feedback information array.
+</para>
+</sect3>
+
+<sect3 id="Preedit_Callbacks">
+<title>Preedit Callbacks</title>
+
+<para>
+The IM Server sends
+<function>XIM_PREEDIT_START </function>
+message to call the XIMPreeditStartCallback function.
+</para>
+
+<literallayout class="monospaced">
+XIM_PREEDIT_START (IM Server -> IM library)
+
+ 2 CARD16 input-method-ID
+ 2 CARD16 input-context-ID
+</literallayout>
+
+<para>
+The reply to this message must be sent synchronously. The reply forwards
+the return value from the callback function to the IM Server.
+</para>
+
+<literallayout class="monospaced">
+XIM_PREEDIT_START_REPLY (IM library -> IM Server)
+
+ 2 CARD16 input-method-ID
+ 2 CARD16 input-context-ID
+ 4 INT32 return value
+</literallayout>
+
+<para>
+<function>XIM_PREEDIT_START_REPLY</function>
+message returns the input-context-ID to distinguish replies from multiple
+IC's. The return value contains the return value of the function
+XIMPreeditStartCallback.
+</para>
+
+<para>
+The IM Server sends
+<function>XIM_PREEDIT_DRAW </function>
+message to call the XIMPreeditDrawCallback function.
+</para>
+
+<literallayout class="monospaced">
+XIM_PREEDIT_DRAW (IM Server -> IM library)
+
+ 2 CARD16 input-method-ID
+ 2 CARD16 input-context-ID
+ 4 INT32 caret
+ 4 INT32 chg_first
+ 4 INT32 chg_length
+ 4 BITMASK32 status
+ #x0000001 no string
+ #x0000002 no feedback
+ 2 n length of preedit string
+ n STRING8 preedit string
+ p unused, p = Pad(2+n)
+ 2 m byte length of feedback array
+ 2 unused
+ m LISTofXIMFEEDBACK feedback array
+</literallayout>
+
+<para>
+The fields "caret", "chg_first" and "chg_length" correspond to the
+fields of XIMPreeditDrawCallbackStruct.
+When the "no string" bit of the status field is set, the text field of
+XIMPreeditDrawCallbackStruct is NULL.
+When the "no feedback" bit of the status field is set, the text feedback
+field of XIMPreeditDrawCallbackStruct is NULL.
+When the above bits are not set, "preedit string" contains the preedit
+string to be displayed, and the feedback array contains feedback information.
+</para>
+
+<para>
+The IM Server sends
+<function>XIM_PREEDIT_CARET</function>
+message to call the PreeditCaretCallback function.
+</para>
+
+<literallayout class="monospaced">
+XIM_PREEDIT_CARET (IM Server -> IM library)
+
+ 2 CARD16 input-method-ID
+ 2 CARD16 input-context-ID
+ 4 INT32 position
+ 4 CARD32 direction
+ #0 XIMForwardChar
+ #1 XIMBackwardChar
+ #2 XIMForwardWord
+ #3 XIMBackwardWord
+ #4 XIMCaretUp
+ #5 XIMCaretDown
+ #6 XIMNextLine
+ #7 XIMCPreviousLine
+ #8 XIMLineStart
+ #9 XIMLineEnd
+ #10 XIMAbsolutePosition
+ #11 XIMDontChange
+ 4 CARD32 style
+ #0 XIMInvisible
+ #1 XIMCPrimary
+ #2 XIMSecondary
+</literallayout>
+
+<para>
+Each entry corresponds to a field of XIMPreeditCaretCallbackStruct.
+Since this callback sets the caret position, its reply must be sent
+synchronously.
+</para>
+
+<literallayout class="monospaced">
+XIM_PREEDIT_CARET_REPLY (IM library -> IM Server)
+
+ 2 CARD16 input-method-ID
+ 2 CARD16 input-context-ID
+ 4 CARD32 position
+</literallayout>
+
+<para>
+The position is the value returned by the callback function after it
+has been called.
+</para>
+
+<para>
+The IM Server sends
+<function>XIM_PREEDIT_DONE </function>
+message to call the XIMPreeditDoneCallback function.
+</para>
+
+<literallayout class="monospaced">
+XIM_PREEDIT_DONE (IM Server -> IM library)
+
+ 2 CARD16 input-method-ID
+ 2 CARD16 input-context-ID
+</literallayout>
+
+</sect3>
+
+<sect3 id="Preedit_state_notify">
+<title>Preedit state notify</title>
+
+<literallayout class="monospaced">
+XIM_PREEDITSTATE (IM Server -> IM Library)
+ 2 CARD16 input-method-ID
+ 2 CARD16 input-context-ID
+ 4 BITMASK32 XIMPreeditState
+ #x0000000 XIMPreeditUnknown
+ #x0000001 XIMPreeditEnable
+ #x0000002 XIMPreeditDisable
+</literallayout>
+
+<para>
+<function>XIM_PREEDITSTATE</function>
+message is used to call the XIMPreeditStateNotifyCallback function.
+</para>
+
+</sect3>
+
+<sect3 id="Status_Callbacks">
+<title>Status Callbacks</title>
+
+<para>
+The IM Server sends
+<function>XIM_STATUS_START </function>
+message to call the XIMStatusStartCallback function.
+</para>
+
+<literallayout class="monospaced">
+XIM_STATUS_START (IM Server -> IM library)
+
+ 2 CARD16 input-method-ID
+ 2 CARD16 input-context-ID
+</literallayout>
+
+<para>
+The IM Server sends
+<function>XIM_STATUS_DRAW </function>
+message to call the XIMStatusDrawCallback function.
+</para>
+
+<literallayout class="monospaced">
+XIM_STATUS_DRAW (IM Server -> IM library)
+
+ 2 CARD16 input-method-ID
+ 2 CARD16 input-context-ID
+ 4 CARD32 type
+ #0 XIMTextType
+ #1 XIMBitmapType
+</literallayout>
+
+<para>
+If type is XIMTextType, the arguments continue as follows.
+</para>
+
+<literallayout class="monospaced">
+ 4 BITMASK32 status
+ #x0000001 no string
+ #x0000002 no feedback
+ 2 n length of status string
+ n STRING8 status string
+ p unused, p = Pad(2+n)
+ 2 m byte length of feedback array
+ 2 unused
+ m LISTofXIMFEEDBACK feedback array
+</literallayout>
+
+<para>
+If type is XIMBitmapType, the arguments continue as follows.
+</para>
+
+<literallayout class="monospaced">
+ 4 PIXMAP pixmap data
+</literallayout>
+
+<para>
+The field "type" corresponds to the field in XIMStatusDrawCallbackStruct.
+</para>
+
+<para>
+The IM Server sends
+<function>XIM_STATUS_DONE </function>
+message to call the XIMStatusDoneCallback function.
+</para>
+
+<literallayout class="monospaced">
+XIM_STATUS_DONE (IM Server -> IM library)
+
+ 2 CARD16 input-method-ID
+ 2 CARD16 input-context-ID
+</literallayout>
+
+</sect3>
+</sect2>
+</sect1>
+
+<sect1 id="Acknowledgements">
+<title>Acknowledgements</title>
+<para>
+This document represents the culmination of several years of debate and
+experiments done under the auspices of the MIT X Consortium i18n working
+group. Although this was a group effort, the author remains responsible
+for any errors or omissions.
+</para>
+
+<para>
+We would like to thank to all members of this group.
+And we would like to make special thanks to the following people
+(in alphabetical order) for their participation in the IM Protocol
+design,
+Hector Chan, Takashi Fujiwara, Yoshio Horiuchi, Makoto Inada,
+Hiromu Inukai, Mickael Kung, Seiji Kuwari, Franky Ling, Hiroyuki Machida,
+Hiroyuki Miyamoto, Frank Rojas, Bob Scheifler, Makiko Shimamura,
+Shoji Sugiyama, Hidetoshi Tajima, Masaki Takeuchi, Makoto Wakamatsu,
+Masaki Wakao, Nobuyuki Tanaka, Shigeru Yamada, Katsuhisa Yano, Jinsoo Yoon.
+</para>
+
+</sect1>
+
+<bibliography>
+<title>References</title>
+<biblioentry>
+ <title>X Window System Protocol Version 11</title>
+ <author><firstname>Robert W.</firstname><surname>Scheifler</surname></author>
+</biblioentry>
+
+<biblioentry>
+ <title>Xlib - C Language X Interface"</title>
+ <author><firstname>Robert W.</firstname><surname>Scheifler</surname></author>
+</biblioentry>
+</bibliography>
+
+<appendix id="common_extensions">
+<title>Common Extensions</title>
+<para>
+Extension opcodes and packet names (e.g.
+<function>XIM_EXT_SET_EVENT_MASK</function>
+) for additional extensions may be registered with X Consortium.
+The following is a commonly well-known extended packet.
+</para>
+
+<para>
+(1) Extension to manipulate the event handling\fP
+</para>
+
+<para>
+<!-- .LP -->
+<function>XIM_EXT_SET_EVENT_MASK </function>
+message specifies the set of event masks that the IM library should manipulate.
+</para>
+
+<literallayout class="monospaced">
+XIM_EXT_SET_EVENT_MASK (IM Server -> IM library)
+
+ 2 CARD16 input-method-ID
+ 2 CARD16 input-context-ID
+ 4 EVENTMASK filter-event-mask (*1)
+ 4 EVENTMASK intercept-event-mask (*2)
+ 4 EVENTMASK select-event-mask (*3)
+ 4 EVENTMASK forward-event-mask (*4)
+ 4 EVENTMASK synchronous-event-mask (*5)
+
+ (*1) Specify the events to be neglected by the IM library via XFilterEvent.
+ (*2) Specify the events to be deselected by the IM library with XSelectInput.
+ (*3) Specify the events to be selected by the IM library with XSelectInput.
+ (*4) Specify all the events to be forwarded to the IM Server by the IM library.
+ (*5) Specify the events to be forwarded with synchronous flag on by the IM library.
+</literallayout>
+
+<para>
+<!-- .LP -->
+The IM library must reply
+<function>XIM_SYNC_REPLY</function>
+message to the IM Server. This request is valid after the ic is created.
+</para>
+
+<para>
+(2) Extension for improvement of performance.
+</para>
+<para>
+The following requests may be used for improvement of performance.
+</para>
+
+<para>
+<function>XIM_EXT_FORWARD_KEYEVENT</function>
+message may be used instead of
+<function>XIM_FORWARD_EVENT</function>
+message.
+</para>
+
+<literallayout class="monospaced">
+XIM_EXT_FORWARD_KEYEVENT (IM Server <--> IM library)
+ 2 CARD16 input-method-ID
+ 2 CARD16 input-context-ID
+ 2 BITMASK16 flag
+ #0001 synchronous
+ 2 CARD16 sequence number
+ 1 BYTE xEvent.u.u.type
+ 1 BYTE keycode
+ 2 CARD16 state
+ 4 CARD32 time
+ 4 CARD32 window
+</literallayout>
+
+<para>
+<function>XIM_EXT_MOVE</function>
+message may be used to change the spot location instead of
+<function></function>
+XIM_SET_IC_VALUES
+message.
+It is effective only if the client specified XIMPreeditPosition.
+</para>
+
+
+<literallayout class="monospaced">
+XIM_EXT_MOVE (IM library -> IM Server)
+
+ 2 CARD16 input-method-ID
+ 2 CARD16 input-context-ID
+ 2 INT16 X
+ 2 INT16 Y
+</literallayout>
+
+<para>
+<function>XIM_EXT_MOVE</function>
+message is a asynchronous request.
+</para>
+
+</appendix>
+<appendix id="transport_list">
+<title>Transport List</title>
+
+<para>
+The list of transport specific IM Server address format registered
+</para>
+
+<para>
+The following format represents the ATOM contained in
+<function>XIM_SERVERS</function>
+property and the string returned from the request converting
+selection target LOCALES and TRANSPORT.
+</para>
+<literallayout class="monospaced">
+ "{<emphasis remap='I'>category</emphasis>=[<emphasis remap='I'>value</emphasis>,...]}..."
+</literallayout>
+<para>
+The following categories are currently registered.
+</para>
+
+<literallayout class="monospaced">
+<function>server</function>;: IM Server name (used for XIM_SERVERS)
+<function>locale</function>;: XPG4 locale name (LOCALES)
+<function>transport</function>;: transport-specific name (TRANSPORT)
+</literallayout>
+
+<para>
+The preregistered formats for transport-specific names are as follows:
+</para>
+
+<para>
+<function>TCP/IP Names</function>
+</para>
+
+<para>
+The following syntax should be used for system internal domain names:
+</para>
+<literallayout class="monospaced">
+<<emphasis remap='I'>local name</emphasis>> ::= "local/"<<emphasis remap='I'>hostname</emphasis>>":"<<emphasis remap='I'>pathname</emphasis>>
+</literallayout>
+<para>
+Where <<emphasis remap='I'>pathname</emphasis>> is a path name of socket address.
+</para>
+
+<para>
+IM Server's name should be set to <<emphasis remap='I'>pathname</emphasis>> to run multiple IM Server
+at the same time
+</para>
+
+<para>
+The following syntax should be used for Internet domain names:
+</para>
+<literallayout class="monospaced">
+<<emphasis remap='I'>TCP name</emphasis>> ::= "tcp/"<<emphasis remap='I'>hostname</emphasis>>":"<<emphasis remap='I'>ipportnumber</emphasis>>
+</literallayout>
+<para>
+where <<emphasis remap='I'>hostname</emphasis>> is either symbolic (such as expo.lcs.mit.edu) or
+numeric decimal (such as 18.30.0.212). The <<emphasis remap='I'>ipportnumber</emphasis>> is the
+port on which the IM Server is listening for connections.
+For example:
+</para>
+<literallayout class="monospaced">
+tcp/expo.lcs.mit.edu:8012
+tcp/18.30.0.212:7890
+</literallayout>
+
+<para>
+<function>DECnet Names</function>
+</para>
+
+<para>
+The following syntax should be used for DECnet names:
+</para>
+<literallayout class="monospaced">
+<<emphasis remap='I'>DECnet name</emphasis>> ::= "decnet/"<<emphasis remap='I'>nodename</emphasis>>"::IMSERVER$"<<emphasis remap='I'>objname</emphasis>>
+</literallayout>
+<para>
+where <<emphasis remap='I'>nodename</emphasis>> is either
+symbolic (such as SRVNOD) or the numeric
+decimal form of the DECnet address (such as 44.70).
+The <<emphasis remap='I'>objname</emphasis>>
+is normal, case-insensitive DECnet object name. For example:
+</para>
+
+<literallayout class="monospaced">
+DECNET/SRVNOD::IMSERVER$DEFAULT
+decnet/44.70::IMSERVER$other
+</literallayout>
+
+<para>
+<function>X Names</function>
+</para>
+
+<para>
+The following syntax should be used for X names:
+</para>
+<literallayout class="monospaced">
+<<emphasis remap='I'>X name</emphasis>> ::= "X/"
+</literallayout>
+
+<para>
+If a given category has multiple values, the value is evaluated in order of
+setting.
+</para>
+
+</appendix>
+<appendix id="protocol_number">
+<title>Protocol Number</title>
+
+<para>
+<function>Major Protocol number</function>
+</para>
+
+<literallayout class="monospaced">
+XIM_CONNECT #001
+XIM_CONNECT_REPLY #002
+XIM_DISCONNECT #003
+XIM_DISCONNECT_REPLY #004
+
+XIM_AUTH_REQUIRED #010
+XIM_AUTH_REPLY #011
+XIM_AUTH_NEXT #012
+XIM_AUTH_SETUP #013
+XIM_AUTH_NG #014
+
+XIM_ERROR #020
+
+XIM_OPEN #030
+XIM_OPEN_REPLY #031
+XIM_CLOSE #032
+XIM_CLOSE_REPLY #033
+XIM_REGISTER_TRIGGERKEYS #034
+XIM_TRIGGER_NOTIFY #035
+XIM_TRIGGER_NOTIFY_REPLY #036
+XIM_SET_EVENT_MASK #037
+XIM_ENCODING_NEGOTIATION #038
+XIM_ENCODING_NEGOTIATION_REPLY #039
+XIM_QUERY_EXTENSION #040
+XIM_QUERY_EXTENSION_REPLY #041
+XIM_SET_IM_VALUES #042
+XIM_SET_IM_VALUES_REPLY #043
+XIM_GET_IM_VALUES #044
+XIM_GET_IM_VALUES_REPLY #045
+
+XIM_CREATE_IC #050
+XIM_CREATE_IC_REPLY #051
+XIM_DESTROY_IC #052
+XIM_DESTROY_IC_REPLY #053
+XIM_SET_IC_VALUES #054
+XIM_SET_IC_VALUES_REPLY #055
+XIM_GET_IC_VALUES #056
+XIM_GET_IC_VALUES_REPLY #057
+XIM_SET_IC_FOCUS #058
+XIM_UNSET_IC_FOCUS #059
+XIM_FORWARD_EVENT #060
+XIM_SYNC #061
+XIM_SYNC_REPLY #062
+XIM_COMMIT #063
+XIM_RESET_IC #064
+XIM_RESET_IC_REPLY #065
+
+XIM_GEOMETRY #070
+XIM_STR_CONVERSION #071
+XIM_STR_CONVERSION_REPLY #072
+XIM_PREEDIT_START #073
+XIM_PREEDIT_START_REPLY #074
+XIM_PREEDIT_DRAW #075
+XIM_PREEDIT_CARET #076
+XIM_PREEDIT_CARET_REPLY #077
+XIM_PREEDIT_DONE #078
+XIM_STATUS_START #079
+XIM_STATUS_DRAW #080
+XIM_STATUS_DONE #081
+XIM_PREEDITSTATE #082
+
+(*) The IM Server's extension protocol number should be more than #128.
+</literallayout>
+</appendix>
+
+<appendix id="implementation_tips">
+
+<title>Implementation Tips</title>
+<para>
+(1) FrontEnd Method
+</para>
+
+<para>
+FrontEnd method is recognized as a performance acceleration by the
+trade off of the variety of the reliability.
+</para>
+
+<para>
+In order to use the FrontEnd method, the IM library must query the IM
+Server to see if the FrontEnd extension is available. The query is
+made by using the
+<function>XIM_QUERY_EXTENSION</function>
+message. The IM Server may send
+<function>XIM_EXT_SET_EVENT_MASK</function>
+message with intercept-event-mask, forward-event-mask, and
+synchronous-event-mask values set after replying
+<function>XIM_QUERY_EXTENSION_REPLY</function>
+message.
+</para>
+
+<para>
+FrontEnd method can be implemented in a couple of ways depending on
+how the IM Server utilize
+<function>XIM_EXT_SET_EVENT_MASK</function>
+message.
+</para>
+
+<para>
+One approach is to update both of the input mask and the filter-event-mask
+depending on the preeidting state. The sample protocol sequence using the
+static event flow is as follows:
+</para>
+
+<mediaobject id="staticflow">
+ <imageobject>
+ <imagedata scale="75" format="SVG" fileref="staticflow.svg"/>
+ </imageobject>
+ <caption>The flow of events</caption>
+</mediaobject>
+
+<para>
+To pursuit a maximum performance regardless of the preediting mode,
+the IM Server may use the dynamic event flow with the following
+sample protocol sequence.
+</para>
+
+<mediaobject id="dynamicflow">
+ <imageobject>
+ <imagedata scale="75" format="SVG" fileref="dynamicflow.svg"/>
+ </imageobject>
+ <caption>The flow of events</caption>
+</mediaobject>
+
+<para>
+This method can reduce the XIM protocol traffic dramatically
+by updating intercept-event-mask and select-event-mask accordingly.
+The tradeoff of this performance improvement is that the key
+events may be lost or disordered in some particular situation, such as
+when the user types the keyboard in following sequence really fast:
+</para>
+
+<para>
+<preediting on key>"some strings"<preediting off
+key>"another string"
+</para>
+
+<para>
+Since this method requires the input mask updates to the both the IM Server
+and Xlib when turning on and off the preediting, and there is a time lag
+till the requests take effect when two client issues the input mask updates
+simultaneously.
+</para>
+
+<para>
+Another approach of the FrontEnd method is to update the filter-event-mask
+depending on the preediting state and not to update the input mask.
+The IM Server must register both of the preediting on key list and off key
+list by
+<function>XIM_REGISTER_TRIGGERKEYS</function>
+message.
+In this method, Both the IM Server and the IM client select the same
+events on the same client's window, so that the events are delivered
+to both of the IM Server and the client. The preediting on and off
+states are expressed by whether the key events are filtered or not.
+The sample protocol sequence are as follows:
+</para>
+
+<para>
+<<Using static event flow>>
+</para>
+
+<mediaobject id="staticflowsampleseq">
+ <imageobject>
+ <imagedata scale="75" format="SVG" fileref="staticflowsampleseq.svg"/>
+ </imageobject>
+ <caption>The flow of events</caption>
+</mediaobject>
+
+<para>
+<<Using the dynamic event flow>>
+</para>
+
+<mediaobject id="dynamicflowsampleseq">
+ <imageobject>
+ <imagedata scale="75" format="SVG" fileref="dynamicflowsampleseq.svg"/>
+ </imageobject>
+ <caption>The flow of events</caption>
+</mediaobject>
+
+<para>
+This method does not have the problem of the time lag when going across
+the preediting on and off mode, however, the amount of the performance
+acceleration is not as good as the method described above.
+</para>
+
+<para>
+In general, the FrontEnd method requires some synchronization to some
+of the X protocols, such as the ChangeWindowAttribute protocol for the
+event mask change or the GrabKey protocol, since it relies on the X's
+principal event dispatching mechanism. Any X protocol bindings do not
+consider the synchronization might cause some mis-synchronization
+between the IM clients and the IM Server.
+</para>
+
+<para>
+(2) Transport Layer
+</para>
+
+<para>
+The Xlib XIM implementation is layered into three functions, a protocol
+layer, an interface layer and a transport layer. The purpose of this
+layering is to make the protocol independent of transport implementation.
+Each function of these layers are:
+</para>
+
+<variablelist>
+ <varlistentry>
+ <term>The protocol layer</term>
+ <listitem>
+ <para>
+implements overall function of XIM and calls the interface layer
+functions when it needs to communicate to IM Server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>The interface layer</term>
+ <listitem>
+ <para>
+separates the implementation of the transport layer from the protocol
+layer, in other words, it provides implementation independent hook for
+the transport layer functions.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>The transport layer</term>
+ <listitem>
+ <para>
+handles actual data communication with IM Server. It is done by a set
+of several functions named transporters.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The interface layer and the transport layer make various communication
+channels usable such as X Protocol, TCP/IP, DECnet or STREAM.
+The following is a sample implementation for the transporter using
+the X connection.
+Refer to "xtrans" for the transporter using Socket Transport. <!-- xref ?-->
+</para>
+
+<para>
+At the beginning of the X Transport connection for the XIM transport
+mechanism, two different windows must be created either in an Xlib XIM
+or in an IM Server, with which the Xlib and the IM Server exchange the
+XIM transports by using the ClientMessage events and Window Properties.
+In the following, the window created by the Xlib is referred as the
+"client communication window", and on the other hand, the window created
+by the IM Server is referred as the "IMS communication window".
+</para>
+
+<para>
+Connection
+</para>
+
+<para>
+In order to establish a connection, a communication window is created.
+A ClientMessage in the following event's format is sent to the owner
+window of XIM_SERVER selection, which the IM Server has created.
+</para>
+
+<para>
+Refer to "The Input Method Protocol" for the XIM_SERVER atom. <!-- xref -->
+</para>
+
+<table frame="topbot" id="clientmessage_sent_to_the_ims_window">
+ <?dbfo keep-together="always" ?>
+ <title>The ClientMessage sent to the IMS window.</title>
+ <tgroup cols="3" align='left' colsep='0' rowsep='0'>
+ <colspec colname="col1" colwidth="1.0*"/>
+ <colspec colname="col2" colwidth="1.0*" colsep="1"/>
+ <colspec colname="col3" colwidth="3.5*"/>
+ <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="center"/>
+ <thead>
+ <row rowsep='1'>
+ <entry spanname="span-horiz" colsep='1'>Structure Member</entry>
+ <entry>Contents</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>int</entry>
+ <entry>type</entry>
+ <entry>ClientMessage</entry>
+ </row>
+ <row>
+ <entry>u_long</entry>
+ <entry>serial</entry>
+ <entry>Set by the X Window System</entry>
+ </row>
+ <row>
+ <entry>Bool</entry>
+ <entry>send_event</entry>
+ <entry>Set by the X Window System</entry>
+ </row>
+ <row>
+ <entry>Display</entry>
+ <entry>*display</entry>
+ <entry>The display to which connects</entry>
+ </row>
+ <row>
+ <entry>Window</entry>
+ <entry>window</entry>
+ <entry>IMS Window ID</entry>
+ </row>
+ <row>
+ <entry>Atom</entry>
+ <entry>message_type</entry>
+ <entry>XInternAtom(display, "_XIM_XCONNECT", False)</entry>
+ </row>
+ <row>
+ <entry>int</entry>
+ <entry>format</entry>
+ <entry>32</entry>
+ </row>
+ <row>
+ <entry>long</entry>
+ <entry>data.l[0]</entry>
+ <entry>client communication window ID</entry>
+ </row>
+ <row>
+ <entry>long</entry>
+ <entry>data.l[1]</entry>
+ <entry>client-major-transport-version (*1)</entry>
+ </row>
+ <row>
+ <entry>long</entry>
+ <entry>data.l[2]</entry>
+ <entry>client-major-transport-version (*1)</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</table>
+
+<para>
+In order to establish the connection (to notify the IM Server communication
+window), the IM Server sends a ClientMessage in the following event's
+format to the client communication window.
+</para>
+
+<table frame="topbot" id="clientmessage_sent_by_the_im_server">
+ <?dbfo keep-together="always" ?>
+ <title>The ClientMessage sent by the IM Server.</title>
+ <tgroup cols="3" align='left' colsep='0' rowsep='0'>
+ <colspec colname="col1" colwidth="1.0*"/>
+ <colspec colname="col2" colwidth="1.0*" colsep="1"/>
+ <colspec colname="col3" colwidth="3.5*"/>
+ <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="center"/>
+ <thead>
+ <row rowsep='1'>
+ <entry spanname="span-horiz" colsep='1'>Structure Member</entry>
+ <entry>Contents</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>int</entry>
+ <entry>type</entry>
+ <entry>ClientMessage</entry>
+ </row>
+ <row>
+ <entry>u_long</entry>
+ <entry>serial</entry>
+ <entry>Set by the X Window System</entry>
+ </row>
+ <row>
+ <entry>Bool</entry>
+ <entry>send_event</entry>
+ <entry>Set by the X Window System</entry>
+ </row>
+ <row>
+ <entry>Display</entry>
+ <entry>*display</entry>
+ <entry>The display to which connects</entry>
+ </row>
+ <row>
+ <entry>Window</entry>
+ <entry>window</entry>
+ <entry>client communication window ID</entry>
+ </row>
+ <row>
+ <entry>Atom</entry>
+ <entry>message_type</entry>
+ <entry>XInternAtom(display, "_XIM_XCONNECT", False)</entry>
+ </row>
+ <row>
+ <entry>int</entry>
+ <entry>format</entry>
+ <entry>32</entry>
+ </row>
+ <row>
+ <entry>long</entry>
+ <entry>data.l[0]</entry>
+ <entry>IMS communication window ID</entry>
+ </row>
+ <row>
+ <entry>long</entry>
+ <entry>data.l[1]</entry>
+ <entry>server-major-transport-version (*1)</entry>
+ </row>
+ <row>
+ <entry>long</entry>
+ <entry>data.l[2]</entry>
+ <entry>server-minor-transport-version (*1)</entry>
+ </row>
+ <row>
+ <entry>long</entry>
+ <entry>data.l[3]</entry>
+ <entry>dividing size between ClientMessage and Property (*2)</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</table>
+
+<para>
+(*1) major/minor-transport-version
+</para>
+<para>
+The read/write method is decided by the combination of
+major/minor-transport-version, as follows:
+</para>
+
+
+<table frame="all" id="readwrite_method_and_the_majorminor_transport_version">
+ <?dbfo keep-together="always" ?>
+ <title>The read/write method and the major/minor-transport-version</title>
+ <tgroup cols="3" align='left' colsep='1' rowsep='1'>
+ <colspec colname="col1" colwidth="1.0*"/>
+ <colspec colname="col2" colwidth="1.0*"/>
+ <colspec colname="col3" colwidth="3.0*"/>
+ <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="center"/>
+ <thead>
+ <row>
+ <entry spanname="span-horiz" colsep='1'>Transport-version</entry>
+ <entry>read/write</entry>
+ </row>
+ <row>
+ <entry>major</entry>
+ <entry>minor</entry>
+ <entry></entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry morerows="2">0</entry>
+ <entry>0</entry>
+ <entry>only-CM & Property-with-CM</entry>
+ </row>
+ <row>
+ <entry>1</entry>
+ <entry>only-CM & multi-CM</entry>
+ </row>
+ <row rowsep="1">
+ <entry>2</entry>
+ <entry>only-CM & multi-CM & Property-with-CM</entry>
+ </row>
+ <row rowsep="1">
+ <entry>1</entry>
+ <entry>0</entry>
+ <entry>PropertyNotify</entry>
+ </row>
+ <row>
+ <entry morerows="1">2</entry>
+ <entry>0</entry>
+ <entry>only-CM & PropertyNotify</entry>
+ </row>
+ <row>
+ <entry>1</entry>
+ <entry>only-CM & multi-CM & PropertyNotify</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</table>
+
+<literallayout class="monospaced">
+only-CM : data is sent via a ClientMessage
+multi-CM : data is sent via multiple ClientMessages
+Property-with-CM : data is written in Property, and its Atom
+ is send via ClientMessage
+PropertyNotify : data is written in Property, and its Atom
+ is send via PropertyNotify
+
+</literallayout>
+
+<para>
+The method to decide major/minor-transport-version is as follows:
+</para>
+
+<itemizedlist>
+ <listitem>
+ <para>
+The client sends 0 as major/minor-transport-version to the IM Server.
+The client must support all methods in Table D-3.
+The client may send another number as major/minor-transport-version to
+use other method than the above in the future.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The IM Server sends its major/minor-transport-version number to
+the client. The client sends data using the method specified by the
+IM Server.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If major/minor-transport-version number is not available, it is regarded
+as 0.
+<!-- .RE -->
+ </para>
+ </listitem>
+</itemizedlist>
+
+<para>
+(*2) dividing size between ClientMessage and Property
+</para>
+
+<para>
+If data is sent via both of multi-CM and Property, specify the dividing
+size between ClientMessage and Property. The data, which is smaller than
+this size, is sent via multi-CM (or only-CM), and the data, which is
+lager than this size, is sent via Property.
+</para>
+
+<para>
+<emphasis role="bold">read/write</emphasis>
+</para>
+
+<para>
+The data is transferred via either ClientMessage or Window Property in
+the X Window System.
+</para>
+
+<para>
+Format for the data from the Client to the IM Server
+</para>
+
+<para>
+ClientMessage
+</para>
+
+<para>
+If data is sent via ClientMessage event, the format is as follows:
+</para>
+
+
+<table frame="topbot" id="clientmessage_events_format_first_or_middle">
+ <?dbfo keep-together="always" ?>
+<title>The ClientMessage event's format (first or middle)</title>
+ <tgroup cols="3" align='left' colsep='0' rowsep='0'>
+ <colspec colname="col1" colwidth="1.0*"/>
+ <colspec colname="col2" colwidth="1.0*" colsep="1"/>
+ <colspec colname="col3" colwidth="3.5*"/>
+ <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="center"/>
+ <thead>
+ <row rowsep='1'>
+ <entry spanname="span-horiz" colsep='1'>Structure Member</entry>
+ <entry>Contents</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>int</entry>
+ <entry>type</entry>
+ <entry>ClientMessage</entry>
+ </row>
+ <row>
+ <entry>u_long</entry>
+ <entry>serial</entry>
+ <entry>Set by the X Window System</entry>
+ </row>
+ <row>
+ <entry>Bool</entry>
+ <entry>send_event</entry>
+ <entry>Set by the X Window System</entry>
+ </row>
+ <row>
+ <entry>Display</entry>
+ <entry>*display</entry>
+ <entry>The display to which connects</entry>
+ </row>
+ <row>
+ <entry>Window</entry>
+ <entry>window</entry>
+ <entry>IMS communication window ID</entry>
+ </row>
+ <row>
+ <entry>Atom</entry>
+ <entry>message_type</entry>
+ <entry>XInternAtom(display, "_XIM_MOREDATA", False)</entry>
+ </row>
+ <row>
+ <entry>int</entry>
+ <entry>format</entry>
+ <entry>8</entry>
+ </row>
+ <row>
+ <entry>char</entry>
+ <entry>data.b[20]</entry>
+ <entry>(read/write DATA : 20 byte)</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</table>
+
+<table frame="topbot" id="clientmessage_events_format_only_or_last">
+ <?dbfo keep-together="always" ?>
+<title>The ClientMessage event's format (only or last)</title>
+ <tgroup cols="3" align='left' colsep='0' rowsep='0'>
+ <colspec colname="col1" colwidth="1.0*"/>
+ <colspec colname="col2" colwidth="1.0*" colsep="1"/>
+ <colspec colname="col3" colwidth="3.5*"/>
+ <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="center"/>
+ <thead>
+ <row rowsep='1'>
+ <entry spanname="span-horiz" colsep='1'>Structure Member</entry>
+ <entry>Contents</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>int</entry>
+ <entry>type</entry>
+ <entry>ClientMessage</entry>
+ </row>
+ <row>
+ <entry>u_long</entry>
+ <entry>serial</entry>
+ <entry>Set by the X Window System</entry>
+ </row>
+ <row>
+ <entry>Bool</entry>
+ <entry>send_event</entry>
+ <entry>Set by the X Window System</entry>
+ </row>
+ <row>
+ <entry>Display</entry>
+ <entry>*display</entry>
+ <entry>The display to which connects</entry>
+ </row>
+ <row>
+ <entry>Window</entry>
+ <entry>window</entry>
+ <entry>IMS communication window ID</entry>
+ </row>
+ <row>
+ <entry>Atom</entry>
+ <entry>message_type</entry>
+ <entry>XInternAtom(display, "_XIM_PROTOCOL", False)</entry>
+ </row>
+ <row>
+ <entry>int</entry>
+ <entry>format</entry>
+ <entry>8</entry>
+ </row>
+ <row>
+ <entry>char</entry>
+ <entry>data.b[20]</entry>
+ <entry>(read/write DATA : MAX 20 byte) (*1)</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</table>
+
+<para>
+(*1) If the data is smaller than 20 byte, all data other than available data
+must be 0.
+</para>
+
+<para>
+Property
+</para>
+
+<para>
+In the case of large data, data will be sent via the Window Property
+for the efficiency. There are the following two methods to notify
+Property, and transport-version is decided which method is used.
+</para>
+
+<itemizedlist>
+ <listitem>
+ <para>
+The XChangeProperty function is used to store data in the client
+communication window, and Atom of the stored data is notified to the
+IM Server via ClientMessage event.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The XChangeProperty function is used to store data in the client
+communication window, and Atom of the stored data is notified to the
+IM Server via PropertyNotify event.
+ </para>
+ </listitem>
+</itemizedlist>
+
+<para>
+The arguments of the XChangeProperty are as follows:
+</para>
+
+<table frame="topbot" id="xchangeproperty_events_format">
+ <?dbfo keep-together="always" ?>
+<title>The XChangeProperty event's format</title>
+ <tgroup cols="3" align='left' colsep='0' rowsep='0'>
+ <colspec colname="col1" colwidth="1.0*"/>
+ <colspec colname="col2" colwidth="1.0*" colsep="1"/>
+ <colspec colname="col3" colwidth="3.5*"/>
+ <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="center"/>
+ <thead>
+ <row rowsep='1'>
+ <entry spanname="span-horiz" colsep='1'>Argument</entry>
+ <entry>Contents</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>Display</entry>
+ <entry>*display</entry>
+ <entry>The display to which connects</entry>
+ </row>
+ <row>
+ <entry>Window</entry>
+ <entry>window</entry>
+ <entry>IMS communication window ID</entry>
+ </row>
+ <row>
+ <entry>Atom</entry>
+ <entry>property</entry>
+ <entry>read/write property Atom (*1)</entry>
+ </row>
+ <row>
+ <entry>Atom</entry>
+ <entry>type</entry>
+ <entry>XA_STRING </entry>
+ </row>
+ <row>
+ <entry>int</entry>
+ <entry>format</entry>
+ <entry>8</entry>
+ </row>
+ <row>
+ <entry>int</entry>
+ <entry>mode</entry>
+ <entry>PropModeAppend</entry>
+ </row>
+ <row>
+ <entry>u_char</entry>
+ <entry>*data</entry>
+ <entry>read/write DATA</entry>
+ </row>
+ <row>
+ <entry>int</entry>
+ <entry>nelements</entry>
+ <entry>length of DATA</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</table>
+
+<para>
+The read/write property ATOM allocates the following strings by
+<function>XInternAtom</function>.
+</para>
+
+<para>
+"_clientXXX"
+</para>
+
+<para>
+The client changes the property with the mode of PropModeAppend and
+the IM Server will read it with the delete mode i.e. (delete = True).
+</para>
+
+<para>
+If Atom is notified via ClientMessage event, the format of the ClientMessage
+is as follows:
+</para>
+
+<table frame="topbot" id="clientmessage_events_format_to_send_atom_of_property">
+ <?dbfo keep-together="always" ?>
+<title>The ClientMessage event's format to send Atom of property</title>
+ <tgroup cols="3" align='left' colsep='0' rowsep='0'>
+ <colspec colname="col1" colwidth="1.0*"/>
+ <colspec colname="col2" colwidth="1.0*" colsep="1"/>
+ <colspec colname="col3" colwidth="3.5*"/>
+ <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="center"/>
+ <thead>
+ <row rowsep='1'>
+ <entry spanname="span-horiz" colsep='1'>Structure Members</entry>
+ <entry>Contents</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>int</entry>
+ <entry>type</entry>
+ <entry>ClientMessage</entry>
+ </row>
+ <row>
+ <entry>u_long</entry>
+ <entry>serial</entry>
+ <entry>Set by the X Window System</entry>
+ </row>
+ <row>
+ <entry>Bool</entry>
+ <entry>send_event</entry>
+ <entry>Set by the X Window System</entry>
+ </row>
+ <row>
+ <entry>Display</entry>
+ <entry>*display</entry>
+ <entry>The display to which connects</entry>
+ </row>
+ <row>
+ <entry>Window</entry>
+ <entry>window</entry>
+ <entry>IMS communication window ID</entry>
+ </row>
+ <row>
+ <entry>Atom</entry>
+ <entry>message_type</entry>
+ <entry>XInternAtom(display, "_XIM_PROTOCOL", False)</entry>
+ </row>
+ <row>
+ <entry>int</entry>
+ <entry>format</entry>
+ <entry>32</entry>
+ </row>
+ <row>
+ <entry>long</entry>
+ <entry>data.l[0]</entry>
+ <entry>length of read/write property Atom</entry>
+ </row>
+ <row>
+ <entry>long</entry>
+ <entry>data.l[1]</entry>
+ <entry>read/write property Atom</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</table>
+
+<para>
+Format for the data from the IM Server to the Client
+</para>
+
+<para>
+<!-- .LP -->
+<!-- .RS -->
+<!-- .B -->
+ClientMessage
+</para>
+<para>
+<!-- .LP -->
+The format of the ClientMessage is as follows:
+</para>
+
+
+
+<table frame="topbot" id="clientmessage_events_format_for_first_or_middle">
+ <?dbfo keep-together="always" ?>
+<title>The ClientMessage event's format (first or middle)</title>
+ <tgroup cols="3" align='left' colsep='0' rowsep='0'>
+ <colspec colname="col1" colwidth="1.0*"/>
+ <colspec colname="col2" colwidth="1.0*" colsep="1"/>
+ <colspec colname="col3" colwidth="3.5*"/>
+ <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="center"/>
+ <thead>
+ <row rowsep='1'>
+ <entry spanname="span-horiz" colsep='1'>Structure Members</entry>
+ <entry>Contents</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>int</entry>
+ <entry>type</entry>
+ <entry>ClientMessage</entry>
+ </row>
+ <row>
+ <entry>u_long</entry>
+ <entry>serial</entry>
+ <entry>Set by the X Window System</entry>
+ </row>
+ <row>
+ <entry>Bool</entry>
+ <entry>send_event </entry>
+ <entry>Set by the X Window System</entry>
+ </row>
+ <row>
+ <entry>Display</entry>
+ <entry>*display</entry>
+ <entry>The display to which connects</entry>
+ </row>
+ <row>
+ <entry>Window</entry>
+ <entry>window</entry>
+ <entry>client communication window ID</entry>
+ </row>
+ <row>
+ <entry>Atom</entry>
+ <entry>message_type</entry>
+ <entry>XInternAtom(display, "_XIM_MOREDATA", False)</entry>
+ </row>
+ <row>
+ <entry>int</entry>
+ <entry>format</entry>
+ <entry>8</entry>
+ </row>
+ <row>
+ <entry>char</entry>
+ <entry>data.b[20]</entry>
+ <entry>(read/write DATA : 20 byte)</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</table>
+
+
+<table frame="topbot" id="clientmessage_events_format_for_only_or_last">
+ <?dbfo keep-together="always" ?>
+<title>The ClientMessage event's format (only or last)</title>
+ <tgroup cols="3" align='left' colsep='0' rowsep='0'>
+ <colspec colname="col1" colwidth="1.0*"/>
+ <colspec colname="col2" colwidth="1.0*" colsep="1"/>
+ <colspec colname="col3" colwidth="3.5*"/>
+ <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="center"/>
+ <thead>
+ <row rowsep='1'>
+ <entry spanname="span-horiz" colsep='1'>Structure Members</entry>
+ <entry>Contents</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>int</entry>
+ <entry>type</entry>
+ <entry>ClientMessage</entry>
+ </row>
+ <row>
+ <entry>u_long</entry>
+ <entry>serial</entry>
+ <entry>Set by the X Window System</entry>
+ </row>
+ <row>
+ <entry>Bool</entry>
+ <entry>send_event </entry>
+ <entry>Set by the X Window System</entry>
+ </row>
+ <row>
+ <entry>Display</entry>
+ <entry>*display</entry>
+ <entry>The display to which connects</entry>
+ </row>
+ <row>
+ <entry>Window</entry>
+ <entry>window</entry>
+ <entry>client communication window ID</entry>
+ </row>
+ <row>
+ <entry>Atom</entry>
+ <entry>message_type</entry>
+ <entry>XInternAtom(display, "_XIM_PROTOCOL", False)</entry>
+ </row>
+ <row>
+ <entry>int</entry>
+ <entry>format</entry>
+ <entry>8</entry>
+ </row>
+ <row>
+ <entry>char</entry>
+ <entry>data.b[20]</entry>
+ <entry>(read/write DATA : MAX 20 byte) (*1)</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</table>
+
+<para>
+(*1) If the data size is smaller than 20 bytes, all data other than available
+data must be 0.
+</para>
+
+<para>
+Property
+</para>
+
+<para>
+In the case of large data, data will be sent via the Window Property
+for the efficiency. There are the following two methods to notify
+Property, and transport-version is decided which method is used.
+</para>
+
+<itemizedlist>
+ <listitem>
+ <para>
+The XChangeProperty function is used to store data in the IMS
+communication window, and Atom of the property is sent via the
+ClientMessage event.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The XChangeProperty function is used to store data in the IMS
+communication window, and Atom of the property is sent via
+PropertyNotify event.
+ </para>
+ </listitem>
+</itemizedlist>
+
+<para>
+The arguments of the XChangeProperty are as follows:
+</para>
+
+<table frame="topbot" id="xchangeproperty_events_format_2">
+ <?dbfo keep-together="always" ?>
+<title>The XChangeProperty event's format</title>
+ <tgroup cols="3" align='left' colsep='0' rowsep='0'>
+ <colspec colname="col1" colwidth="1.0*"/>
+ <colspec colname="col2" colwidth="1.0*" colsep="1"/>
+ <colspec colname="col3" colwidth="3.5*"/>
+ <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="center"/>
+ <thead>
+ <row rowsep='1'>
+ <entry spanname="span-horiz" colsep='1'>Argument</entry>
+ <entry>Contents</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>Display</entry>
+ <entry>*display</entry>
+ <entry>The display which to connects</entry>
+ </row>
+ <row>
+ <entry>Window</entry>
+ <entry>window</entry>
+ <entry>client communication window ID</entry>
+ </row>
+ <row>
+ <entry>Atom</entry>
+ <entry>property</entry>
+ <entry>read/write property Atom (*1)</entry>
+ </row>
+ <row>
+ <entry>Atom</entry>
+ <entry>type</entry>
+ <entry>XA_STRING</entry>
+ </row>
+ <row>
+ <entry>int</entry>
+ <entry>format</entry>
+ <entry>8</entry>
+ </row>
+ <row>
+ <entry>int</entry>
+ <entry>mode</entry>
+ <entry>PropModeAppend</entry>
+ </row>
+ <row>
+ <entry>u_char</entry>
+ <entry>*data</entry>
+ <entry>read/write DATA</entry>
+ </row>
+ <row>
+ <entry>int</entry>
+ <entry>nelements</entry>
+ <entry>length of DATA</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</table>
+
+<para>
+(*1) The read/write property ATOM allocates some strings, which are not
+allocated by the client, by <function>XInternAtom</function>.
+</para>
+
+<para>
+The IM Server changes the property with the mode of PropModeAppend and
+the client reads it with the delete mode, i.e. (delete = True).
+</para>
+
+<para>
+If Atom is notified via ClientMessage event, the format of the ClientMessage
+is as follows:
+</para>
+
+
+<table frame="topbot" id="clientmessage_events_format_to_send_atom_of_property_2">
+ <?dbfo keep-together="always" ?>
+<title>The ClientMessage event's format to send Atom of property</title>
+ <tgroup cols="3" align='left' colsep='0' rowsep='0'>
+ <colspec colname="col1" colwidth="1.0*"/>
+ <colspec colname="col2" colwidth="1.0*" colsep='1'/>
+ <colspec colname="col3" colwidth="3.5*"/>
+ <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="center"/>
+ <thead>
+ <row rowsep='1'>
+ <entry spanname="span-horiz" colsep='1'>Structure Member</entry>
+ <entry>Contents</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>int</entry>
+ <entry>type</entry>
+ <entry>ClientMessage </entry>
+ </row>
+ <row>
+ <entry>u_long</entry>
+ <entry>serial</entry>
+ <entry>Set by the X Window System </entry>
+ </row>
+ <row>
+ <entry>Bool</entry>
+ <entry>send_event</entry>
+ <entry>Set by the X Window System </entry>
+ </row>
+ <row>
+ <entry>Display</entry>
+ <entry>*display</entry>
+ <entry>The display to which connects </entry>
+ </row>
+ <row>
+ <entry>Window</entry>
+ <entry>window</entry>
+ <entry>client communication window ID </entry>
+ </row>
+ <row>
+ <entry>Atom</entry>
+ <entry>message_type</entry>
+ <entry>XInternAtom(display, "_XIM_PROTOCOL", False)</entry>
+ </row>
+ <row>
+ <entry>int</entry>
+ <entry>format</entry>
+ <entry>32 </entry>
+ </row>
+ <row>
+ <entry>long</entry>
+ <entry>data.l[0]</entry>
+ <entry>length of read/write property ATOM </entry>
+ </row>
+ <row>
+ <entry>long</entry>
+ <entry>data.l[1]</entry>
+ <entry>read/write property ATOM </entry>
+ </row>
+ </tbody>
+ </tgroup>
+</table>
+
+<para>
+Closing Connection
+</para>
+
+<para>
+If the client disconnect with the IM Server, shutdown function should
+free the communication window properties and etc..
+</para>
+</appendix>
+</article>
Index: create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/XIM
===================================================================
--- create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/XIM (nonexistent)
+++ create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/XIM (revision 5)
Property changes on: create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/XIM
___________________________________________________________________
Added: svn:ignore
## -0,0 +1,73 ##
+
+# install dir
+dist
+
+# Target build dirs
+.a1x-newlib
+.a2x-newlib
+.at91sam7s-newlib
+
+.build-machine
+
+.a1x-glibc
+.a2x-glibc
+.h3-glibc
+.h5-glibc
+.i586-glibc
+.i686-glibc
+.imx6-glibc
+.jz47xx-glibc
+.makefile
+.am335x-glibc
+.omap543x-glibc
+.p5600-glibc
+.power8-glibc
+.power8le-glibc
+.power9-glibc
+.power9le-glibc
+.m1000-glibc
+.riscv64-glibc
+.rk328x-glibc
+.rk33xx-glibc
+.rk339x-glibc
+.s8xx-glibc
+.s9xx-glibc
+.x86_64-glibc
+
+# Hidden files (each file)
+.makefile
+.dist
+.rootfs
+
+# src & hw requires
+.src_requires
+.src_requires_depend
+.requires
+.requires_depend
+
+# Tarballs
+*.gz
+*.bz2
+*.lz
+*.xz
+*.tgz
+*.txz
+
+# Signatures
+*.asc
+*.sig
+*.sign
+*.sha1sum
+
+# Patches
+*.patch
+
+# Descriptions
+*.dsc
+*.txt
+
+# Default linux config files
+*.defconfig
+
+# backup copies
+*~
Index: create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/XKB/ch09.xml
===================================================================
--- create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/XKB/ch09.xml (nonexistent)
+++ create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/XKB/ch09.xml (revision 5)
@@ -0,0 +1,1145 @@
+<?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='Bells'>
+<title>Bells</title>
+<indexterm zone="Bells"><primary>bell</primary></indexterm>
+
+<para>
+The core X protocol allows only applications to explicitly sound the system
+bell with a given duration, pitch, and volume. Xkb extends this capability by
+allowing clients to attach symbolic names to bells, disable audible bells, and
+receive an event whenever the keyboard bell is rung. For the purposes of this
+document, the
+<firstterm>audible</firstterm>
+<indexterm significance="preferred" zone="Bells">
+<primary>audible bell</primary></indexterm>
+<indexterm significance="preferred" zone="Bells">
+<primary>bell</primary><secondary>audible</secondary></indexterm>
+bell is defined to be the system bell, or the default keyboard bell, as
+opposed to any other audible sound generated elsewhere in the system.
+</para>
+
+
+<para>
+You can ask to receive
+<symbol>XkbBellNotify</symbol>
+events (see <link linkend="Detecting_Bells">section 9.4</link>) when any client rings any one of the following:
+</para>
+
+<itemizedlist>
+<listitem>
+ <para>
+The default bell
+ </para>
+</listitem>
+<listitem>
+ <para>
+Any bell on an input device that can be specified by a
+<structfield>bell_class</structfield>
+and
+<structfield>bell_id</structfield>
+pair
+ </para>
+</listitem>
+<listitem>
+ <para>
+Any bell specified only by an arbitrary name. (This is, from the server’s
+point of view, merely a name, and not connected with any physical
+sound-generating device. Some client application must generate the sound, or
+visual feedback, if any, that is associated with the name.)
+ </para>
+</listitem>
+</itemizedlist>
+
+<para>
+You can also ask to receive
+<symbol>XkbBellNotify</symbol>
+events when the server rings the default bell or if any client has requested
+events only (without the bell sounding) for any of the bell types previously
+listed.
+</para>
+
+<para>
+You can disable audible bells on a global basis (to set the
+<emphasis>AudibleBell</emphasis>
+control, see <xref linkend="Keyboard_Controls" />). For example, a client that replaces the keyboard
+bell with some other audible cue might want to turn off the
+<emphasis>AudibleBell</emphasis>
+control to prevent the server from also generating a sound and avoid
+cacophony. If you disable audible bells and request to receive
+<symbol>XkbBellNotify</symbol>
+events, you can generate feedback different from the default bell.
+</para>
+
+
+<para>
+You can, however, override the
+<emphasis>AudibleBell</emphasis>
+control by calling one of the functions that force the ringing of a bell in
+spite of the setting of the
+<emphasis>AudibleBell</emphasis>
+control —
+<function>XkbForceDeviceBell</function>
+or
+<function>XkbForceBell</function>
+(see <link linkend="Forcing_a_Server_Generated_Bell">section 9.3.3</link>). In this case the server does not generate a bell event.
+</para>
+
+
+<para>
+Just as some keyboards can produce keyclicks to indicate when a key is pressed
+or repeating, Xkb can provide feedback for the controls by using special beep
+codes. The
+<emphasis>AccessXFeedback</emphasis>
+control is used to configure the specific types of operations that generate
+feedback. See <link linkend="The_AccessXFeedback_Control">section 10.6.3</link> for a discussion on
+<emphasis>AccessXFeedback</emphasis>
+control.
+</para>
+
+<para>
+This chapter describes bell names, the functions used to generate named bells,
+and the events the server generates for bells.
+</para>
+
+<sect1 id='Bell_Names'>
+<title>Bell Names</title>
+
+<para>
+You can associate a name to an act of ringing a bell by converting the name to
+an Atom and then using this name when you call the functions listed in this
+chapter. If an event is generated as a result, the name is then passed to all
+other clients interested in receiving
+<symbol>XkbBellNotify</symbol>
+events. Note that these are arbitrary names and that there is no binding to
+any sounds. Any sounds or other effects (such as visual bells on the screen)
+must be generated by a client application upon receipt of the bell event
+containing the name. There is no default name for the default keyboard bell.
+The server does generate some predefined bells for the AccessX controls (see
+<link linkend="The_AccessXFeedback_Control">section 10.6.3</link>).
+These named bells are shown in <link linkend="table9.1">Table 9.1</link>;
+the name is included
+in any bell event sent to clients that have requested to receive
+<symbol>XkbBellNotify</symbol>
+events.
+</para>
+
+<table id='table9.1' frame='topbot'>
+<title>Predefined Bells</title>
+<?dbfo keep-together="always" ?>
+<tgroup cols='2' align='left' colsep='0' rowsep='0'>
+<colspec colname='c1' colwidth='1.0*'/>
+<colspec colname='c2' colwidth='1.0*'/>
+<thead>
+<row rowsep='1'>
+ <entry>Action</entry>
+ <entry>Named Bell</entry>
+</row>
+</thead>
+<tbody>
+<row>
+ <entry>Indicator turned on</entry>
+ <entry>AX_IndicatorOn</entry>
+</row>
+<row>
+ <entry>Indicator turned off</entry>
+ <entry>AX_IndicatorOff</entry>
+</row>
+<row>
+ <entry>More than one indicator changed state</entry>
+ <entry>AX_IndicatorChange</entry>
+</row>
+<row>
+ <entry>Control turned on</entry>
+ <entry>AX_FeatureOn</entry>
+</row>
+<row>
+ <entry>Control turned off</entry>
+ <entry>AX_FeatureOff</entry>
+</row>
+<row>
+ <entry>More than one control changed state</entry>
+ <entry>AX_FeatureChange</entry>
+</row>
+<row>
+ <entry>SlowKeys and BounceKeys about to be turned on or off</entry>
+ <entry>AX_SlowKeysWarning</entry>
+</row>
+<row>
+ <entry>SlowKeys key pressed</entry>
+ <entry>AX_SlowKeyPress</entry>
+</row>
+<row>
+ <entry>SlowKeys key accepted</entry>
+ <entry>AX_SlowKeyAccept</entry>
+</row>
+<row>
+ <entry>SlowKeys key rejected</entry>
+ <entry>AX_SlowKeyReject</entry>
+</row>
+<row>
+ <entry>Accepted SlowKeys key released</entry>
+ <entry>AX_SlowKeyRelease</entry>
+</row>
+<row>
+ <entry>BounceKeys key rejected</entry>
+ <entry>AX_BounceKeyReject</entry>
+</row>
+<row>
+ <entry>StickyKeys key latched</entry>
+ <entry>AX_StickyLatch</entry>
+</row>
+<row>
+ <entry>StickyKeys key locked</entry>
+ <entry>AX_StickyLock</entry>
+</row>
+<row>
+ <entry>StickyKeys key unlocked</entry>
+ <entry>AX_StickyUnlock</entry>
+ </row>
+</tbody>
+</tgroup>
+</table>
+
+</sect1>
+<sect1 id='Audible_Bells'>
+<title>Audible Bells</title>
+
+<para>
+Using Xkb you can generate bell events that do not necessarily ring the system
+bell. This is useful if you need to use an audio server instead of the system
+beep. For example, when an audio client starts, it could disable the audible
+bell (the system bell) and then listen for
+<symbol>XkbBellNotify</symbol>
+events (see <link linkend="Detecting_Bells">section 9.4</link>). When it receives a
+<symbol>XkbBellNotify</symbol>
+event, the audio client could then send a request to an audio server to play a
+sound.
+</para>
+
+
+<para>
+You can control the audible bells feature by passing the
+<symbol>XkbAudibleBellMask</symbol>
+to
+<function>XkbChangeEnabledControls</function>
+(see <link linkend="The_EnabledControls_Control">section 10.1.1</link>). If you set
+<symbol>XkbAudibleBellMask</symbol>
+on, the server rings the system bell when a bell event occurs. This is the
+default. If you set
+<symbol>XkbAudibleBellMask</symbol>
+off and a bell event occurs, the server does not ring the system bell unless
+you call
+<function>XkbForceDeviceBell</function>
+or
+<function>XkbForceBell</function>
+(see <link linkend="Forcing_a_Server_Generated_Bell">section 9.3.3</link>).
+</para>
+
+<para>
+Audible bells are also part of the per-client auto-reset controls. For more
+information on auto-reset controls, see <link linkend="The_AutoReset_Control">section 10.1.2</link>.
+</para>
+
+</sect1>
+<sect1 id='Bell_Functions'>
+<title>Bell Functions</title>
+
+<para>
+Use the functions described in this section to ring bells and to generate bell
+events.
+</para>
+
+<para>
+The input extension has two types of feedbacks that can generate bells — bell
+feedback and keyboard feedback. Some of the functions in this section have
+<structfield>bell_class</structfield>
+and
+<structfield>bell_id</structfield>
+parameters; set them as follows: Set
+<structfield>bell_class</structfield>
+to
+<symbol>BellFeedbackClass</symbol>
+or
+<symbol>KbdFeedbackClass</symbol>.
+A device can have more than one feedback of each type; set
+<structfield>bell_id</structfield>
+to the particular bell feedback of
+<structfield>bell_class</structfield>
+type.
+</para>
+
+<para>
+<link linkend="table9.2">Table 9.2</link> shows the conditions that cause
+a bell to sound or an <structname>XkbBellNotifyEvent</structname>
+to be generated when a bell function is called.
+</para>
+
+<table id='table9.2' frame='topbot'>
+<title>Bell Sounding and Bell Event Generating</title>
+<?dbfo keep-together="always" ?>
+<tgroup cols='4' align='left' colsep='0' rowsep='0'>
+<colspec colname='c1' colwidth='1.0*'/>
+<colspec colname='c2' colwidth='1.0*'/>
+<colspec colname='c3' colwidth='1.0*'/>
+<colspec colname='c4' colwidth='1.0*'/>
+<thead>
+ <row rowsep='1'>
+ <entry>Function called</entry>
+ <entry>AudibleBell</entry>
+ <entry>Server sounds a bell</entry>
+ <entry>Server sends an XkbBellNotifyEvent</entry>
+ </row>
+</thead>
+<tbody>
+<row>
+ <entry>XkbDeviceBell</entry>
+ <entry>On</entry>
+ <entry>Yes</entry>
+ <entry>Yes</entry>
+</row>
+<row>
+ <entry>XkbDeviceBell</entry>
+ <entry>Off</entry>
+ <entry>No</entry>
+ <entry>Yes</entry>
+</row>
+<row>
+ <entry>XkbBell</entry>
+ <entry>On</entry>
+ <entry>Yes</entry>
+ <entry>Yes</entry>
+</row>
+<row>
+ <entry>XkbBell</entry>
+ <entry>Off</entry>
+ <entry>No</entry>
+ <entry>Yes</entry>
+</row>
+<row>
+ <entry>XkbDeviceBellEvent</entry>
+ <entry>On or Off</entry>
+ <entry>No</entry>
+ <entry>Yes</entry>
+</row>
+<row>
+ <entry>XkbBellEvent</entry>
+ <entry>On or Off</entry>
+ <entry>No</entry>
+ <entry>Yes</entry>
+</row>
+<row>
+ <entry>XkbDeviceForceBell</entry>
+ <entry>On or Off</entry>
+ <entry>Yes</entry>
+ <entry>No</entry>
+</row>
+<row>
+ <entry>XkbForceBell</entry>
+ <entry>On or Off</entry>
+ <entry>Yes</entry>
+ <entry>No</entry>
+ </row>
+</tbody>
+</tgroup>
+</table>
+
+<sect2 id='Generating_Named_Bells'>
+<title>Generating Named Bells</title>
+
+<para>
+To ring the bell on an X input extension device or the default keyboard, use
+<function>XkbDeviceBell</function>.
+</para>
+
+<indexterm significance="preferred" zone="XkbDeviceBell"><primary><function>XkbDeviceBell</function></primary></indexterm>
+<funcsynopsis id="XkbDeviceBell">
+ <funcprototype>
+ <funcdef>Bool <function>XkbDeviceBell</function></funcdef>
+<!-- (
+<parameter>display, window, device_id, bell_class, bell_id, percent, name</parameter>
+) -->
+
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>Window <parameter>window</parameter></paramdef>
+ <paramdef>unsigned int <parameter>device_spec</parameter></paramdef>
+ <paramdef>unsigned int <parameter>bell_class</parameter></paramdef>
+ <paramdef>unsigned int <parameter>bell_id</parameter></paramdef>
+ <paramdef>int <parameter>percent</parameter></paramdef>
+ <paramdef>Atom <parameter>name</parameter></paramdef>
+ </funcprototype>
+</funcsynopsis>
+<variablelist>
+ <varlistentry>
+ <term>
+ <parameter>display</parameter>
+ </term>
+ <listitem>
+ <para>
+ connection to the X server
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>window</parameter>
+ </term>
+ <listitem>
+ <para>
+ window for which the bell is generated, or None
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>device_spec</parameter>
+ </term>
+ <listitem>
+ <para>
+ device ID, or <symbol>XkbUseCoreKbd</symbol>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>bell_class</parameter>
+ </term>
+ <listitem>
+ <para>
+ X input extension bell class of the bell to be rung
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>bell_id</parameter>
+ </term>
+ <listitem>
+ <para>
+ X input extension bell ID of the bell to be rung
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>percent</parameter>
+ </term>
+ <listitem>
+ <para>
+ bell volume, from −100 to 100 inclusive
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>name</parameter>
+ </term>
+ <listitem>
+ <para>
+ a name for the bell, or <symbol>NULL</symbol>
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+Set
+<parameter>percent</parameter>
+to be the volume relative to the base volume for the keyboard as described for
+<function>XBell</function>.
+</para>
+
+<para>
+Note that
+<parameter>bell_class</parameter>
+and
+<parameter>bell_id</parameter>
+indicate the bell to physically ring.
+<parameter>name</parameter>
+is simply an arbitrary moniker for the client application’s use.
+</para>
+
+<para>
+To determine the current feedback settings of an extension input device, use
+<function>XGetFeedbackControl</function>.
+See the X input extension documentation for more information on
+<function>XGetFeedbackControl</function>
+and related data structures.
+</para>
+
+<para>
+If a compatible keyboard extension is not present in the X server,
+<function>XkbDeviceBell</function>
+immediately returns
+<symbol>False</symbol>.
+Otherwise,
+<function>XkbDeviceBell</function>
+rings the bell as specified for the display and keyboard device and returns
+<symbol>True</symbol>.
+If you have disabled the audible bell, the server does not ring the system
+bell, although it does generate a
+<symbol>XkbBellNotify</symbol>
+event.
+</para>
+
+<para>
+You can call
+<function>XkbDeviceBell</function>
+without first initializing the keyboard extension.
+</para>
+
+<para>
+As a convenience function, Xkb provides a function to ring the bell on the
+default keyboard:
+<function>XkbBell</function>.
+</para>
+
+<indexterm significance="preferred" zone="XkbBell"><primary><function>XkbBell</function></primary></indexterm>
+<funcsynopsis id="XkbBell">
+ <funcprototype>
+ <funcdef>Bool <function>XkbBell</function></funcdef>
+<!-- (
+<parameter>display, window, percent, name</parameter>
+) -->
+
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>Window <parameter>window</parameter></paramdef>
+ <paramdef>int <parameter>percent</parameter></paramdef>
+ <paramdef>Atom <parameter>name</parameter></paramdef>
+ </funcprototype>
+</funcsynopsis>
+<variablelist>
+ <varlistentry>
+ <term>
+ <parameter>display</parameter>
+ </term>
+ <listitem>
+ <para>
+ connection to the X server
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>window</parameter>
+ </term>
+ <listitem>
+ <para>
+ event window, or None
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>percent</parameter>
+ </term>
+ <listitem>
+ <para>
+ relative volume, which can range from −100 to 100 inclusive
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>name</parameter>
+ </term>
+ <listitem>
+ <para>
+ a bell name, or <symbol>NULL</symbol>
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+If a compatible keyboard extension isn’t present in the X server,
+<function>XkbBell</function>
+calls
+<function>XBell</function>
+with the specified
+<parameter>display</parameter>
+and
+<parameter>percent</parameter>,
+and returns
+<symbol>False</symbol>.
+Otherwise,
+<function>XkbBell</function>
+calls
+<function>XkbDeviceBell</function>
+with the specified
+<parameter>display</parameter>,
+<parameter>window</parameter>,
+<parameter>percent</parameter>,
+and
+<parameter>name</parameter>,
+a
+<structfield>device_spec</structfield>
+of
+<symbol>XkbUseCoreKbd</symbol>,
+a
+<structfield>bell_class</structfield>
+of
+<symbol>XkbDfltXIClass</symbol>,
+and a
+<structfield>bell_id</structfield>
+of
+<symbol>XkbDfltXIId</symbol>,
+and returns
+<symbol>True</symbol>.
+</para>
+
+<para>
+If you have disabled the audible bell, the server does not ring the system
+bell, although it does generate a
+<symbol>XkbBellNotify</symbol>
+event.
+</para>
+
+<para>
+You can call
+<function>XkbBell</function>
+without first initializing the keyboard extension.
+</para>
+
+</sect2>
+<sect2 id='Generating_Named_Bell_Events'>
+<title>Generating Named Bell Events</title>
+
+<para>
+Using Xkb, you can also generate a named bell event that does not ring any
+bell. This allows you to do things such as generate events when your
+application starts.
+</para>
+
+<para>
+For example, if an audio client listens for these types of bells, it can
+produce a <quote>whoosh</quote> sound when it receives a named bell event to indicate a
+client just started. In this manner, applications can generate start-up
+feedback and not worry about producing annoying beeps if an audio server is not
+running.
+</para>
+
+
+<para>
+To cause a bell event for an X input extension device or for the keyboard,
+without ringing the corresponding bell, use
+<function>XkbDeviceBellEvent</function>.
+</para>
+
+<indexterm significance="preferred" zone="XkbDeviceBellEvent"><primary><function>XkbDeviceBellEvent</function></primary></indexterm>
+<funcsynopsis id="XkbDeviceBellEvent">
+ <funcprototype>
+ <funcdef>Bool <function>XkbDeviceBellEvent</function></funcdef>
+<!-- (
+<parameter>display, window, device_spec, bell_class, bell_id, percent, name</parameter>
+) -->
+
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>Window <parameter>window</parameter></paramdef>
+ <paramdef>unsigned int <parameter>device_spec</parameter></paramdef>
+ <paramdef>unsigned int <parameter>bell_class</parameter></paramdef>
+ <paramdef>unsigned int <parameter>bell_id</parameter></paramdef>
+ <paramdef>int <parameter>percent</parameter></paramdef>
+ <paramdef>Atom <parameter>name</parameter></paramdef>
+ </funcprototype>
+</funcsynopsis>
+<variablelist>
+ <varlistentry>
+ <term>
+ <parameter>display</parameter>
+ </term>
+ <listitem>
+ <para>
+ connection to the X server
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>window</parameter>
+ </term>
+ <listitem>
+ <para>
+ event window, or None
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>device_spec</parameter>
+ </term>
+ <listitem>
+ <para>
+ device ID, or <symbol>XkbUseCoreKbd</symbol>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>bell_class</parameter>
+ </term>
+ <listitem>
+ <para>
+ input extension bell class for the event
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>bell_id</parameter>
+ </term>
+ <listitem>
+ <para>
+ input extension bell ID for the event
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>percent</parameter>
+ </term>
+ <listitem>
+ <para>
+ volume for the bell, which can range from −100 to 100 inclusive
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>name</parameter>
+ </term>
+ <listitem>
+ <para>
+ a bell name, or <symbol>NULL</symbol>
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+If a compatible keyboard extension isn’t present in the X server,
+<function>XkbDeviceBellEvent</function>
+immediately returns
+<symbol>False</symbol>.
+Otherwise,
+<function>XkbDeviceBellEvent</function>
+causes an
+<symbol>XkbBellNotify</symbol>
+event to be sent to all interested clients and returns
+<symbol>True</symbol>.
+Set
+<parameter>percent</parameter>
+to be the volume relative to the base volume for the keyboard as described for
+<function>XBell</function>.
+</para>
+
+
+<para>
+In addition,
+<function>XkbDeviceBellEvent</function>
+may generate
+<type>Atom</type>
+protocol errors as well as
+<symbol>XkbBellNotify</symbol>
+events. You can call
+<function>XkbBell</function>
+without first initializing the keyboard extension.
+</para>
+
+
+<para>
+As a convenience function, Xkb provides a function to cause a bell event for
+the keyboard without ringing the bell:
+<function>XkbBellEvent</function>.
+</para>
+
+
+<indexterm significance="preferred" zone="XkbBellEvent"><primary><function>XkbBellEvent</function></primary></indexterm>
+<funcsynopsis id="XkbBellEvent">
+ <funcprototype>
+ <funcdef>Bool <function>XkbBellEvent</function></funcdef>
+<!-- (
+<parameter>display, window, percent, name</parameter>
+) -->
+
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>Window <parameter>window</parameter></paramdef>
+ <paramdef>int <parameter>percent</parameter></paramdef>
+ <paramdef>Atom <parameter>name</parameter></paramdef>
+ </funcprototype>
+</funcsynopsis>
+<variablelist>
+ <varlistentry>
+ <term>
+ <parameter>display</parameter>
+ </term>
+ <listitem>
+ <para>
+ connection to the X server
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>window</parameter>
+ </term>
+ <listitem>
+ <para>
+ the event window, or None
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>percent</parameter>
+ </term>
+ <listitem>
+ <para>
+ relative volume, which can range from −100 to 100 inclusive
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>name</parameter>
+ </term>
+ <listitem>
+ <para>
+ a bell name, or <symbol>NULL</symbol>
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+If a compatible keyboard extension isn’t present in the X server,
+<function>XkbBellEvent</function>
+immediately returns
+<symbol>False</symbol>.
+Otherwise,
+<function>XkbBellEvent</function>
+calls
+<function>XkbDeviceBellEvent</function>
+with the specified
+<parameter>display</parameter>,
+<parameter>window</parameter>,
+<parameter>percent</parameter>,
+and
+<parameter>name</parameter>,
+a
+<structfield>device_spec</structfield>
+of
+<symbol>XkbUseCoreKbd</symbol>,
+a
+<structfield>bell_class</structfield>
+of
+<symbol>XkbDfltXIClass</symbol>,
+and a
+<structfield>bell_id</structfield>
+of
+<symbol>XkbDfltXIId</symbol>,
+and returns what
+<function>XkbDeviceBellEvent</function>
+returns.
+</para>
+
+<para>
+<function>XkbBellEvent</function>
+generates a <symbol>XkbBellNotify</symbol>
+event.
+</para>
+
+
+<para>
+You can call
+<function>XkbBellEvent</function>
+without first initializing the keyboard extension.
+</para>
+
+</sect2>
+<sect2 id='Forcing_a_Server_Generated_Bell'>
+<title>Forcing a Server-Generated Bell</title>
+
+<para>
+To ring the bell on any keyboard, overriding user preference settings for
+audible bells, use <function>XkbForceDeviceBell</function>.
+</para>
+
+<indexterm significance="preferred" zone="XkbForceDeviceBell"><primary><function>XkbForceDeviceBell</function></primary></indexterm>
+<funcsynopsis id="XkbForceDeviceBell">
+ <funcprototype>
+ <funcdef>Bool <function>XkbForceDeviceBell</function></funcdef>
+<!-- (
+<parameter>display, window, device_spec, bell_class, bell_id, percent</parameter>
+) -->
+
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>Window <parameter>window</parameter></paramdef>
+ <paramdef>unsigned int <parameter>device_spec</parameter></paramdef>
+ <paramdef>unsigned int <parameter>bell_class</parameter></paramdef>
+ <paramdef>unsigned int <parameter>bell_id</parameter></paramdef>
+ <paramdef>int <parameter>percent</parameter></paramdef>
+ </funcprototype>
+</funcsynopsis>
+<variablelist>
+ <varlistentry>
+ <term>
+ <parameter>display</parameter>
+ </term>
+ <listitem>
+ <para>
+ connection to the X server
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>window</parameter>
+ </term>
+ <listitem>
+ <para>
+ event window, or None
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>device_spec</parameter>
+ </term>
+ <listitem>
+ <para>
+ device ID, or <symbol>XkbUseCoreKbd</symbol>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>bell_class</parameter>
+ </term>
+ <listitem>
+ <para>
+ input extension class of the bell to be rung
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>bell_id</parameter>
+ </term>
+ <listitem>
+ <para>
+ input extension ID of the bell to be rung
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>percent</parameter>
+ </term>
+ <listitem>
+ <para>
+ relative volume, which can range from −100 to 100 inclusive
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+If a compatible keyboard extension isn’t present in the X server,
+<function>XkbForceDeviceBell</function>
+immediately returns
+<symbol>False</symbol>.
+Otherwise,
+<function>XkbForceDeviceBell</function>
+rings the bell as specified for the display and keyboard device and returns
+<symbol>True</symbol>.
+Set
+<parameter>percent</parameter>
+to be the volume relative to the base volume for the keyboard as described for
+<function>XBell</function>.
+There is no
+<structfield>name</structfield>
+parameter because
+<function>XkbForceDeviceBell</function>
+does not cause an
+<symbol>XkbBellNotify</symbol>
+event.
+</para>
+
+<para>
+You can call
+<function>XkbBell</function>
+without first initializing the keyboard extension.
+</para>
+
+<para>
+To ring the bell on the default keyboard, overriding user preference settings
+for audible bells, use
+<function>XkbForceBell</function>.
+</para>
+
+<indexterm significance="preferred" zone="XkbForceBell"><primary><function>XkbForceBell</function></primary></indexterm>
+<funcsynopsis id="XkbForceBell">
+ <funcprototype>
+ <funcdef>Bool <function>XkbForceBell</function></funcdef>
+<!-- (
+<parameter>display, percent)</parameter> -->
+
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>int <parameter>percent</parameter></paramdef>
+ </funcprototype>
+</funcsynopsis>
+<variablelist>
+ <varlistentry>
+ <term>
+ <parameter>display</parameter>
+ </term>
+ <listitem>
+ <para>
+ connection to the X server
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>percent</parameter>
+ </term>
+ <listitem>
+ <para>
+ volume for the bell, which can range from −100 to 100 inclusive
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+If a compatible keyboard extension isn’t present in the X server,
+<function>XkbForceBell</function>
+calls
+<function>XBell</function>
+with the specified
+<parameter>display</parameter>
+and
+<parameter>percent</parameter>
+and returns
+<symbol>False</symbol>.
+Otherwise,
+<function>XkbForceBell</function>
+calls
+<function>XkbForceDeviceBell</function>
+with the specified
+<parameter>display</parameter>
+and
+<parameter>percent</parameter>,
+<structfield>device_spec</structfield>
+=
+<symbol>XkbUseCoreKbd</symbol>,
+<structfield>bell_class</structfield>
+=
+<symbol>XkbDfltXIClass</symbol>,
+<structfield>bell_id</structfield>
+=
+<symbol>XkbDfltXIId</symbol>,
+<structfield>window</structfield>
+= None, and
+<structfield>name</structfield>
+=
+<symbol>NULL</symbol>,
+and returns what
+<function>XkbForceDeviceBell</function>
+returns.
+</para>
+
+<para>
+<function>XkbForceBell</function>
+does not cause an
+<symbol>XkbBellNotify</symbol>
+event.
+</para>
+
+<para>
+You can call
+<function>XkbBell</function>
+without first initializing the keyboard extension.
+</para>
+
+</sect2>
+</sect1>
+<sect1 id='Detecting_Bells'>
+<title>Detecting Bells</title>
+
+<para>
+Xkb generates
+<symbol>XkbBellNotify</symbol>
+events for all bells except for those resulting from calls to
+<function>XkbForceDeviceBell</function>
+and
+<function>XkbForceBell</function>.
+To receive
+<symbol>XkbBellNotify</symbol>
+events under all possible conditions, pass
+<symbol>XkbBellNotifyMask</symbol>
+in both the
+<parameter>bits_to_change</parameter>
+and
+<parameter>values_for_bits</parameter>
+parameters to
+<function>XkbSelectEvents</function>
+(see <link linkend="Selecting_Xkb_Events">section 4.3</link>).
+</para>
+
+<para>
+The
+<symbol>XkbBellNotify</symbol>
+event has no event details. It is either selected or it is not. However, you
+can call
+<function>XkbSelectEventDetails</function>
+using
+<symbol>XkbBellNotify</symbol>
+as the
+<structfield>event_type</structfield>
+and specifying
+<symbol>XkbAllBellEventsMask</symbol>
+in
+<parameter>bits_to_change</parameter>
+and
+<parameter>values_for_bits</parameter>.
+This has the same effect as a call to
+<function>XkbSelectEvents</function>.
+</para>
+
+<para>
+The structure for the
+<symbol>XkbBellNotify</symbol>
+event type contains:
+
+<programlisting>
+typedef struct _XkbBellNotify {
+ int type; /* Xkb extension base event code */
+ unsigned long serial; /* X server serial number for event */
+ Bool send_event; /* <symbol>True</symbol> ⇒ synthetically generated */
+ Display * display; /* server connection where event generated */
+ Time time; /* server time when event generated */
+ int xkb_type; /* <symbol>XkbBellNotify</symbol> */
+ unsigned int device; /* Xkb device ID, will not be <symbol>XkbUseCoreKbd</symbol> */
+ int percent; /* requested volume as % of max */
+ int pitch; /* requested pitch in Hz */
+ int duration; /* requested duration in microseconds */
+ unsigned int bell_class; /* X input extension feedback class */
+ unsigned int bell_id; /* X input extension feedback ID */
+ Atom name; /* "name" of requested bell */
+ Window window; /* window associated with event */
+ Bool event_only; /* <symbol>False</symbol> → the server did not produce a beep */
+} <structname>XkbBellNotifyEvent</structname>;
+</programlisting></para>
+
+<para>
+If your application needs to generate visual bell feedback on the screen when
+it receives a bell event, use the window ID in the
+<structname>XkbBellNotifyEvent</structname>,
+if present.
+</para>
+
+</sect1>
+</chapter>
Index: create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/XKB/ch10.xml
===================================================================
--- create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/XKB/ch10.xml (nonexistent)
+++ create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/XKB/ch10.xml (revision 5)
@@ -0,0 +1,5383 @@
+<?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='Keyboard_Controls'>
+<title>Keyboard Controls</title>
+
+<indexterm significance="preferred" zone="Keyboard_Controls">
+<primary>controls</primary></indexterm>
+<indexterm significance="preferred" zone="Keyboard_Controls">
+<primary>server controls</primary></indexterm>
+<indexterm significance="preferred" zone="Keyboard_Controls">
+<primary>controls</primary><secondary>server</secondary></indexterm>
+
+<para>
+The Xkb extension is composed of two parts: a server extension, and a
+client-side X library extension. This chapter discusses functions used to
+modify controls effecting the behavior of the server portion of the Xkb
+extension. <xref linkend="X_Library_Controls" /> discusses functions used to modify controls that affect
+only the behavior of the client portion of the extension; those controls are
+known as Library Controls.
+</para>
+
+
+<para>
+Xkb contains control features that affect the entire keyboard, known as global
+keyboard controls. Some of the controls may be selectively enabled and
+disabled; these controls are known as the
+<firstterm>Boolean Controls</firstterm>.
+<indexterm significance="preferred" zone="Keyboard_Controls">
+<primary>boolean controls</primary></indexterm>
+<indexterm significance="preferred" zone="Keyboard_Controls">
+<primary>controls</primary><secondary>boolean</secondary></indexterm>
+Boolean Controls can be turned on or off under program control and can also
+be automatically set to an on or off condition when a client program exits. The
+remaining controls, known as the
+<firstterm>Non-Boolean Controls</firstterm>,
+<indexterm significance="preferred" zone="Keyboard_Controls">
+<primary>non-boolean controls</primary></indexterm>
+<indexterm significance="preferred" zone="Keyboard_Controls">
+<primary>controls</primary><secondary>non-boolean</secondary></indexterm>
+are always active. The
+<structname>XkbControlsRec</structname>
+structure describes the current state of most of the global controls and the
+attributes effecting the behavior of each of these Xkb features. This chapter
+describes the Xkb controls and how to manipulate them.
+</para>
+
+
+<para>
+There are two possible components for each of the Boolean Controls: attributes
+describing how the control should work, and a state describing whether the
+behavior as a whole is enabled or disabled. The attributes and state for most
+of these controls are held in the
+<structname>XkbControlsRec</structname>
+structure (see <link linkend="The_XkbControlsRec_Structure">section 10.8</link>).
+</para>
+
+
+<para>
+You can manipulate the Xkb controls individually, via convenience functions, or
+as a whole. To treat them as a group, modify an
+<structname>XkbControlsRec</structname>
+structure to describe all of the changes to be made, and then pass that
+structure and appropriate flags to an Xkb library function, or use a
+<structname>XkbControlsChangesRec</structname>
+(see <link linkend="The_XkbControlsChangesRec_Structure">section 10.10.1</link>) to reduce network traffic. When using a convenience
+function to manipulate one control individually, you do not use an
+<structname>XkbControlsRec</structname>
+structure directly.
+</para>
+
+
+<para>
+The Xkb controls are grouped as shown in
+<link linkend="table10.1">Table 10.1</link>.
+</para>
+
+<table id='table10.1' frame='topbot'>
+<title>Xkb Keyboard Controls</title>
+<?dbfo keep-together="always" ?>
+<tgroup cols='3' align='left' colsep='0' rowsep='0'>
+<colspec colname='c1' colwidth='1.5*'/>
+<colspec colname='c2' colwidth='1.5*'/>
+<colspec colname='c3' colwidth='1.0*'/>
+<thead>
+<row rowsep='1'>
+ <entry>Type of Control</entry>
+ <entry>Control Name</entry>
+ <entry>Boolean Control?</entry>
+ </row>
+</thead>
+<tbody>
+ <row>
+ <entry>Controls for enabling and disabling other controls</entry>
+ <entry>EnabledControls</entry>
+ <entry>No</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>AutoReset</entry>
+ <entry>No</entry>
+ </row>
+ <row>
+ <entry>Control for bell behavior</entry>
+ <entry>AudibleBell</entry>
+ <entry>Boolean</entry>
+ </row>
+ <row>
+ <entry>Controls for repeat key behavior</entry>
+ <entry>PerKeyRepeat</entry>
+ <entry>No</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>RepeatKeys</entry>
+ <entry>Boolean</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>DetectableAutorepeat</entry>
+ <entry>Boolean</entry>
+ </row>
+ <row>
+ <entry>Controls for keyboard overlays</entry>
+ <entry>Overlay1</entry>
+ <entry>Boolean</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>Overlay2</entry>
+ <entry>Boolean</entry>
+ </row>
+ <row>
+ <entry>Controls for using the mouse from the keyboard</entry>
+ <entry>MouseKeys</entry>
+ <entry>Boolean</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>MouseKeysAccel</entry>
+ <entry>Boolean</entry>
+ </row>
+ <row>
+ <entry>Controls for better keyboard access by </entry>
+ <entry>AccessXFeedback</entry>
+ <entry>Boolean</entry>
+ </row>
+ <row>
+ <entry>physically impaired persons</entry>
+ <entry>AccessXKeys</entry>
+ <entry>Boolean</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>AccessXTimeout</entry>
+ <entry>Boolean</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>BounceKeys</entry>
+ <entry>Boolean</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>SlowKeys</entry>
+ <entry>Boolean</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>StickyKeys</entry>
+ <entry>Boolean</entry>
+ </row>
+ <row>
+ <entry>Controls for general keyboard mapping</entry>
+ <entry>GroupsWrap</entry>
+ <entry>No</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>IgnoreGroupLock</entry>
+ <entry>Boolean</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>IgnoreLockMods</entry>
+ <entry>No</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>InternalMods</entry>
+ <entry>No</entry>
+ </row>
+ <row>
+ <entry>Miscellaneous per-client controls</entry>
+ <entry>GrabsUseXKBState</entry>
+ <entry>Boolean</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>LookupStateWhenGrabbed</entry>
+ <entry>Boolean</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>SendEventUsesXKBState</entry>
+ <entry>Boolean</entry>
+ </row>
+</tbody>
+</tgroup>
+</table>
+
+<para>
+The individual categories and controls are described first, together with
+functions for manipulating them. A description of the
+<structname>XkbControlsRec</structname>
+structure and the general functions for dealing with all of the controls at
+once follow at the end of the chapter.
+</para>
+
+<sect1 id='Controls_that_Enable_and_Disable_Other_Controls'>
+<title>Controls that Enable and Disable Other Controls</title>
+
+<para>
+Enable and disable the boolean controls under program control by using the
+<emphasis>EnabledControls</emphasis>
+control; enable and disable them upon program exit by configuring the
+<emphasis>AutoReset</emphasis>
+control.
+</para>
+
+
+<sect2 id='The_EnabledControls_Control'>
+<title>The EnabledControls Control</title>
+
+<para>
+The
+<emphasis>EnabledControls</emphasis>
+control is a bit mask where each bit that is turned on means the corresponding
+control is enabled, and when turned off, disabled. It corresponds to the
+<structfield>enabled_ctrls</structfield>
+field of an
+<structname>XkbControlsRec</structname>
+structure (see <link linkend="The_XkbControlsRec_Structure">section 10.8</link>). The bits describing which controls are turned on
+or off are defined in <link linkend="table10.7">Table 10.7</link>.
+</para>
+
+
+<para>
+Use
+<function>XkbChangeEnabledControls</function>
+to manipulate the
+<emphasis>EnabledControls</emphasis>
+control.
+</para>
+
+<indexterm significance="preferred" zone="XkbChangeEnabledControls"><primary><function>XkbChangeEnabledControls</function></primary></indexterm>
+<funcsynopsis id="XkbChangeEnabledControls">
+ <funcprototype>
+ <funcdef>Bool <function>XkbChangeEnabledControls</function></funcdef>
+<!-- (
+<parameter>dpy</parameter>,
+<parameter>device_spec</parameter>,
+<parameter>mask</parameter>,
+<parameter>values</parameter>
+) -->
+
+ <paramdef>Display *<parameter>dpy</parameter></paramdef>
+ <paramdef>unsigned int <parameter>device_spec</parameter></paramdef>
+ <paramdef>unsigned int <parameter>mask</parameter></paramdef>
+ <paramdef>unsigned int <parameter>values</parameter></paramdef>
+ </funcprototype>
+</funcsynopsis>
+<variablelist>
+ <varlistentry>
+ <term>
+ <parameter>dpy</parameter>
+ </term>
+ <listitem>
+ <para>
+ connection to X server
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>device_spec</parameter>
+ </term>
+ <listitem>
+ <para>
+ keyboard device to modify
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>mask</parameter>
+ </term>
+ <listitem>
+ <para>
+ 1 bit → controls to enable / disable
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>values</parameter>
+ </term>
+ <listitem>
+ <para>
+ 1 bit ⇒ enable, 0 bit ⇒ disable
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<parameter>mask</parameter>
+parameter specifies the boolean controls to be enabled or disabled, and the
+<parameter>values</parameter>
+mask specifies the new state for those controls. Valid values for both of
+these masks are composed of a bitwise inclusive OR of bits taken from the set
+of mask bits in <link linkend="table10.7">Table 10.7</link>,
+using only those masks with <quote>ok</quote> in the
+<structfield>enabled_ctrls</structfield>
+column.
+</para>
+
+
+<para>
+If the X server does not support a compatible version of Xkb or the Xkb
+extension has not been properly initialized,
+<function>XkbChangeEnabledControls</function>
+returns
+<symbol>False</symbol>;
+otherwise, it sends the request to the X server and returns
+<symbol>True</symbol>.
+</para>
+
+
+<para>
+Note that the
+<emphasis>EnabledControls</emphasis>
+control only enables and disables controls; it does not configure them. Some
+controls, such as the
+<emphasis>AudibleBell</emphasis>
+control, have no configuration attributes and are therefore manipulated solely
+by enabling and disabling them. Others, however, have additional attributes to
+configure their behavior. For example, the
+<emphasis>RepeatControl</emphasis>
+control uses
+<structfield>repeat_delay</structfield>
+and
+<structfield>repeat_interval</structfield>
+fields to describe the timing behavior of keys that repeat. The
+<emphasis>RepeatControl</emphasis>
+behavior is turned on or off depending on the value of the
+<symbol>XkbRepeatKeysMask</symbol>
+bit, but you must use other means, as described in this chapter, to configure
+its behavior in detail.
+</para>
+
+
+</sect2>
+<sect2 id='The_AutoReset_Control'>
+<title>The AutoReset Control</title>
+
+<para>
+You can configure the boolean controls to automatically be enabled or disabled
+when a program exits. This capability is controlled via two masks maintained in
+the X server on a per-client basis. There is no client-side Xkb data structure
+corresponding to these masks. Whenever the client exits for any reason, any
+boolean controls specified in the
+<firstterm>auto-reset mask</firstterm>
+<indexterm significance="preferred" zone="The_AutoReset_Control">
+<primary>auto-reset mask</primary></indexterm>
+<indexterm significance="preferred" zone="The_AutoReset_Control">
+<primary>mask</primary><secondary>auto-reset</secondary></indexterm>
+are set to the corresponding value from the
+<firstterm>auto-reset values</firstterm>
+mask. This makes it possible for clients to "clean up after themselves"
+automatically, even if abnormally terminated. The bits used in the masks
+correspond to the
+<emphasis>EnabledControls</emphasis>
+control bits.
+</para>
+
+
+<para>
+For example, a client that replaces the keyboard bell with some other audible
+cue might want to turn off the
+<emphasis>AudibleBell</emphasis>
+control to prevent the server from also generating a sound and avoid
+cacophony. If the client were to exit without resetting the
+<emphasis>AudibleBell</emphasis>
+control, the user would be left without any feedback at all. Setting
+<emphasis>AudibleBell</emphasis>
+in both the auto-reset mask and auto-reset values guarantees that the audible
+bell will be turned back on when the client exits.
+</para>
+
+
+<para>
+To get the current values of the auto-reset controls, use
+<function>XkbGetAutoResetControls</function>.
+</para>
+
+<indexterm significance="preferred" zone="XkbGetAutoResetControls"><primary><function>XkbGetAutoResetControls</function></primary></indexterm>
+<funcsynopsis id="XkbGetAutoResetControls">
+ <funcprototype>
+ <funcdef>Bool <function>XkbGetAutoResetControls</function></funcdef>
+<!-- (
+<parameter>dpy</parameter>,
+<parameter>auto_ctrls</parameter>,
+<parameter>auto_values</parameter>
+) -->
+
+ <paramdef>Display *<parameter>dpy</parameter></paramdef>
+ <paramdef>unsigned int *<parameter>auto_ctrls</parameter></paramdef>
+ <paramdef>unsigned int *<parameter>auto_values</parameter></paramdef>
+ </funcprototype>
+</funcsynopsis>
+<variablelist>
+ <varlistentry>
+ <term>
+ <parameter>dpy</parameter>
+ </term>
+ <listitem>
+ <para>
+ connection to X server
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>auto_ctrls</parameter>
+ </term>
+ <listitem>
+ <para>
+ specifies which bits in <parameter>auto_values</parameter> are relevant
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>auto_values</parameter>
+ </term>
+ <listitem>
+ <para>
+ 1 bit ⇒ corresponding control has auto-reset on
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<function>XkbGetAutoResetControls</function>
+backfills
+<parameter>auto_ctrls</parameter>
+and
+<parameter>auto_values</parameter>
+with the
+<emphasis>AutoReset</emphasis>
+control attributes for this particular client. It returns
+<symbol>True</symbol>
+if successful, and
+<symbol>False</symbol>
+otherwise.
+</para>
+
+
+<para>
+To change the current values of the
+<emphasis>AutoReset</emphasis>
+control attributes, use
+<function>XkbSetAutoResetControls</function>.
+</para>
+
+
+<indexterm significance="preferred" zone="XkbSetAutoResetControls"><primary><function>XkbSetAutoResetControls</function></primary></indexterm>
+<funcsynopsis id="XkbSetAutoResetControls">
+ <funcprototype>
+ <funcdef>Bool <function>XkbSetAutoResetControls</function></funcdef>
+<!-- (
+<parameter>dpy</parameter>,
+<parameter>changes</parameter>,
+<parameter>auto_ctrls</parameter>,
+<parameter>auto_values</parameter>
+) -->
+
+ <paramdef>Display *<parameter>dpy</parameter></paramdef>
+ <paramdef>unsigned int <parameter>changes</parameter></paramdef>
+ <paramdef>unsigned int *<parameter>auto_ctrls</parameter></paramdef>
+ <paramdef>unsigned int *<parameter>auto_values</parameter></paramdef>
+ </funcprototype>
+</funcsynopsis>
+<variablelist>
+ <varlistentry>
+ <term>
+ <parameter>dpy</parameter>
+ </term>
+ <listitem>
+ <para>
+ connection to X server
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>changes</parameter>
+ </term>
+ <listitem>
+ <para>
+ controls for which to change auto-reset values
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>auto_ctrls</parameter>
+ </term>
+ <listitem>
+ <para>
+ controls from changes that should auto reset
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>auto_values</parameter>
+ </term>
+ <listitem>
+ <para>
+ 1 bit ⇒ auto-reset on
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<function>XkbSetAutoResetControls</function>
+changes the auto-reset status and associated auto-reset
+values for the controls selected by
+<parameter>changes</parameter>.
+For any control selected by
+<parameter>changes</parameter>,
+if the corresponding bit is set in
+<parameter>auto_ctrls</parameter>,
+the control is configured to auto-reset when the client exits. If the
+corresponding bit in
+<parameter>auto_values</parameter>
+is on, the control is turned on when the client exits;
+if zero, the control is turned off when the client exits.
+For any control selected by
+<parameter>changes</parameter>,
+if the corresponding bit is not set in
+<parameter>auto_ctrls</parameter>,
+the control is configured to not reset when the client exits. For example:
+</para>
+
+
+<para>
+To leave the auto-reset controls for
+<emphasis>StickyKeys</emphasis>
+the way they are:
+
+<programlisting>
+ ok = XkbSetAutoResetControls(dpy, 0, 0, 0);
+</programlisting></para>
+
+<para>
+To change the auto-reset controls so that
+<emphasis>StickyKeys</emphasis>
+are unaffected when the client exits:
+
+<programlisting>
+ ok = XkbSetAutoResetControls(dpy, XkbStickyKeysMask, 0, 0);
+</programlisting></para>
+
+<para>
+To change the auto-reset controls so that
+<emphasis>StickyKeys</emphasis>
+are turned off when the client exits:
+
+<programlisting>
+ ok = XkbSetAutoResetControls(dpy, XkbStickyKeysMask, XkbStickyKeysMask, 0);
+</programlisting></para>
+
+<para>
+To change the auto-reset controls so that
+<emphasis>StickyKeys</emphasis>
+are turned on when the client exits:
+
+<programlisting>
+ ok = XkbSetAutoResetControls(dpy, XkbStickyKeysMask, XkbStickyKeysMask,
+ XkbStickyKeysMask);
+</programlisting></para>
+
+<para>
+<function>XkbSetAutoResetControls</function>
+backfills
+<parameter>auto_ctrls</parameter>
+and
+<parameter>auto_values</parameter>
+with the auto-reset controls for this particular client. Note that all of the
+bits are valid in the returned values, not just the ones selected in the
+<parameter>changes</parameter>
+mask.
+</para>
+
+
+</sect2>
+</sect1>
+<sect1 id='Control_for_Bell_Behavior'>
+<title>Control for Bell Behavior</title>
+
+<para>
+The X server’s generation of sounds is controlled by the
+<emphasis>AudibleBell</emphasis>
+control. Configuration of different bell sounds is discussed in <xref linkend="Bells" />.
+</para>
+
+
+<sect2 id='The_AudibleBell_Control'>
+<title>The AudibleBell Control</title>
+
+<para>
+The
+<emphasis>AudibleBell</emphasis>
+control is a boolean control that has no attributes. As such, you may enable
+and disable it using either the
+<emphasis>EnabledControls</emphasis>
+control or the
+<emphasis>AutoReset</emphasis>
+control discussed in <link linkend="The_EnabledControls_Control">section 10.1.1</link>. When enabled, protocol requests to
+generate a sound result in the X server actually producing a real sound; when
+disabled, requests to the server to generate a sound are ignored unless the
+sound is forced. See <link linkend="Audible_Bells">section 9.2</link>.
+</para>
+
+
+</sect2>
+</sect1>
+<sect1 id='Controls_for_Repeat_Key_Behavior'>
+<title>Controls for Repeat Key Behavior</title>
+
+<indexterm significance="preferred" zone="Controls_for_Repeat_Key_Behavior">
+<primary>auto-repeat</primary><secondary>controls</secondary></indexterm>
+
+<para>
+The repeating behavior of keyboard keys is governed by three controls, the
+<emphasis>PerKeyRepeat</emphasis>
+control, which is always active, and the
+<emphasis>RepeatKeys</emphasis>
+and
+<emphasis>DetectableAutorepeat</emphasis>
+controls, which are boolean controls that may be enabled and disabled.
+<emphasis>PerKeyRepeat</emphasis>
+determines which keys are allowed to repeat.
+<emphasis>RepeatKeys</emphasis>
+governs the behavior of an individual key when it is repeating.
+<emphasis>DetectableAutorepeat</emphasis>
+allows a client to detect when a key is repeating as a result of being held
+down.
+</para>
+
+
+<sect2 id='The_PerKeyRepeat_Control'>
+<title>The PerKeyRepeat Control</title>
+
+<para>
+The
+<emphasis>PerKeyRepeat</emphasis>
+control is a bitmask long enough to contain a bit for each key on the device;
+it determines which individual keys are allowed to repeat. The Xkb
+<emphasis>PerKeyRepeat</emphasis>
+control provides no functionality different from that available via the core X
+protocol. There are no convenience functions in Xkb for manipulating this
+control. The
+<emphasis>PerKeyRepeat</emphasis>
+control settings are carried in the
+<structfield>per_key_repeat</structfield>
+field of an
+<structname>XkbControlsRec</structname>
+structure, discussed in <link linkend="The_XkbControlsRec_Structure">section 10.8</link>.
+</para>
+
+
+</sect2>
+<sect2 id='The_RepeatKeys_Control'>
+<title>The RepeatKeys Control</title>
+
+<para>
+The core protocol allows only control over whether or not the entire keyboard
+or individual keys should auto-repeat when held down.
+<emphasis>RepeatKeys</emphasis>
+is a boolean control that extends this capability by adding control over the
+delay until a key begins to repeat and the rate at which it repeats.
+<emphasis>RepeatKeys</emphasis>
+is coupled with the core auto-repeat control: when
+<emphasis>RepeatKeys</emphasis>
+is enabled or disabled, the core auto-repeat is enabled or disabled and vice
+versa.
+</para>
+
+
+<para>
+Auto-repeating keys are controlled by two attributes. The first,
+<firstterm>timeout</firstterm>,
+is the delay after the initial press of an auto-repeating key and the first
+generated repeat event. The second,
+<firstterm>interval</firstterm>,
+is the delay between all subsequent generated repeat events. As with all
+boolean controls, configuring the attributes that determine how the control
+operates does not automatically enable the control as a whole; see <link linkend="Controls_that_Enable_and_Disable_Other_Controls">section 10.1</link>.
+</para>
+
+
+<para>
+To get the current attributes of the
+<emphasis>RepeatKeys</emphasis>
+control for a keyboard device, use
+<function>XkbGetAutoRepeatRate</function>.
+</para>
+
+<indexterm significance="preferred" zone="XkbGetAutoRepeatRate"><primary><function>XkbGetAutoRepeatRate</function></primary></indexterm>
+<funcsynopsis id="XkbGetAutoRepeatRate">
+ <funcprototype>
+ <funcdef>Bool <function>XkbGetAutoRepeatRate</function></funcdef>
+<!-- (
+<parameter>display, device_spec, timeout_rtrn, interval_rtrn</parameter>
+) -->
+
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>unsigned int <parameter>device_spec</parameter></paramdef>
+ <paramdef>unsigned int *<parameter>timeout_rtrn</parameter></paramdef>
+ <paramdef>unsigned int *<parameter>interval_rtrn</parameter></paramdef>
+ </funcprototype>
+</funcsynopsis>
+<variablelist>
+ <varlistentry>
+ <term>
+ <parameter>display</parameter>
+ </term>
+ <listitem>
+ <para>
+ connection to X server
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>device_spec</parameter>
+ </term>
+ <listitem>
+ <para>
+ desired device ID, or <symbol>XkbUseCoreKbd</symbol>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>timeout_rtrn</parameter>
+ </term>
+ <listitem>
+ <para>
+ backfilled with initial repeat delay, ms
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>interval_rtrn</parameter>
+ </term>
+ <listitem>
+ <para>
+ backfilled with subsequent repeat delay, ms
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<function>XkbGetAutoRepeatRate</function>
+queries the server for the current values of the
+<emphasis>RepeatControls</emphasis>
+control attributes, backfills
+<parameter>timeout_rtrn</parameter>
+and
+<parameter>interval_rtrn</parameter>
+with them, and returns
+<symbol>True</symbol>.
+If a compatible version of the Xkb extension is not available in the server
+<function>XkbGetAutoRepeatRate</function>
+returns
+<symbol>False</symbol>.
+</para>
+
+
+<para>
+To set the attributes of the RepeatKeys control for a keyboard device, use
+<function>XkbSetAutoRepeatRate</function>.
+</para>
+
+
+<indexterm significance="preferred" zone="XkbSetAutoRepeatRate"><primary><function>XkbSetAutoRepeatRate</function></primary></indexterm>
+<funcsynopsis id="XkbSetAutoRepeatRate">
+ <funcprototype>
+ <funcdef>Bool <function>XkbSetAutoRepeatRate</function></funcdef>
+<!-- (
+<parameter>display, device_spec, timeout, interval</parameter>
+) -->
+
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>unsigned int <parameter>device_spec</parameter></paramdef>
+ <paramdef>unsigned int <parameter>timeout</parameter></paramdef>
+ <paramdef>unsigned int <parameter>interval</parameter></paramdef>
+ </funcprototype>
+</funcsynopsis>
+<variablelist>
+ <varlistentry>
+ <term>
+ <parameter>display</parameter>
+ </term>
+ <listitem>
+ <para>
+ connection to X server
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>device_spec</parameter>
+ </term>
+ <listitem>
+ <para>
+ device to configure, or <symbol>XkbUseCoreKbd</symbol>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>timeout</parameter>
+ </term>
+ <listitem>
+ <para>
+ initial delay, ms
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>interval</parameter>
+ </term>
+ <listitem>
+ <para>
+ delay between repeats, ms
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<function>XkbSetAutoRepeatRate</function>
+sends a request to the X server to configure the
+<emphasis>AutoRepeat</emphasis>
+control attributes to the values specified in
+<parameter>timeout</parameter>
+and
+<parameter>interval</parameter>.
+</para>
+
+
+<para>
+<function>XkbSetAutoRepeatRate</function>
+does not wait for a reply; it normally returns
+<symbol>True</symbol>.
+Specifying a zero value for either
+<parameter>timeout</parameter>
+or
+<parameter>interval</parameter>
+causes the server to generate a
+<errorname>BadValue</errorname>
+protocol error. If a compatible version of the Xkb extension is not available
+in the server,
+<function>XkbSetAutoRepeatRate</function>
+returns
+<symbol>False</symbol>.
+</para>
+
+
+</sect2>
+<sect2 id='The_DetectableAutorepeat_Control'>
+<title>The DetectableAutorepeat Control</title>
+
+<para>
+Auto-repeat is the generation of multiple key events by a keyboard when the
+user presses a key and holds it down. Keyboard hardware and device-dependent X
+server software often implement auto-repeat by generating multiple
+<symbol>KeyPress</symbol>
+events with no intervening
+<symbol>KeyRelease</symbol>
+event. The standard behavior of the X server is to generate a
+<symbol>KeyRelease</symbol>
+event for every
+<symbol>KeyPress</symbol>
+event. If the keyboard hardware and device-dependent software of the X server
+implement auto-repeat by generating multiple
+<symbol>KeyPress</symbol>
+events, the device-independent part of the X server by default synthetically
+generates a
+<symbol>KeyRelease</symbol>
+event after each
+<symbol>KeyPress</symbol>
+event. This provides predictable behavior for X clients, but does not allow
+those clients to detect the fact that a key is auto-repeating.
+</para>
+
+
+<para>
+Xkb allows clients to request
+<firstterm>detectable auto-repeat</firstterm>.
+<indexterm significance="preferred" zone="The_DetectableAutorepeat_Control">
+<primary>detectable auto-repeat</primary></indexterm>
+<indexterm significance="preferred" zone="The_DetectableAutorepeat_Control">
+<primary>auto-repeat</primary><secondary>detectable</secondary></indexterm>
+If a client requests and the server supports
+<emphasis>DetectableAutorepeat</emphasis>,
+Xkb generates
+<symbol>KeyRelease</symbol>
+events only when the key is physically released. If
+<emphasis>DetectableAutorepeat</emphasis>
+is not supported or has not been requested, the server synthesizes a
+<symbol>KeyRelease</symbol>
+event for each repeating
+<symbol>KeyPress</symbol>
+event it generates.
+</para>
+
+
+<para>
+<emphasis>DetectableAutorepeat</emphasis>,
+unlike the other controls in this chapter, is not contained in the
+<structname>XkbControlsRec</structname>
+structure, nor can it be enabled or disabled via the
+<emphasis>EnabledControls</emphasis>
+control. Instead, query and set
+<emphasis>DetectableAutorepeat</emphasis>
+using
+<function>XkbGetDetectableAutorepeat</function>
+and
+<function>XkbSetDetectableAutorepeat</function>.
+</para>
+
+
+<para>
+<emphasis>DetectableAutorepeat</emphasis>
+is a condition that applies to all keyboard devices for a client’s
+connection to a given X server; it cannot be selectively set for some devices
+and not for others. For this reason, none of the Xkb library functions
+involving
+<emphasis>DetectableAutorepeat</emphasis>
+involve a device specifier.
+</para>
+
+
+<para>
+To determine whether or not the server supports
+<emphasis>DetectableAutorepeat</emphasis>,
+use
+<function>XkbGetDetectableAutorepeat</function>.
+</para>
+
+<indexterm significance="preferred" zone="XkbGetDetectableAutorepeat"><primary><function>XkbGetDetectableAutorepeat</function></primary></indexterm>
+<funcsynopsis id="XkbGetDetectableAutorepeat">
+ <funcprototype>
+ <funcdef>Bool <function>XkbGetDetectableAutorepeat</function></funcdef>
+<!-- (
+<parameter>display, supported_rtrn</parameter>
+) -->
+
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>Bool *<parameter>supported_rtrn</parameter></paramdef>
+ </funcprototype>
+</funcsynopsis>
+<variablelist>
+ <varlistentry>
+ <term>
+ <parameter>display</parameter>
+ </term>
+ <listitem>
+ <para>
+ connection to X server
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>supported_rtrn</parameter>
+ </term>
+ <listitem>
+ <para>
+ backfilled <symbol>True</symbol> if
+<emphasis>DetectableAutorepeat</emphasis>
+ supported
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<function>XkbGetDetectableAutorepeat</function>
+queries the server for the current state of
+<emphasis>DetectableAutorepeat</emphasis>
+and waits for a reply. If
+<parameter>supported_rtrn</parameter>
+is not
+<symbol>NULL</symbol>,
+it backfills supported_rtrn with
+<symbol>True</symbol>
+if the server supports
+<emphasis>DetectableAutorepeat</emphasis>,
+and
+<symbol>False</symbol>
+otherwise.
+<function>XkbGetDetectableAutorepeat</function>
+returns the current state of
+<emphasis>DetectableAutorepeat</emphasis>
+for the requesting client:
+<symbol>True</symbol>
+if
+<emphasis>DetectableAutorepeat</emphasis>
+is set, and
+<symbol>False</symbol>
+otherwise.
+</para>
+
+
+<para>
+To set
+<emphasis>DetectableAutorepeat</emphasis>,
+use
+<function>XkbSetDetectableAutorepeat</function>.
+This request affects all keyboard activity for the requesting client only;
+other clients still see the expected nondetectable auto-repeat behavior, unless
+they have requested otherwise.
+</para>
+
+
+<indexterm significance="preferred" zone="XkbSetDetectableAutorepeat"><primary><function>XkbSetDetectableAutorepeat</function></primary></indexterm>
+<funcsynopsis id="XkbSetDetectableAutorepeat">
+ <funcprototype>
+ <funcdef>Bool <function>XkbSetDetectableAutorepeat</function></funcdef>
+<!-- (
+<parameter>display, detectable, supported_rtrn</parameter>
+) -->
+
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>Bool <parameter>detectable</parameter></paramdef>
+ <paramdef>Bool *<parameter>supported_rtrn</parameter></paramdef>
+ </funcprototype>
+</funcsynopsis>
+<variablelist>
+ <varlistentry>
+ <term>
+ <parameter>display</parameter>
+ </term>
+ <listitem>
+ <para>
+ connection to X server
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>detectable</parameter>
+ </term>
+ <listitem>
+ <para>
+ <symbol>True</symbol> ⇒ set
+<emphasis>DetectableAutorepeat</emphasis>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>supported_rtrn</parameter>
+ </term>
+ <listitem>
+ <para>
+ backfilled <symbol>True</symbol> if
+<emphasis>DetectableAutorepeat</emphasis>
+ supported
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<function>XkbSetDetectableAutorepeat</function>
+sends a request to the server to set
+<emphasis>DetectableAutorepeat</emphasis>
+on for the current client if
+<parameter>detectable</parameter>
+is
+<symbol>True</symbol>,
+and off it
+<parameter>detectable</parameter>
+is
+<symbol>False</symbol>;
+it then waits for a reply. If
+<parameter>supported_rtrn</parameter>
+is not
+<symbol>NULL</symbol>,
+<function>XkbSetDetectableAutorepeat</function>
+backfills
+<parameter>supported_rtrn</parameter>
+with
+<symbol>True</symbol>
+if the server supports
+<emphasis>DetectableAutorepeat</emphasis>,
+and
+<symbol>False</symbol>
+if it does not.
+<function>XkbSetDetectableAutorepeat</function>
+returns the current state of
+<emphasis>DetectableAutorepeat</emphasis>
+for the requesting client:
+<symbol>True</symbol>
+if
+<emphasis>DetectableAutorepeat</emphasis>
+is set, and
+<symbol>False</symbol>
+otherwise.
+</para>
+
+
+</sect2>
+</sect1>
+<sect1 id='Controls_for_Keyboard_Overlays_Overlay1_and_Overlay2_Controls'>
+<title>Controls for Keyboard Overlays (Overlay1 and Overlay2 Controls)</title>
+
+<para>
+A keyboard overlay allows some subset of the keyboard to report alternate
+keycodes when the overlay is enabled. For example, a keyboard overlay can be
+used to simulate a numeric or editing keypad on a keyboard that does not
+actually have one by reusing some portion of the keyboard as an overlay. This
+technique is very common on portable computers and embedded systems with small
+keyboards.
+</para>
+
+
+<para>
+Xkb includes direct support for two keyboard overlays, using the
+<emphasis>Overlay1</emphasis>
+and
+<emphasis>Overlay2</emphasis>
+controls. When
+<emphasis>Overlay1</emphasis>
+is enabled, all of the keys that are members of the first keyboard overlay
+generate an alternate keycode. When
+<emphasis>Overlay2</emphasis>
+is enabled, all of the keys that are members of the second keyboard overlay
+generate an alternate keycode. The two overlays are mutually exclusive; any
+particular key may be in at most one overlay.
+<emphasis>Overlay1</emphasis>
+and
+<emphasis>Overlay2</emphasis>
+are boolean controls. As such, you may enable and disable them using either
+the
+<emphasis>EnabledControls</emphasis>
+control or the
+<emphasis>AutoReset</emphasis>
+control discussed in <link linkend="The_EnabledControls_Control">section 10.1.1</link>.
+</para>
+
+
+<para>
+To specify the overlay to which a key belongs and the alternate keycode it
+should generate when that overlay is enabled, assign it either the
+<symbol>XkbKB_Overlay1</symbol>
+or
+<symbol>XkbKB_Overlay2</symbol>
+key behaviors, as described in <link linkend="Key_Behavior">section 16.2</link>.
+</para>
+
+
+</sect1>
+<sect1 id='Controls_for_Using_the_Mouse_from_the_Keyboard'>
+<title>Controls for Using the Mouse from the Keyboard</title>
+
+<para>
+Using Xkb, it is possible to configure the keyboard to allow simulation of the
+X pointer device. This simulation includes both movement of the pointer itself
+and press and release events associated with the buttons on the pointer. Two
+controls affect this behavior: the
+<emphasis>MouseKeys</emphasis>
+control determines whether or not simulation of the pointer device is active,
+as well as configuring the default button; the
+<emphasis>MouseKeysAccel</emphasis>
+control determines the movement characteristics of the pointer when simulated
+via the keyboard. Both of them are boolean controls; as such, you may enable
+and disable them using either the
+<emphasis>EnabledControls</emphasis>
+control or the
+<emphasis>AutoReset</emphasis>
+control discussed in <link linkend="The_EnabledControls_Control">section 10.1.1</link>. The individual keys that simulate
+different aspects of the pointer device are determined by the keyboard mapping,
+discussed in <xref linkend="Xkb_Server_Keyboard_Mapping" />.
+</para>
+
+
+<sect2 id='The_MouseKeys_Control'>
+<title>The MouseKeys Control</title>
+
+<para>
+The
+<emphasis>MouseKeys</emphasis>
+control allows a user to control all the mouse functions from the keyboard.
+When
+<emphasis>MouseKeys</emphasis>
+are enabled, all keys with
+<emphasis>MouseKeys</emphasis>
+actions bound to them generate core pointer events instead of normal
+<symbol>KeyPress</symbol>
+and
+<symbol>KeyRelease</symbol>
+events.
+</para>
+
+
+<para>
+The
+<emphasis>MouseKeys</emphasis>
+control has a single attribute,
+<structfield>mk_dflt_btn</structfield>
+that specifies the core button number to be used by mouse keys actions that do
+not explicitly specify a button. There is no convenience function for getting
+or setting the attribute; instead use
+<function>XkbGetControls</function>
+and
+<function>XkbSetControls</function>
+(see <link linkend="Querying_Controls">section 10.9</link> and <link linkend="Changing_Controls">section 10.10</link>).
+</para>
+
+<note><para>
+<emphasis>MouseKeys</emphasis>
+can also be turned on and off by pressing the key combination necessary to
+produce an
+<keysym>XK_Pointer_EnableKeys</keysym>
+keysym. The de facto default standard for this is
+<keycombo><keycap>Shift</keycap><keycap>Alt</keycap><keycap>NumLock</keycap></keycombo>,
+but this may vary depending on the keymap.</para></note>
+
+</sect2>
+<sect2 id='The_MouseKeysAccel_Control'>
+<title>The MouseKeysAccel Control</title>
+
+<para>
+When the
+<emphasis>MouseKeysAccel</emphasis>
+control is enabled, the effect of a key-activated pointer motion action
+changes as a key is held down. If the control is disabled, pressing a
+mouse-pointer key yields one mouse event. When
+<emphasis>MouseKeysAccel</emphasis>
+is enabled, mouse movement is defined by an initial distance specified in the
+<symbol>XkbSA_MovePtr</symbol>
+action and the following fields in the
+<structname>XkbControlsRec</structname>
+structure (see <link linkend="The_XkbControlsRec_Structure">section 10.8</link>).
+</para>
+
+<table id='table10.2' frame='topbot'>
+<title>MouseKeysAccel Fields</title>
+<?dbfo keep-together="always" ?>
+<tgroup cols='2' align='left' colsep='0' rowsep='0'>
+<colspec colname='c1' colwidth='1.0*'/>
+<colspec colname='c2' colwidth='2.0*'/>
+<thead>
+<row rowsep='1'>
+ <entry>Field</entry>
+ <entry>Function</entry>
+</row>
+</thead>
+<tbody>
+<row>
+ <entry>mk_delay</entry>
+ <entry>Time (ms) between the initial key press and the first repeated
+motion event</entry>
+</row>
+<row>
+ <entry>mk_interval</entry>
+ <entry>Time (ms) between repeated motion events</entry>
+</row>
+<row>
+ <entry>mk_time_to_max</entry>
+ <entry>Number of events (count) before the pointer reaches maximum
+speed</entry>
+</row>
+<row>
+ <entry>mk_max_speed</entry>
+ <entry>The maximum speed (in pixels per event) the pointer reaches</entry>
+</row>
+<row>
+ <entry>mk_curve</entry>
+ <entry>The ramp used to reach maximum pointer speed</entry>
+ </row>
+</tbody>
+</tgroup>
+</table>
+
+<para>
+There are no convenience functions to query or change the attributes of the
+<emphasis>MouseKeysAccel</emphasis>
+control; instead use
+<function>XkbGetControls</function>
+and
+<function>XkbSetControls</function>
+(see <link linkend="Querying_Controls">section 10.9</link> and <link linkend="Changing_Controls">section 10.10</link>).
+</para>
+
+
+<para>
+The effects of the attributes of the
+<emphasis>MouseKeysAccel</emphasis>
+control depend on whether the
+<symbol>XkbSA_MovePtr</symbol>
+action (see <link linkend="Key_Actions">section 16.1</link>) specifies relative or absolute pointer motion.
+</para>
+
+<sect3 id='Absolute_Pointer_Motion'>
+<title>Absolute Pointer Motion</title>
+
+<para>
+If an
+<symbol>XkbSA_MovePtr</symbol>
+action specifies an absolute position for one of the coordinates but still
+allows acceleration, all repeated events contain any absolute coordinates
+specified in the action. For example, if the
+<symbol>XkbSA_MovePtr</symbol>
+action specifies an absolute position for the X direction, but a relative
+motion for the Y direction, the pointer accelerates in the Y direction, but
+stays at the same X position.
+</para>
+
+
+</sect3>
+<sect3 id='Relative_Pointer_Motion'>
+<title>Relative Pointer Motion</title>
+
+<para>
+If the
+<symbol>XkbSA_MovePtr</symbol>
+action specifies relative motion, the initial event always moves the cursor
+the distance specified in the action. After
+<structfield>mk_delay</structfield>
+milliseconds, a second motion event is generated, and another occurs every
+<structfield>mk_interval</structfield>
+milliseconds until the user releases the key.
+</para>
+
+
+<para>
+Between the time of the second motion event and
+<structfield>mk_time_to_max</structfield>
+intervals, the change in pointer distance per interval increases with each
+interval. After
+<structfield>mk_time_to_max</structfield>
+intervals have elapsed, the change in pointer distance per interval remains
+the same and is calculated by multiplying the original distance specified in
+the action by
+<structfield>mk_max_speed</structfield>.
+</para>
+
+
+<para>
+For example, if the
+<symbol>XkbSA_MovePtr</symbol>
+action specifies a relative motion in the X direction of 5,
+<structfield>mk_delay</structfield>
+=160,
+<structfield>mk_interval</structfield>
+=40,
+<structfield>mk_time_to_max</structfield>
+=30, and
+<structfield>mk_max_speed</structfield>
+=30, the following happens when the user presses the key:
+</para>
+
+<itemizedlist>
+<listitem>
+ <para>
+The pointer immediately moves 5 pixels in the X direction when the key is
+pressed.
+ </para>
+</listitem>
+<listitem>
+ <para>
+After 160 milliseconds
+(<structfield>mk_delay</structfield>),
+and every 40 milliseconds thereafter
+(<structfield>mk_interval</structfield>),
+the pointer moves in the X direction.
+ </para>
+</listitem>
+<listitem>
+ <para>
+The distance in the X direction increases with each interval until 30 intervals
+(
+<structfield>mk_time_to_max</structfield>)
+have elapsed.
+ </para>
+</listitem>
+<listitem>
+ <para>
+After 30 intervals, the pointer stops accelerating, and moves 150 pixels
+(
+<structfield>mk_max_speed</structfield>
+* the original distance) every interval thereafter, until the key is released.
+ </para>
+</listitem>
+</itemizedlist>
+
+<para>
+The increase in pointer difference for each interval is a function of
+<structfield>mk_curve</structfield>.
+Events after the first but before maximum acceleration has been achieved are
+accelerated according to the formula:
+</para>
+
+<mediaobject>
+<imageobject> <imagedata format="SVG" fileref="XKBlib-3.svg"/>
+</imageobject>
+</mediaobject>
+
+
+<para>
+Where
+<emphasis>action_delta</emphasis>
+is the relative motion specified by the
+<symbol>XkbSA_MovePtr</symbol>
+action,
+<structfield>mk_max_speed</structfield>
+and
+<structfield>mk_time_to_max</structfield>
+are parameters to the
+<emphasis>MouseKeysAccel</emphasis>
+control, and the curveFactor is computed using the
+<emphasis>MouseKeysAccel</emphasis>
+<structfield>mk_curve</structfield>
+parameter as follows:
+</para>
+
+<mediaobject>
+<imageobject> <imagedata format="SVG" fileref="XKBlib-4.svg"/>
+</imageobject>
+</mediaobject>
+
+
+<para>
+With the result that a
+<structfield>mk_curve</structfield>
+of zero causes the distance moved to increase linearly from
+<emphasis>action_delta</emphasis>
+to <mediaobject>
+<imageobject> <imagedata format="SVG" fileref="XKBlib-5.svg"/>
+</imageobject>
+</mediaobject>.
+A negative
+<structfield>mk_curve</structfield>
+causes an initial sharp increase in acceleration that tapers off, and a
+positive curve yields a slower initial increase in acceleration followed by a
+sharp increase as the number of pointer events generated by the action
+approaches
+<structfield>mk_time_to_max</structfield>.
+The legal values for
+<structfield>mk_curve</structfield>
+are between −1000 and 1000.
+</para>
+
+
+<para>
+A distance vs. time graph of the pointer motion is shown in
+<link linkend="figure10.1">Figure 10.1</link>.
+</para>
+
+<figure id='figure10.1'>
+ <title>MouseKeys Acceleration</title>
+ <mediaobject>
+ <imageobject> <imagedata format="SVG" fileref="XKBlib-6.svg"/>
+ </imageobject>
+ </mediaobject>
+</figure>
+
+<!--
+<H5 CLASS="Figure">
+MouseKeys Acceleration</H5>
+-->
+</sect3>
+</sect2>
+</sect1>
+<sect1 id='Controls_for_Better_Keyboard_Access_by_Physically_ImpairedPersons'>
+<title>Controls for Better Keyboard Access by Physically Impaired
+Persons</title>
+
+<para>
+The Xkb extension includes several controls specifically aimed at making
+keyboard use more effective for physically impaired people. All of these
+controls are boolean controls and may be individually enabled and disabled, as
+well as configured to tune their specific behavior. The behavior of these
+controls is based on the AccessDOS package
+<footnote><para>
+AccessDOS provides access to the DOS operating system for people with physical
+impairments and was developed by the Trace R&D Center at the University of
+Wisconsin. For more information on AccessDOS, contact the Trace R&D Center,
+Waisman Center and Department of Industrial Engineering, University of
+Wisconsin-Madison WI 53705-2280. Phone: 608-262-6966. e-mail: info@trace.wisc.edu.
+</para></footnote>.
+</para>
+
+<sect2 id='The_AccessXKeys_Control'>
+<title>The AccessXKeys Control</title>
+
+<para>
+Enabling or disabling the keyboard controls through a graphical user interface
+may be impossible for people who need to use the controls. For example, a user
+who needs
+<emphasis>SlowKeys</emphasis>
+(see <link linkend="The_SlowKeys_Control">section 10.6.6</link>) may not even be able to start the graphical application,
+let alone use it, if
+<emphasis>SlowKeys</emphasis>
+is not enabled. To allow easier access to some of the controls, the
+<emphasis>AccessXKeys</emphasis>
+control provides a set of special key sequences similar to those available in
+AccessDOS.
+</para>
+
+
+<para>
+When the
+<emphasis>AccessXKeys</emphasis>
+control is enabled, the user can turn controls on or off from the keyboard by
+entering the following standard key sequences:
+</para>
+
+<itemizedlist>
+<listitem>
+ <para>
+Holding down a <keycap>Shift</keycap> key by itself for eight seconds
+toggles the
+<emphasis>SlowKeys</emphasis>
+control.
+ </para>
+</listitem>
+<listitem>
+ <para>
+Pressing and releasing the left or right
+<keycap>Shift</keycap>
+key five times in a row, without any intervening key events and with less than
+30 seconds delay between consecutive presses, toggles the state of the
+<emphasis>StickyKeys</emphasis>
+control.
+ </para>
+</listitem>
+<listitem>
+ <para>
+Simultaneously operating two or more modifier keys deactivates the
+<emphasis>StickyKeys</emphasis>
+control.
+ </para>
+</listitem>
+</itemizedlist>
+
+<para>
+When the
+<emphasis>AccessXKeys</emphasis>
+control is disabled, Xkb does not look for the above special key sequences.
+</para>
+
+
+<para>
+Some of these key sequences optionally generate audible feedback of the change
+in state, as described in <link linkend="The_AccessXFeedback_Control">section 10.6.3</link>, or
+<symbol>XkbControlsNotify</symbol>
+events, described in <link linkend="Tracking_Changes_to_Keyboard_Controls">section 10.11</link>.
+</para>
+
+</sect2>
+<sect2 id='The_AccessXTimeout_Control'>
+<title>The AccessXTimeout Control</title>
+
+<para>
+In environments where computers are shared, features such as
+<emphasis>SlowKeys</emphasis>
+present a problem: if
+<emphasis>SlowKeys</emphasis>
+is on, the keyboard can appear to be unresponsive because keys are not
+accepted until they are held for a certain period of time. To help solve this
+problem, Xkb provides an
+<emphasis>AccessXTimeout</emphasis>
+control to automatically change the enabled/disabled state of any boolean
+controls and to change the value of the
+<emphasis>AccessXKeys</emphasis>
+and
+<emphasis>AccessXFeedback</emphasis>
+control attributes if the keyboard is idle for a specified period of time.
+</para>
+
+
+<para>
+When a timeout as specified by
+<emphasis>AccessXTimeout</emphasis>
+occurs and a control is consequently modified, Xkb generates an
+<symbol>XkbControlsNotify</symbol>
+event. For more information on
+<symbol>XkbControlsNotify</symbol>
+events, refer to <link linkend="Tracking_Changes_to_Keyboard_Controls">section 10.11</link>.
+</para>
+
+
+<para>
+Use
+<function>XkbGetAccessXTimeout</function>
+to query the current
+<emphasis>AccessXTimeout</emphasis>
+options for a keyboard device.
+</para>
+
+<indexterm significance="preferred" zone="XkbGetAccessXTimeout"><primary><function>XkbGetAccessXTimeout</function></primary></indexterm>
+<funcsynopsis id="XkbGetAccessXTimeout">
+ <funcprototype>
+ <funcdef>Bool <function>XkbGetAccessXTimeout</function></funcdef>
+<!-- (
+<parameter>display</parameter>,
+<parameter>device_spec</parameter>,
+<parameter>timeout_rtrn</parameter>,
+<parameter>ctrls_mask_rtrn</parameter>,
+<parameter>ctrls_values_rtrn</parameter>,
+<parameter>options_mask_rtrn, options_values_rtrn</parameter>
+) -->
+
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>unsigned int <parameter>device_spec</parameter></paramdef>
+ <paramdef>unsigned short *<parameter>timeout_rtrn</parameter></paramdef>
+ <paramdef>unsigned int *<parameter>ctrls_mask_rtrn</parameter></paramdef>
+ <paramdef>unsigned int *<parameter>ctrls_values_rtrn</parameter></paramdef>
+ <paramdef>unsigned short *<parameter>opts_mask_rtrn</parameter></paramdef>
+ <paramdef>unsigned short *<parameter>opts_values_rtrn</parameter></paramdef>
+ </funcprototype>
+</funcsynopsis>
+<variablelist>
+ <varlistentry>
+ <term>
+ <parameter>display</parameter>
+ </term>
+ <listitem>
+ <para>
+ connection to X server
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>device_spec</parameter>
+ </term>
+ <listitem>
+ <para>
+ device to query, or <symbol>XkbUseCoreKbd</symbol>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>timeout_rtrn</parameter>
+ </term>
+ <listitem>
+ <para>
+ delay until AccessXTimeout, seconds
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>ctrls_mask_rtrn</parameter>
+ </term>
+ <listitem>
+ <para>
+ backfilled with controls to modify
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>ctrls_values_rtrn</parameter>
+ </term>
+ <listitem>
+ <para>
+ backfilled with on/off status for controls
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>opts_mask_rtrn</parameter>
+ </term>
+ <listitem>
+ <para>
+ backfilled with <structfield>ax_options</structfield> to modify
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>opts_values_rtrn</parameter>
+ </term>
+ <listitem>
+ <para>
+ backfilled with values for <structfield>ax_options</structfield>
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<function>XkbGetAccessXTimeout</function>
+sends a request to the X server to obtain the current values for the
+<emphasis>AccessXTimeout</emphasis>
+attributes, waits for a reply, and backfills the values into the appropriate
+arguments.
+The parameters
+<parameter>opts_mask_rtrn</parameter>
+and
+<parameter>opts_values_rtrn</parameter>
+are backfilled with the options to modify and the values for
+<structfield>ax_options</structfield>,
+which is a field in the
+<structname>XkbControlsRec</structname>
+structure (see <link linkend="The_XkbControlsRec_Structure">section 10.8</link>).
+<function>XkbGetAccessXTimeout</function>
+returns
+<symbol>True</symbol>
+if successful; if a compatible version of the Xkb extension is not available
+in the server,
+<function>XkbGetAccessXTimeout</function>
+returns
+<symbol>False</symbol>.
+</para>
+
+
+<para>
+To configure the
+<emphasis>AccessXTimeout</emphasis>
+options for a keyboard device, use
+<function>XkbSetAccessXTimeout</function>.
+</para>
+
+
+<indexterm significance="preferred" zone="XkbSetAccessXTimeout"><primary><function>XkbSetAccessXTimeout</function></primary></indexterm>
+<funcsynopsis id="XkbSetAccessXTimeout">
+ <funcprototype>
+ <funcdef>Bool <function>XkbSetAccessXTimeout</function></funcdef>
+<!-- (
+<parameter>display</parameter>,
+<parameter>device_spec, timeout, ctrls_mask, ctrls_values, opts_mask,
+opts_values</parameter>
+) -->
+
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>unsigned int <parameter>device_spec</parameter></paramdef>
+ <paramdef>unsigned short <parameter>timeout</parameter></paramdef>
+ <paramdef>unsigned int <parameter>ctrls_mask</parameter></paramdef>
+ <paramdef>unsigned int <parameter>ctrls_values</parameter></paramdef>
+ <paramdef>unsigned short <parameter>opts_mask</parameter></paramdef>
+ <paramdef>unsigned short <parameter>opts_values</parameter></paramdef>
+ </funcprototype>
+</funcsynopsis>
+<variablelist>
+ <varlistentry>
+ <term>
+ <parameter>display</parameter>
+ </term>
+ <listitem>
+ <para>
+ connection to X server
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>device_spec</parameter>
+ </term>
+ <listitem>
+ <para>
+ device to configure, or <symbol>XkbUseCoreKbd</symbol>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>timeout</parameter>
+ </term>
+ <listitem>
+ <para>
+ seconds idle until AccessXTimeout occurs
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>ctrls_mask</parameter>
+ </term>
+ <listitem>
+ <para>
+ boolean controls to modify
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>ctrls_values</parameter>
+ </term>
+ <listitem>
+ <para>
+ new bits for controls selected by <parameter>ctrls_mask</parameter>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>opts_mask</parameter>
+ </term>
+ <listitem>
+ <para>
+ <structfield>ax_options</structfield> to change
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>opts_values</parameter>
+ </term>
+ <listitem>
+ <para>
+ new bits for <structfield>ax_options</structfield> selected by <parameter>opts_mask</parameter>
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<parameter>timeout</parameter>
+specifies the number of seconds the keyboard must be idle before the controls
+are modified.
+<parameter>ctrls_mask</parameter>
+specifies what controls are to be enabled or disabled, and
+<parameter>ctrls_values</parameter>
+specifies whether those controls are to be enabled or disabled. The bit values
+correspond to those for enabling and disabling boolean controls
+(see <link linkend="The_EnabledControls_Control">section 10.1.1</link>). The
+<parameter>opts_mask</parameter>
+field specifies which attributes of the
+<emphasis>AccessXKeys</emphasis>
+and
+<emphasis>AccessXFeedback</emphasis>
+controls are to be changed, and
+<parameter>opts_values</parameter>
+specifies the new values for those options. The bit values correspond to those
+for the
+<structfield>ax_options</structfield>
+field of an
+<structname>XkbDescRec</structname>
+(see <link linkend="The_XkbControlsRec_Structure">section 10.8</link>).
+</para>
+
+
+<para>
+<function>XkbSetAccessXTimeout</function>
+sends a request to configure the
+<emphasis>AccessXTimeout</emphasis>
+control to the server.
+It does not wait for a reply, and normally returns
+<symbol>True</symbol>.
+If a compatible version of the Xkb extension is not available in the server,
+<function>XkbSetAccessXTimeout</function>
+returns
+<symbol>False</symbol>.
+</para>
+
+
+</sect2>
+<sect2 id='The_AccessXFeedback_Control'>
+<title>The AccessXFeedback Control</title>
+
+<para>
+Just as some keyboards can produce keyclicks to indicate when a key is pressed
+or repeating, Xkb can provide feedback for the controls by using special beep
+codes. Use the
+<emphasis>AccessXFeedback</emphasis>
+control to configure the specific types of operations that generate feedback.
+</para>
+
+
+<para>
+There is no convenience function for modifying the
+<emphasis>AccessXFeedback</emphasis>
+control, although the feedback as a whole can be enabled or disabled just as
+other boolean controls are (see <link linkend="Controls_that_Enable_and_Disable_Other_Controls">section 10.1</link>). Individual beep codes are turned
+on or off by modifying the following bits in the
+<structfield>ax_options</structfield>
+field of an
+<structname>XkbControlsRec</structname>
+structure and using
+<function>XkbSetControls</function>
+(see <link linkend="Changing_Controls">section 10.10</link>):
+</para>
+
+<table id='table10.3' frame='topbot'>
+<title>AccessXFeedback Masks</title>
+<?dbfo keep-together="always" ?>
+<tgroup cols='3' align='left' colsep='0' rowsep='0'>
+<colspec colname='c1' colwidth='1.0*'/>
+<colspec colname='c2' colwidth='1.0*'/>
+<colspec colname='c3' colwidth='1.0*'/>
+<thead>
+<row rowsep='1'>
+ <entry>Action</entry>
+ <entry>Beep Code</entry>
+ <entry>ax_options bit</entry>
+ </row>
+</thead>
+<tbody>
+<row>
+ <entry>LED turned on</entry>
+ <entry>High-pitched beep</entry>
+ <entry><symbol>XkbAX_IndicatorFBMask</symbol></entry>
+</row>
+<row>
+ <entry>LED turned off</entry>
+ <entry>Low-pitched beep</entry>
+ <entry><symbol>XkbAX_IndicatorFBMask</symbol></entry>
+</row>
+<row>
+ <entry>More than one LED changed state</entry>
+ <entry>Two high-pitched beeps</entry>
+ <entry><symbol>XkbAX_IndicatorFBMask</symbol></entry>
+</row>
+<row>
+ <entry>Control turned on</entry>
+ <entry>Rising tone</entry>
+ <entry><symbol>XkbAX_FeatureFBMask</symbol></entry>
+</row>
+<row>
+ <entry>Control turned off</entry>
+ <entry>Falling tone</entry>
+ <entry><symbol>XkbAX_FeatureFBMask</symbol></entry>
+</row>
+<row>
+ <entry>More than one control changed state</entry>
+ <entry>Two high-pitched beeps</entry>
+ <entry><symbol>XkbAX_FeatureFBMask</symbol></entry>
+</row>
+<row>
+ <entry>SlowKeys and BounceKeys about to be turned on or off</entry>
+ <entry>Three high-pitched beeps</entry>
+ <entry><symbol>XkbAX_SlowWarnFBMask</symbol></entry>
+</row>
+<row>
+ <entry>SlowKeys key pressed</entry>
+ <entry>Medium-pitched beep</entry>
+ <entry><symbol>XkbAX_SKPressFBMask</symbol></entry>
+</row>
+<row>
+ <entry>SlowKeys key accepted</entry>
+ <entry>Medium-pitched beep</entry>
+ <entry><symbol>XkbAX_SKAcceptFBMask</symbol></entry>
+</row>
+<row>
+ <entry>SlowKeys key rejected</entry>
+ <entry>Low-pitched beep</entry>
+ <entry><symbol>XkbAX_SKRejectFBMask</symbol></entry>
+</row>
+<row>
+ <entry>Accepted SlowKeys key released</entry>
+ <entry>Medium-pitched beep</entry>
+ <entry><symbol>XkbAX_SKReleaseFBMask</symbol></entry>
+</row>
+<row>
+ <entry>BounceKeys key rejected</entry>
+ <entry>Low-pitched beep</entry>
+ <entry><symbol>XkbAX_BKRejectFBMask</symbol></entry>
+</row>
+<row>
+ <entry>StickyKeys key latched</entry>
+ <entry>Low-pitched beep followed by high-pitched beep</entry>
+ <entry><symbol>XkbAX_StickyKeysFBMask</symbol></entry>
+</row>
+<row>
+ <entry>StickyKeys key locked</entry>
+ <entry>High-pitched beep</entry>
+ <entry><symbol>XkbAX_StickyKeysFBMask</symbol></entry>
+</row>
+<row>
+ <entry>StickyKeys key unlocked</entry>
+ <entry>Low-pitched beep</entry>
+ <entry><symbol>XkbAX_StickyKeysFBMask</symbol></entry>
+ </row>
+</tbody>
+</tgroup>
+</table>
+
+<para>
+Implementations that cannot generate continuous tones may generate multiple
+beeps instead of falling and rising tones; for example, they can generate a
+high-pitched beep followed by a low-pitched beep instead of a continuous
+falling tone. Other implementations can only ring the bell with one fixed
+pitch. In these cases, use the
+<symbol>XkbAX_DumbBellFBMask</symbol>
+bit of
+<structfield>ax_options</structfield>
+to indicate that the bell can only ring with a fixed pitch.
+</para>
+
+
+<para>
+When any of the above feedbacks occur, Xkb may generate a
+<symbol>XkbBellNotify</symbol>
+event (see <link linkend="Detecting_Bells">section 9.4</link>).
+</para>
+
+
+</sect2>
+<sect2 id='AccessXNotify_Events'>
+<title>AccessXNotify Events</title>
+
+<indexterm significance="preferred" zone="AccessXNotify_Events">
+<primary>events</primary><secondary><symbol>XkbAccessXNotify</symbol></secondary></indexterm>
+<indexterm significance="preferred" zone="AccessXNotify_Events">
+<primary><structname>XkbAccessXNotifyEvent</structname></primary></indexterm>
+
+<para>
+The server can generate
+<symbol>XkbAccessXNotify</symbol>
+events for some of the global keyboard controls. The structure for the
+<symbol>XkbAccessXNotify</symbol>
+event type is as follows:
+
+<programlisting>
+typedef struct {
+ int type; /* Xkb extension base event code */
+ unsigned long serial; /* X server serial number for event */
+ Bool send_event; /* <symbol>True</symbol> ⇒ synthetically generated */
+ Display * display; /* server connection where event generated */
+ Time time; /* server time when event generated */
+ int xkb_type; /* <symbol>XkbAccessXNotify</symbol> */
+ int device; /* Xkb device ID, will not be <symbol>XkbUseCoreKbd</symbol> */
+ int detail; /* XkbAXN_* */
+ KeyCode keycode; /* key of event */
+ int slowKeysDelay; /* current SlowKeys delay */
+ int debounceDelay; /* current debounce delay */
+} <structname>XkbAccessXNotifyEvent</structname>;
+</programlisting></para>
+
+<para>
+The
+<structfield>detail</structfield>
+field describes what AccessX event just occurred and can be any of the values
+in <link linkend="table10.4">Table 10.4</link>.
+</para>
+
+<table id='table10.4' frame='topbot'>
+<title>AccessXNotify Events</title>
+<?dbfo keep-together="always" ?>
+<tgroup cols='2' align='left' colsep='0' rowsep='0'>
+<colspec colname='c1' colwidth='1.0*'/>
+<colspec colname='c2' colwidth='2.0*'/>
+<thead>
+<row rowsep='1'>
+ <entry>detail</entry>
+ <entry>Reason</entry>
+</row>
+</thead>
+<tbody>
+<row>
+ <entry><symbol>XkbAXN_SKPress</symbol></entry>
+ <entry>A key was pressed when SlowKeys was enabled.</entry>
+</row>
+<row>
+ <entry><symbol>XkbAXN_SKAccept</symbol></entry>
+ <entry>A key was accepted (held longer than the SlowKeys delay).</entry>
+</row>
+<row>
+ <entry><symbol>XkbAXN_SKRelease</symbol></entry>
+ <entry>An accepted SlowKeys key was released.</entry>
+</row>
+<row>
+ <entry><symbol>XkbAXN_SKReject</symbol></entry>
+ <entry>A key was rejected (released before the SlowKeys delay
+expired).</entry>
+</row>
+<row>
+ <entry><symbol>XkbAXN_BKAccept</symbol></entry>
+ <entry>A key was accepted by BounceKeys.</entry>
+</row>
+<row>
+ <entry><symbol>XkbAXN_BKReject</symbol></entry>
+ <entry>A key was rejected (pressed before the BounceKeys delay
+expired).</entry>
+</row>
+<row>
+ <entry><symbol>XkbAXN_AXKWarning</symbol></entry>
+ <entry>AccessXKeys is about to turn on/off StickyKeys or BounceKeys.</entry>
+ </row>
+</tbody>
+</tgroup>
+</table>
+
+<para>
+The
+<structfield>keycode</structfield>
+field reports the keycode of the key for which the event occurred. If the
+action is related to
+<emphasis>SlowKeys</emphasis>,
+the
+<structfield>slowKeysDelay</structfield>
+field contains the current
+<emphasis>SlowKeys</emphasis>
+acceptance delay. If the action is related to
+<emphasis>BounceKeys</emphasis>,
+the
+<structfield>debounceDelay</structfield>
+field contains the current
+<emphasis>BounceKeys</emphasis>
+debounce delay.
+</para>
+
+<sect3 id='Selecting_for_AccessX_Events'>
+<title>Selecting for AccessX Events</title>
+
+<para>
+To receive
+<symbol>XkbAccessXNotify</symbol>
+events under all possible conditions, use
+<function>XkbSelectEvents</function>
+(see <link linkend="Selecting_Xkb_Events">section 4.3</link>) and pass
+<symbol>XkbAccessXNotifyMask</symbol>
+in both
+<parameter>bits_to_change</parameter>
+and
+<parameter>values_for_bits</parameter>.
+</para>
+
+
+<para>
+To receive
+<symbol>XkbStateNotify</symbol>
+events only under certain conditions, use
+<function>XkbSelectEventDetails</function>
+using
+<symbol>XkbAccessXNotify</symbol>
+as the
+<structfield>event_type</structfield>
+and specifying the desired state changes in
+<parameter>bits_to_change</parameter>
+and
+<parameter>values_for_bits</parameter>
+using mask bits from <link linkend="table10.5">Table 10.5</link>.
+</para>
+
+<table id='table10.5' frame='topbot'>
+<title>AccessXNotify Event Details</title>
+<?dbfo keep-together="always" ?>
+<tgroup cols='3' align='left' colsep='0' rowsep='0'>
+<colspec colname='c1' colwidth='1.5*'/>
+<colspec colname='c2' colwidth='1.0*'/>
+<colspec colname='c3' colwidth='2.0*'/>
+<thead>
+<row rowsep='1'>
+ <entry>XkbAccessXNotify Event Details</entry>
+ <entry>Value</entry>
+ <entry>Circumstances</entry>
+ </row>
+</thead>
+<tbody>
+ <row>
+ <entry><symbol>XkbAXN_SKPressMask</symbol></entry>
+ <entry>(1<<0)</entry>
+ <entry>Slow key press notification wanted</entry>
+ </row>
+ <row>
+ <entry><symbol>XkbAXN_SKAcceptMask</symbol></entry>
+ <entry>(1<<1)</entry>
+ <entry>Slow key accept notification wanted</entry>
+ </row>
+ <row>
+ <entry><symbol>XkbAXN_SKRejectMask</symbol></entry>
+ <entry>(1<<2)</entry>
+ <entry>Slow key reject notification wanted</entry>
+ </row>
+ <row>
+ <entry><symbol>XkbAXN_SKReleaseMask</symbol></entry>
+ <entry>(1<<3)</entry>
+ <entry>Slow key release notification wanted</entry>
+ </row>
+ <row>
+ <entry><symbol>XkbAXN_BKAcceptMask</symbol></entry>
+ <entry>(1<<4)</entry>
+ <entry>Bounce key accept notification wanted</entry>
+ </row>
+ <row>
+ <entry><symbol>XkbAXN_BKRejectMask</symbol></entry>
+ <entry>(1<<5)</entry>
+ <entry>Bounce key reject notification wanted</entry>
+ </row>
+ <row>
+ <entry><symbol>XkbAXN_AXKWarningMask</symbol></entry>
+ <entry>(1<<6)</entry>
+ <entry>AccessX warning notification wanted</entry>
+ </row>
+ <row>
+ <entry>XkbAXN_AllEventsMask</entry>
+ <entry>(0x7f)</entry>
+ <entry>All AccessX features notifications wanted</entry>
+ </row>
+</tbody>
+</tgroup>
+</table>
+
+</sect3>
+</sect2>
+<sect2 id='StickyKeys_RepeatKeys_and_MouseKeys_Events'>
+<title>StickyKeys, RepeatKeys, and MouseKeys Events</title>
+
+<para>
+The
+<emphasis>StickyKeys</emphasis>,
+<emphasis>RepeatKeys</emphasis>,
+and
+<emphasis>MouseKeys</emphasis>
+controls do not generate specific events. Instead, the latching, unlatching,
+locking, or unlocking of modifiers using
+<emphasis>StickyKeys</emphasis>
+generates
+<symbol>XkbStateNotify</symbol>
+events as described in <link linkend="Tracking_Keyboard_State">section 5.4</link>. Repeating keys generate normal
+<symbol>KeyPress</symbol>
+and
+<symbol>KeyRelease</symbol>
+events, though the auto-repeat can be detected using
+<emphasis>DetectableAutorepeat</emphasis>
+(see <link linkend="The_DetectableAutorepeat_Control">section 10.3.3</link>). Finally,
+<emphasis>MouseKeys</emphasis>
+generates pointer events identical to those of the core pointer device.
+</para>
+
+
+</sect2>
+<sect2 id='The_SlowKeys_Control'>
+<title>The SlowKeys Control</title>
+
+<para>
+Some users may accidentally bump keys while moving a hand or typing stick
+toward the key they want. Usually, the keys that are accidentally bumped are
+just hit for a very short period of time. The
+<emphasis>SlowKeys</emphasis>
+control helps filter these accidental bumps by telling the server to wait a
+specified period, called the
+<firstterm>SlowKeys acceptance delay</firstterm>,
+before delivering key events. If the key is released before this period
+elapses, no key events are generated. Users can then bump any number of keys on
+their way to the one they want without accidentally getting those characters.
+Once they have reached the key they want, they can then hold the desired key
+long enough for the computer to accept it.
+<emphasis>SlowKeys</emphasis>
+is a boolean control with one configurable attribute.
+</para>
+
+<para>
+When the
+<emphasis>SlowKeys</emphasis>
+control is active, the server reports the initial key press, subsequent
+acceptance or rejection, and release of any key to interested clients by
+sending an appropriate
+<emphasis>AccessXNotify</emphasis>
+event (see <link linkend="AccessXNotify_Events">section 10.6.4</link>).
+</para>
+
+<para>
+To get the
+<emphasis>SlowKeys</emphasis>
+acceptance delay for a keyboard device, use
+<function>XkbGetSlowKeysDelay</function>.
+</para>
+
+<indexterm significance="preferred" zone="XkbGetSlowKeysDelay"><primary><function>XkbGetSlowKeysDelay</function></primary></indexterm>
+<funcsynopsis id="XkbGetSlowKeysDelay">
+ <funcprototype>
+ <funcdef>Bool <function>XkbGetSlowKeysDelay</function></funcdef>
+<!-- (
+<parameter>display</parameter>,
+<parameter>device_spec</parameter>,
+<parameter>delay_rtrn</parameter>
+) -->
+
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>unsigned int <parameter>device_spec</parameter></paramdef>
+ <paramdef>unsigned int *<parameter>delay_rtrn</parameter></paramdef>
+ </funcprototype>
+</funcsynopsis>
+<variablelist>
+ <varlistentry>
+ <term>
+ <parameter>display</parameter>
+ </term>
+ <listitem>
+ <para>
+ connection to X server
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>device_spec</parameter>
+ </term>
+ <listitem>
+ <para>
+ device ID, or <symbol>XkbUseCoreKbd</symbol>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>delay_rtrn</parameter>
+ </term>
+ <listitem>
+ <para>
+ backfilled with <emphasis>SlowKeys</emphasis> delay, ms
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<function>XkbGetSlowKeysDelay</function>
+requests the attributes of the
+<emphasis>SlowKeys</emphasis>
+control from the server, waits for a reply and backfills
+<parameter>delay_rtrn</parameter>
+with the
+<emphasis>SlowKeys</emphasis>
+delay attribute.
+<function>XkbGetSlowKeysDelay</function>
+returns
+<symbol>True</symbol>
+if successful; if a compatible version of the Xkb extension is not available
+in the server,
+<function>XkbGetSlowKeysDelay</function>
+returns
+<symbol>False</symbol>.
+</para>
+
+
+<para>
+To set the
+<emphasis>SlowKeys</emphasis>
+acceptance delay for a keyboard device, use
+<function>XkbSetSlowKeysDelay</function>.
+</para>
+
+
+<indexterm significance="preferred" zone="XkbSetSlowKeysDelay"><primary><function>XkbSetSlowKeysDelay</function></primary></indexterm>
+<funcsynopsis id="XkbSetSlowKeysDelay">
+ <funcprototype>
+ <funcdef>Bool <function>XkbSetSlowKeysDelay</function></funcdef>
+<!-- (
+<parameter>display</parameter>,
+<parameter>device_spec</parameter>,
+<parameter>delay</parameter>
+) -->
+
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>unsigned int <parameter>device_spec</parameter></paramdef>
+ <paramdef>unsigned int <parameter>delay</parameter></paramdef>
+ </funcprototype>
+</funcsynopsis>
+<variablelist>
+ <varlistentry>
+ <term>
+ <parameter>display</parameter>
+ </term>
+ <listitem>
+ <para>
+ connection to X server
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>device_spec</parameter>
+ </term>
+ <listitem>
+ <para>
+ device to configure, or <symbol>XkbUseCoreKbd</symbol>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>delay</parameter>
+ </term>
+ <listitem>
+ <para>
+ <emphasis>SlowKeys</emphasis> delay, ms
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<function>XkbSetSlowKeysDelay</function>
+sends a request to configure the
+<emphasis>SlowKeys</emphasis>
+control to the server.
+It does not wait for a reply, and normally returns
+<symbol>True</symbol>.
+Specifying a value of
+<literal>0</literal>
+for the
+<parameter>delay</parameter>
+parameter causes
+<function>XkbSetSlowKeysDelay</function>
+to generate a
+<errorname>BadValue</errorname>
+protocol error. If a compatible version of the Xkb extension is not available
+in the server
+<function>XkbSetSlowKeysDelay</function>
+returns
+<symbol>False</symbol>.
+</para>
+
+
+</sect2>
+<sect2 id='The_BounceKeys_Control'>
+<title>The BounceKeys Control</title>
+
+<para>
+Some users may accidentally <quote>bounce</quote> on a key when they release it.
+They press it once, then accidentally press it again after they release it. The
+<emphasis>BounceKeys</emphasis>
+control temporarily disables a key after it has been pressed, effectively
+<quote>debouncing</quote> the keyboard. The period of time the key is disabled
+after it is released is known as the
+<firstterm>BounceKeys delay</firstterm>.
+<emphasis>BounceKeys</emphasis>
+is a boolean control.
+</para>
+
+
+<para>
+When the
+<emphasis>BounceKeys</emphasis>
+control is active, the server reports acceptance or rejection of any key to
+interested clients by sending an appropriate
+<emphasis>AccessXNotify</emphasis>
+event (see <link linkend="AccessXNotify_Events">section 10.6.4</link>).
+</para>
+
+
+<para>
+Use
+<function>XkbGetBounceKeysDelay</function>
+to query the current
+<emphasis>BounceKeys</emphasis>
+delay for a keyboard device.
+</para>
+
+<indexterm significance="preferred" zone="XkbGetBounceKeysDelay"><primary><function>XkbGetBounceKeysDelay</function></primary></indexterm>
+<funcsynopsis id="XkbGetBounceKeysDelay">
+ <funcprototype>
+ <funcdef>Bool <function>XkbGetBounceKeysDelay</function></funcdef>
+<!-- (
+<parameter>display</parameter>,
+<parameter>device_spec</parameter>,
+<parameter>delay_rtrn</parameter>
+) -->
+
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>unsigned int <parameter>device_spec</parameter></paramdef>
+ <paramdef>unsigned int *<parameter>delay_rtrn</parameter></paramdef>
+ </funcprototype>
+</funcsynopsis>
+<variablelist>
+ <varlistentry>
+ <term>
+ <parameter>display</parameter>
+ </term>
+ <listitem>
+ <para>
+ connection to X server
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>device_spec</parameter>
+ </term>
+ <listitem>
+ <para>
+ device ID, or <symbol>XkbUseCoreKbd</symbol>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>delay_rtrn</parameter>
+ </term>
+ <listitem>
+ <para>
+ backfilled with bounce keys delay, ms
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<function>XkbGetBounceKeysDelay</function>
+requests the attributes of the
+<emphasis>BounceKeys</emphasis>
+control from the server, waits for a reply, and backfills
+<parameter>delay_rtrn</parameter>
+with the
+<emphasis>BounceKeys</emphasis>
+delay attribute.
+<function>XkbGetBounceKeysDelay</function>
+returns
+<symbol>True</symbol>
+if successful; if a compatible version of the Xkb extension is not available
+in the server
+<function>XkbGetSlowKeysDelay</function>
+returns
+<symbol>False</symbol>.
+</para>
+
+
+<para>
+To set the
+<emphasis>BounceKeys</emphasis>
+delay for a keyboard device, use
+<function>XkbSetBounceKeysDelay</function>.
+</para>
+
+
+<indexterm significance="preferred" zone="XkbSetBounceKeysDelay"><primary><function>XkbSetBounceKeysDelay</function></primary></indexterm>
+<funcsynopsis id="XkbSetBounceKeysDelay">
+ <funcprototype>
+ <funcdef>Bool <function>XkbSetBounceKeysDelay</function></funcdef>
+<!-- (
+<parameter>display</parameter>,
+<parameter>device_spec</parameter>,
+<parameter>delay</parameter>
+) -->
+
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>unsigned int <parameter>device_spec</parameter></paramdef>
+ <paramdef>unsigned int <parameter>delay</parameter></paramdef>
+ </funcprototype>
+</funcsynopsis>
+<variablelist>
+ <varlistentry>
+ <term>
+ <parameter>display</parameter>
+ </term>
+ <listitem>
+ <para>
+ connection to X server
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>device_spec</parameter>
+ </term>
+ <listitem>
+ <para>
+ device to configure, or <symbol>XkbUseCoreKbd</symbol>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>delay</parameter>
+ </term>
+ <listitem>
+ <para>
+ bounce keys delay, ms
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<function>XkbSetBounceKeysDelay</function>
+sends a request to configure the
+<emphasis>BounceKeys</emphasis>
+control to the server.
+It does not wait for a reply and normally returns
+<symbol>True</symbol>.
+Specifying a value of
+<emphasis>zero</emphasis>
+for the
+<parameter>delay</parameter>
+parameter causes
+<function>XkbSetBounceKeysDelay</function>
+to generate a
+<errorname>BadValue</errorname>
+protocol error. If a compatible version of the Xkb extension is not available
+in the server,
+<function>XkbSetBounceKeysDelay</function>
+returns
+<symbol>False</symbol>.
+</para>
+
+</sect2>
+<sect2 id='The_StickyKeys_Control'>
+<title>The StickyKeys Control</title>
+
+<para>
+Some people find it difficult or even impossible to press two keys at once. For
+example, a one-fingered typist or someone using a mouth stick cannot press the
+<keycap>Shift</keycap>
+and
+<keycap>1</keycap>
+keys at the same time. The
+<emphasis>StickyKeys</emphasis>
+control solves this problem by changing the behavior of the modifier keys.
+With
+<emphasis>StickyKeys</emphasis>,
+the user can first press a modifier, release it, then press another key. For
+example, to get an exclamation point on a PC-style keyboard, the user can press
+the
+<keycap>Shift</keycap>
+key, release it, and then press the
+<keycap>1</keycap>
+key.
+</para>
+
+
+<para>
+<emphasis>StickyKeys</emphasis>
+also allows users to lock modifier keys without requiring special locking
+keys. When
+<emphasis>StickyKeys</emphasis>
+is enabled, a modifier is latched when the user presses it just once. The user
+can press a modifier twice in a row to lock it, and then unlock it by pressing
+it one more time.
+</para>
+
+
+<para>
+When a modifier is latched, it becomes unlatched when the user presses a
+nonmodifier key or a pointer button. For instance, to enter the sequence
+<keycombo>
+<keycap>Shift</keycap>
+<keycap>Control</keycap>
+<keycap>Z</keycap>
+</keycombo>
+the user could press and release the
+<keycap>Shift</keycap>
+key to latch it, then press and release the
+<keycap>Control</keycap>
+key to latch it, and finally press and release the
+<keycap>Z</keycap> key. Because the
+<keycap>Control</keycap>
+key is a modifier key, pressing it does not unlatch the
+<keycap>Shift</keycap>
+key. Thus, after the user presses the
+<keycap>Control</keycap>
+key, both the
+<symbol>Shift</symbol>
+and
+<symbol>Control</symbol>
+modifiers are latched. When the user presses the
+<keycap>Z</keycap>
+key, the effect is as though the user had pressed
+<keycombo>
+<keycap>Shift</keycap>
+<keycap>Control</keycap>
+<keycap>Z</keycap>
+</keycombo>.
+In addition, because the
+<keycap>Z</keycap>
+key is not a modifier key, the
+<symbol>Shift</symbol>
+and
+<symbol>Control</symbol>
+modifiers are unlatched.
+</para>
+
+
+<para>
+Locking a modifier key means that the modifier affects any key or pointer
+button the user presses until the user unlocks it or it is unlocked
+programmatically. For example, to enter the sequence ("XKB") on a keyboard
+where ‘(’ is a shifted ‘9’, ‘)’ is a shifted ‘0’, and ‘"’
+is a shifted single quote, the user could press and release the
+<keycap>Shift</keycap>
+key twice to lock the
+<symbol>Shift</symbol>
+modifier. Then, when the user presses the
+<keycap>9</keycap>,
+<keycap>'</keycap>,
+<keycap>x</keycap>,
+<keycap>k</keycap>,
+<keycap>b</keycap>,
+<keycap>'</keycap>,
+and
+<keycap>0</keycap>
+keys in sequence, it generates ("XKB"). To unlock the
+<symbol>Shift</symbol>
+modifier, the user can press and release the
+<keycap>Shift</keycap>
+key.
+</para>
+
+
+<para>
+<emphasis>StickyKeys</emphasis>
+is a boolean control with two separate attributes that may be individually
+configured: one to automatically disable it, and one to control the latching
+behavior of modifier keys.
+</para>
+
+<sect3 id='StickyKeys_Options'>
+<title>StickyKeys Options</title>
+
+<para>
+The
+<emphasis>StickyKeys</emphasis>
+control has two options that can be accessed via the
+<structfield>ax_options</structfield>
+of an
+<structname>XkbControlsRec</structname>
+structure (see <link linkend="The_XkbControlsRec_Structure">section 10.8</link>). The first option,
+<emphasis>TwoKeys</emphasis>,
+specifies whether
+<emphasis>StickyKeys</emphasis>
+should automatically turn off when two keys are pressed at the same time. This
+feature is useful for shared computers so people who do not want them do not
+need to turn
+<emphasis>StickyKeys</emphasis>
+off if a previous user left
+<emphasis>StickyKeys</emphasis>
+on. The second option,
+<emphasis>LatchToLock</emphasis>,
+specifies whether or not
+<emphasis>StickyKeys</emphasis>
+locks a modifier when pressed twice in a row.
+</para>
+
+
+<para>
+Use
+<function>XkbGetStickyKeysOptions</function>
+to query the current
+<emphasis>StickyKeys</emphasis>
+attributes for a keyboard device.
+</para>
+
+<indexterm significance="preferred" zone="XkbGetStickyKeysOptions"><primary><function>XkbGetStickyKeysOptions</function></primary></indexterm>
+<funcsynopsis id="XkbGetStickyKeysOptions">
+ <funcprototype>
+ <funcdef>Bool <function>XkbGetStickyKeysOptions</function></funcdef>
+<!-- (
+<parameter>display</parameter>,
+<parameter>device_spec</parameter>,
+<parameter>options_rtrn</parameter>
+) -->
+
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>unsigned int <parameter>device_spec</parameter></paramdef>
+ <paramdef>unsigned int *<parameter>options_rtrn</parameter></paramdef>
+ </funcprototype>
+</funcsynopsis>
+<variablelist>
+ <varlistentry>
+ <term>
+ <parameter>display</parameter>
+ </term>
+ <listitem>
+ <para>
+ connection to X server
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>device_spec</parameter>
+ </term>
+ <listitem>
+ <para>
+ device ID, or <symbol>XkbUseCoreKbd</symbol>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>options_rtrn</parameter>
+ </term>
+ <listitem>
+ <para>
+ backfilled with StickyKeys option mask
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<function>XkbGetStickyKeysOptions</function>
+requests the attributes of the
+<emphasis>StickyKeys</emphasis>
+control from the server, waits for a reply, and backfills
+<parameter>options_rtrn</parameter>
+with a mask indicating whether the individual
+<emphasis>StickyKeys</emphasis>
+options are on or off. Valid bits in
+<parameter>options_rtrn</parameter>
+are:
+
+ <simplelist type='vert' columns='1'>
+ <member><symbol>XkbAX_TwoKeysMask</symbol></member>
+ <member><symbol>XkbAX_LatchToLockMask</symbol></member>
+ </simplelist>
+</para>
+
+<para>
+<function>XkbGetStickyKeysOptions</function>
+returns
+<symbol>True</symbol>
+if successful; if a compatible version of the Xkb extension is not available
+in the server
+<function>XkbGetStickyKeysOptions</function>
+returns
+<symbol>False</symbol>.
+</para>
+
+
+<para>
+To set the
+<emphasis>StickyKeys</emphasis>
+attributes for a keyboard device, use
+<function>XkbSetStickyKeysOptions</function>.
+</para>
+
+
+<indexterm significance="preferred" zone="XkbSetStickyKeysOptions"><primary><function>XkbSetStickyKeysOptions</function></primary></indexterm>
+<funcsynopsis id="XkbSetStickyKeysOptions">
+ <funcprototype>
+ <funcdef>Bool <function>XkbSetStickyKeysOptions</function></funcdef>
+<!-- (
+<parameter>display</parameter>,
+<parameter>device_spec, mask, values</parameter>
+) -->
+
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>unsigned int <parameter>device_spec</parameter></paramdef>
+ <paramdef>unsigned int <parameter>mask</parameter></paramdef>
+ <paramdef>unsigned int <parameter>values</parameter></paramdef>
+ </funcprototype>
+</funcsynopsis>
+<variablelist>
+ <varlistentry>
+ <term>
+ <parameter>display</parameter>
+ </term>
+ <listitem>
+ <para>
+ connection to X server
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>device_spec</parameter>
+ </term>
+ <listitem>
+ <para>
+ device to configure, or XkbUseCoreKbd
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>mask</parameter>
+ </term>
+ <listitem>
+ <para>
+ selects StickyKeys attributes to modify
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>values</parameter>
+ </term>
+ <listitem>
+ <para>
+ values for selected attributes
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<function>XkbSetStickyKeysOptions</function>
+sends a request to configure the
+<emphasis>StickyKeys</emphasis>
+control to the server.
+It does not wait for a reply and normally returns
+<symbol>True</symbol>.
+The valid bits to use for both the
+<parameter>mask</parameter>
+and
+<parameter>values</parameter>
+parameters are:
+
+ <simplelist type='vert' columns='1'>
+ <member><symbol>XkbAX_TwoKeysMask</symbol></member>
+ <member><symbol>XkbAX_LatchToLockMask</symbol></member>
+ </simplelist>
+</para>
+
+<para>
+If a compatible version of the Xkb extension is not available in the server,
+<function>XkbSetStickyKeysOptions</function>
+returns
+<symbol>False</symbol>.
+</para>
+
+</sect3>
+</sect2>
+</sect1>
+<sect1 id='Controls_for_General_Keyboard_Mapping'>
+<title>Controls for General Keyboard Mapping</title>
+
+<para>
+There are several controls that apply to the keyboard mapping in general. They
+control handling of out-of-range group indices and how modifiers are processed
+and consumed in the server. These are:
+
+ <simplelist type='vert' columns='1'>
+ <member><emphasis>GroupsWrap</emphasis></member>
+ <member><emphasis>IgnoreGroupLock</emphasis></member>
+ <member><emphasis>IgnoreLockMods</emphasis></member>
+ <member><emphasis>InternalMods</emphasis></member>
+ </simplelist>
+</para>
+
+<para>
+<emphasis>IgnoreGroupLock</emphasis>
+is a boolean control; the rest are always active.
+</para>
+
+
+<para>
+Without the modifier processing options provided by Xkb, passive grabs set via
+translations in a client (for example,
+<emphasis>Alt<KeyPress>space</emphasis>)
+do not trigger if any modifiers other than those specified by the translation
+are set. This results in problems in the user interface when either
+<emphasis>NumLock</emphasis>
+or a secondary keyboard group is active. The
+<emphasis>IgnoreLockMods</emphasis>
+and
+<emphasis>IgnoreGroupLock</emphasis>
+controls make it possible to avoid this behavior without exhaustively
+specifying a grab for every possible modifier combination.
+</para>
+
+<sect2 id='The_GroupsWrap_Control'>
+<title>The GroupsWrap Control</title>
+
+<para>
+The
+<emphasis>GroupsWrap</emphasis>
+control determines how illegal groups are handled on a global basis. There are
+a number of valid keyboard sequences that can cause the effective group number
+to go out of range. When this happens, the group must be normalized back to a
+valid number. The
+<emphasis>GroupsWrap</emphasis>
+control specifies how this is done.
+</para>
+
+
+<para>
+When dealing with group numbers, all computations are done using the group
+index, which is the group number minus one. There are three different
+algorithms; the
+<emphasis>GroupsWrap</emphasis>
+control specifies which one is used:
+</para>
+
+<itemizedlist>
+<listitem>
+ <para>XkbRedirectIntoRange</para>
+ <para>
+All invalid group numbers are converted to a valid group number by taking the
+last four bits of the
+<emphasis>GroupsWrap</emphasis>
+control and using them as the group index. If the result is still out of
+range, Group one is used.
+ </para>
+</listitem>
+<listitem>
+ <para>
+XkbClampIntoRange
+ </para>
+ <para>
+All invalid group numbers are converted to the nearest valid group number.
+Group numbers larger than the highest supported group number are mapped to the
+highest supported group; those less than one are mapped to group one.
+ </para>
+</listitem>
+<listitem>
+ <para>XkbWrapIntoRange</para>
+ <para>
+All invalid group numbers are converted to a valid group number using integer
+modulus applied to the group index.
+ </para>
+</listitem>
+</itemizedlist>
+
+<para>
+There are no convenience functions for manipulating the
+<emphasis>GroupsWrap</emphasis>
+control. Manipulate the
+<emphasis>GroupsWrap</emphasis>
+control via the
+<structfield>groups_wrap</structfield>
+field in the
+<structname>XkbControlsRec</structname>
+structure, then use
+<function>XkbSetControls</function>
+and
+<function>XkbGetControls</function>
+(see <link linkend="Querying_Controls">section 10.9</link> and <link linkend="Changing_Controls">section 10.10</link>) to query and change this control.
+</para>
+
+<note><para>See also <link linkend="Per_Key_Group_Information">section 15.3.2</link> or a discussion of the related field,
+<structfield>group_info</structfield>,
+which also normalizes a group under certain circumstances.</para></note>
+
+</sect2>
+<sect2 id='The_IgnoreLockMods_Control'>
+<title>The IgnoreLockMods Control</title>
+
+<para>
+The core protocol does not provide a way to exclude specific modifiers from
+grab calculations, with the result that locking modifiers sometimes have
+unanticipated side effects.
+</para>
+
+
+<para>
+The
+<emphasis>IgnoreLockMods</emphasis>
+control specifies modifiers that should be excluded from grab calculations.
+These modifiers are also not reported in any core events except
+<symbol>KeyPress</symbol>
+and
+<symbol>KeyRelease</symbol>
+events that do not activate a passive grab and that do not occur while a grab
+is active.
+</para>
+
+
+<para>
+Manipulate the
+<emphasis>IgnoreLockMods</emphasis>
+control via the
+<structfield>ignore_lock</structfield>
+field in the
+<structname>XkbControlsRec</structname>
+structure, then use
+<function>XkbSetControls</function>
+and
+<function>XkbGetControls</function>
+(see <link linkend="Querying_Controls">section 10.9</link> and <link linkend="Changing_Controls">section 10.10</link>) to query and change this control. Alternatively,
+use
+<function>XkbSetIgnoreLockMods</function>.
+</para>
+
+
+<para>
+To set the modifiers that, if locked, are not to be reported in matching events
+to passive grabs, use
+<function>XkbSetIgnoreLockMods</function>.
+</para>
+
+<indexterm significance="preferred" zone="XkbSetIgnoreLockMods"><primary><function>XkbSetIgnoreLockMods</function></primary></indexterm>
+<funcsynopsis id="XkbSetIgnoreLockMods">
+ <funcprototype>
+ <funcdef>Bool <function>XkbSetIgnoreLockMods</function></funcdef>
+<!-- (
+<parameter>display, device_spec, affect_real, real_values, affect_virtual,
+virtual_values</parameter>
+) -->
+
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>unsigned int <parameter>device_spec</parameter></paramdef>
+ <paramdef>unsigned int <parameter>affect_real</parameter></paramdef>
+ <paramdef>unsigned int <parameter>real_values</parameter></paramdef>
+ <paramdef>unsigned int <parameter>affect_virtual</parameter></paramdef>
+ <paramdef>unsigned int <parameter>virtual_values</parameter></paramdef>
+ </funcprototype>
+</funcsynopsis>
+<variablelist>
+ <varlistentry>
+ <term>
+ <parameter>display</parameter>
+ </term>
+ <listitem>
+ <para>
+ connection to the X server
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>device_spec</parameter>
+ </term>
+ <listitem>
+ <para>
+ device ID, or <symbol>XkbUseCoreKbd</symbol>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>affect_real</parameter>
+ </term>
+ <listitem>
+ <para>
+ mask of real modifiers affected by this call
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>real_values</parameter>
+ </term>
+ <listitem>
+ <para>
+ values for affected real modifiers (1⇒set, 0⇒unset)
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>affect_virtual</parameter>
+ </term>
+ <listitem>
+ <para>
+ mask of virtual modifiers affected by this call
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>virtual_values</parameter>
+ </term>
+ <listitem>
+ <para>
+ values for affected virtual modifiers (1⇒set, 0⇒unset)
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<function>XkbSetIgnoreLockMods</function>
+sends a request to the server to change the server’s
+<emphasis>IgnoreLockMods</emphasis>
+control.
+<parameter>affect_real</parameter>
+and
+<parameter>real_values</parameter>
+are masks of real modifier bits indicating which real modifiers are to be
+added and removed from the server’s
+<emphasis>IgnoreLockMods</emphasis>
+control. Modifiers selected by both
+<parameter>affect_real</parameter>
+and
+<parameter>real_values</parameter>
+are added to the server’s
+<emphasis>IgnoreLockMods</emphasis>
+control; those selected by
+<parameter>affect_real</parameter>
+but not by
+<parameter>real_values</parameter>
+are removed from the server’s
+<emphasis>IgnoreLockMods</emphasis>
+control. Valid values for
+<parameter>affect_real</parameter>
+and
+<parameter>real_values</parameter>
+consist of any combination of the eight core modifier bits:
+<symbol>ShiftMask</symbol>,
+<symbol>LockMask</symbol>,
+<symbol>ControlMask</symbol>,
+<symbol>Mod1Mask</symbol>
+–
+<symbol>Mod5Mask</symbol>.
+<parameter>affect_virtual</parameter>
+and
+<parameter>virtual_values</parameter>
+are masks of virtual modifier bits indicating which virtual modifiers are to
+be added and removed from the server’s
+<emphasis>IgnoreLockMods</emphasis>
+control. Modifiers selected by both
+<parameter>affect_virtual</parameter>
+and
+<parameter>virtual_values</parameter>
+are added to the server’s
+<emphasis>IgnoreLockMods</emphasis>
+control; those selected by
+<parameter>affect_virtual</parameter>
+but not by
+<parameter>virtual_values</parameter>
+are removed from the server’s
+<emphasis>IgnoreLockMods</emphasis>
+control.
+See <link linkend="Virtual_Modifier_Names_and_Masks">section 7.1</link> for a discussion of virtual modifier masks to use in
+<parameter>affect_virtual</parameter>
+and
+<parameter>virtual_values</parameter>.
+<function>XkbSetIgnoreLockMods</function>
+does not wait for a reply from the server. It returns
+<symbol>True</symbol>
+if the request was sent, and
+<symbol>False</symbol>
+otherwise.
+</para>
+
+</sect2>
+<sect2 id='The_IgnoreGroupLock_Control'>
+<title>The IgnoreGroupLock Control</title>
+
+<para>
+The
+<emphasis>IgnoreGroupLock</emphasis>
+control is a boolean control with no attributes. If enabled, it specifies that
+the locked state of the keyboard group should not be considered when activating
+passive grabs.
+</para>
+
+<para>
+Because
+<emphasis>IgnoreGroupLock</emphasis>
+is a boolean control with no attributes, use the general boolean controls
+functions (see <link linkend="Controls_that_Enable_and_Disable_Other_Controls">section 10.1</link>) to change its state.
+</para>
+
+
+</sect2>
+<sect2 id='The_InternalMods_Control'>
+<title>The InternalMods Control</title>
+
+<para>
+The core protocol does not provide any means to prevent a modifier from being
+reported in events sent to clients; Xkb, however makes this possible via the
+<emphasis>InternalMods</emphasis>
+control. It specifies modifiers that should be consumed by the server and not
+reported to clients. When a key is pressed and a modifier that has its bit set
+in the
+<emphasis>InternalMods</emphasis>
+control is reported to the server, the server uses the modifier when
+determining the actions to apply for the key. The server then clears the bit,
+so it is not actually reported to the client. In addition, modifiers specified
+in the
+<emphasis>InternalMods</emphasis>
+control are not used to determine grabs and are not used to calculate core
+protocol compatibility state.
+</para>
+
+
+<para>
+Manipulate the
+<emphasis>InternalMods</emphasis>
+control via the
+<structfield>internal</structfield>
+field in the
+<structname>XkbControlsRec</structname>
+structure, using
+<function>XkbSetControls</function>
+and
+<function>XkbGetControls</function>
+(see <link linkend="Querying_Controls">section 10.9</link>
+and <link linkend="Changing_Controls">section 10.10</link>). Alternatively, use
+<function>XkbSetServerInternalMods</function>.
+</para>
+
+
+<para>
+To set the modifiers that are consumed by the server before events are
+delivered to the client, use
+<function>XkbSetServerInternalMods</function>.
+</para>
+
+<indexterm significance="preferred" zone="XkbSetServerInternalMods"><primary><function>XkbSetServerInternalMods</function></primary></indexterm>
+<funcsynopsis id="XkbSetServerInternalMods">
+ <funcprototype>
+ <funcdef>Bool <function>XkbSetServerInternalMods</function></funcdef>
+<!-- (
+<parameter>display, device_spec, affect_real, real_values, affect_virtual,
+virtual_values</parameter>
+) -->
+
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>unsigned int <parameter>device_spec</parameter></paramdef>
+ <paramdef>unsigned int <parameter>affect_real</parameter></paramdef>
+ <paramdef>unsigned int <parameter>real_values</parameter></paramdef>
+ <paramdef>unsigned int <parameter>affect_virtual</parameter></paramdef>
+ <paramdef>unsigned int <parameter>virtual_values</parameter></paramdef>
+ </funcprototype>
+</funcsynopsis>
+<variablelist>
+ <varlistentry>
+ <term>
+ <parameter>display</parameter>
+ </term>
+ <listitem>
+ <para>
+ connection to the X server
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>device_spec</parameter>
+ </term>
+ <listitem>
+ <para>
+ ‘device ID, or <symbol>XkbUseCoreKbd</symbol>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>affect_real</parameter>
+ </term>
+ <listitem>
+ <para>
+ mask of real modifiers affected by this call
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>real_values</parameter>
+ </term>
+ <listitem>
+ <para>
+ values for affected real modifiers (1⇒set, 0⇒unset)
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>affect_virtual</parameter>
+ </term>
+ <listitem>
+ <para>
+ mask of virtual modifiers affected by this call
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>virtual_values</parameter>
+ </term>
+ <listitem>
+ <para>
+ values for affected virtual modifiers (1⇒set, 0⇒unset)
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<function>XkbSetServerInternalMods</function>
+sends a request to the server to change the internal modifiers consumed by the
+server.
+<parameter>affect_real</parameter>
+and
+<parameter>real_values</parameter>
+are masks of real modifier bits indicating which real modifiers are to be
+added and removed from the server’s internal modifiers control. Modifiers
+selected by both
+<parameter>affect_real</parameter>
+and
+<parameter>real_values</parameter>
+are added to the server’s internal modifiers control; those selected by
+<parameter>affect_real</parameter>
+but not by
+<parameter>real_values</parameter>
+are removed from the server’s internal modifiers mask. Valid values for
+<parameter>affect_real</parameter>
+and
+<parameter>real_values</parameter>
+consist of any combination of the eight core modifier bits:
+<symbol>ShiftMask</symbol>,
+<symbol>LockMask</symbol>,
+<symbol>ControlMask</symbol>,
+<symbol>Mod1Mask</symbol>
+–
+<symbol>Mod5Mask</symbol>.
+<parameter>affect_virtual</parameter>
+and
+<parameter>virtual_values</parameter>
+are masks of virtual modifier bits indicating which virtual modifiers are to
+be added and removed from the server’s internal modifiers control. Modifiers
+selected by both
+<parameter>affect_virtual</parameter>
+and
+<parameter>virtual_values</parameter>
+are added to the server’s internal modifiers control; those selected by
+<parameter>affect_virtual</parameter>
+but not by
+<parameter>virtual_values</parameter>
+are removed from the server’s internal modifiers control.
+See <link linkend="Virtual_Modifier_Names_and_Masks">section 7.1</link> for a discussion of virtual modifier masks to use in
+<parameter>affect_virtual</parameter>
+and
+<parameter>virtual_values</parameter>.
+<function>XkbSetServerInternalMods</function>
+does not wait for a reply from the server. It returns
+<symbol>True</symbol>
+if the request was sent and
+<symbol>False</symbol>
+otherwise.
+</para>
+
+
+</sect2>
+</sect1>
+<sect1 id='The_XkbControlsRec_Structure'>
+<title>The XkbControlsRec Structure</title>
+
+<indexterm significance="preferred" zone="The_XkbControlsRec_Structure">
+<primary><structname>XkbControlsRec</structname></primary></indexterm>
+
+<para>
+Many of the individual controls described in sections 10.1 through 10.7 may be
+manipulated via convenience functions discussed in those sections. Some of
+them, however, have no convenience functions. The
+<structname>XkbControlsRec</structname>
+structure allows the manipulation of one or more of the controls in a single
+operation and to track changes to any of them in conjunction with the
+<function>XkbGetControls</function>
+and
+<function>XkbSetControls</function>
+functions. This is the only way to manipulate those controls that have no
+convenience functions.
+</para>
+
+
+<para>
+The
+<structname>XkbControlsRec</structname>
+structure is defined as follows:
+
+<programlisting>
+#define XkbMaxLegalKeyCode 255
+#define XkbPerKeyBitArraySize ((XkbMaxLegalKeyCode+1)/8)
+
+typedef struct {
+ unsigned char mk_dflt_btn; /* default button for
+ keyboard driven mouse */
+ unsigned char num_groups; /* number of keyboard groups */
+ unsigned char groups_wrap; /* how to wrap out-of-bounds groups */
+ XkbModsRec internal; /* defines server internal modifiers */
+ XkbModsRec ignore_lock; /* modifiers to ignore when
+ checking for grab */
+ unsigned int enabled_ctrls; /* 1 bit ⇒ corresponding
+ boolean control enabled */
+ unsigned short repeat_delay; /* ms delay until first repeat */
+ unsigned short repeat_interval; /* ms delay between repeats */
+ unsigned short slow_keys_delay; /* ms minimum time key must be
+ down to be ok */
+ unsigned short debounce_delay; /* ms delay before key reactivated */
+ unsigned short mk_delay; /* ms delay to second mouse
+ motion event */
+ unsigned short mk_interval; /* ms delay between repeat mouse
+ events */
+ unsigned short mk_time_to_max; /* # intervals until constant
+ mouse move */
+ unsigned short mk_max_speed; /* multiplier for maximum mouse speed */
+ short mk_curve; /* determines mouse move curve type */
+ unsigned short ax_options; /* 1 bit ⇒ Access X option enabled */
+ unsigned short ax_timeout; /* seconds until Access X disabled */
+ unsigned short axt_opts_mask; /* 1 bit ⇒ options to reset
+ on Access X timeout */
+ unsigned short axt_opts_values; /* 1 bit ⇒ turn option on, 0⇒ off */
+ unsigned int axt_ctrls_mask; /* which bits in <structfield>enabled_ctrls</structfield>
+ to modify */
+ unsigned int axt_ctrls_values; /* values for new bits in
+ <structfield>enabled_ctrls</structfield> */
+ unsigned char per_key_repeat[XkbPerKeyBitArraySize];
+ /* per key auto repeat */
+} <structname>XkbControlsRec</structname>, *XkbControlsPtr;
+</programlisting>
+</para>
+
+<para>
+The general-purpose functions that work with the
+<structname>XkbControlsRec</structname>
+structure use a mask to specify which controls are to be manipulated.
+<link linkend="table10.6">Table 10.6</link>
+lists these controls, the masks used to select them in the general
+function calls
+(<structfield>which</structfield>
+parameter), and the data fields in the
+<structname>XkbControlsRec</structname>
+structure that comprise each of the individual controls. Also listed are the
+bit used to turn boolean controls on and off and the section where each control
+is described in more detail.
+</para>
+
+<table id='table10.6' frame='topbot'>
+<title>Xkb Controls</title>
+<?dbfo keep-together="auto" ?>
+<tgroup cols='5' align='left' colsep='0' rowsep='0'>
+<colspec colname='c1' colwidth='2.0*'/>
+<colspec colname='c2' colwidth='3.1*'/>
+<colspec colname='c3' colwidth='2.2*'/>
+<colspec colname='c4' colwidth='2.6*'/>
+<colspec colname='c5' colwidth='1.0*'/>
+<thead>
+<row rowsep='1'>
+ <entry>Control</entry>
+ <entry>Control Selection Mask (which parameter)</entry>
+ <entry>Relevant XkbControlsRec Data Fields</entry>
+ <entry>Boolean Control enabled_ctrls bit</entry>
+ <entry>Section</entry>
+ </row>
+</thead>
+<tbody>
+ <row>
+ <entry>AccessXFeedback</entry>
+ <entry><symbol>XkbAccessXFeedbackMask</symbol></entry>
+ <entry>ax_options: XkbAX_*FBMask</entry>
+ <entry>XkbAccessXFeedback­Mask</entry>
+ <entry><link linkend="The_AccessXFeedback_Control">10.6.3</link></entry>
+ </row>
+ <row>
+ <entry>AccessXKeys</entry>
+ <entry></entry>
+ <entry></entry>
+ <entry>XkbAccessXKeys­Mask</entry>
+ <entry><link linkend="The_AccessXKeys_Control">10.6.1</link></entry>
+ </row>
+ <row>
+ <entry>AccessXTimeout</entry>
+ <entry><symbol>XkbAccessXTimeoutMask</symbol></entry>
+ <entry>
+ <para>ax_timeout</para>
+ <para>axt_opts_mask</para>
+ <para>axt_opts_values</para>
+ <para>axt_ctrls_mask</para>
+ <para>axt_ctrls_values</para>
+ </entry>
+ <entry>XkbAccessXTimeout­Mask</entry>
+ <entry><link linkend="The_AccessXTimeout_Control">10.6.2</link></entry>
+ </row>
+ <row>
+ <entry>AudibleBell</entry>
+ <entry></entry>
+ <entry></entry>
+ <entry><symbol>XkbAudibleBellMask</symbol></entry>
+ <entry><link linkend="Audible_Bells">9.2</link></entry>
+ </row>
+ <row>
+ <entry>AutoReset</entry>
+ <entry></entry>
+ <entry></entry>
+ <entry></entry>
+ <entry><link linkend="The_AutoReset_Control">10.1.2</link></entry>
+ </row>
+ <row>
+ <entry>BounceKeys</entry>
+ <entry><symbol>XkbBounceKeysMask</symbol></entry>
+ <entry>debounce_delay</entry>
+ <entry><symbol>XkbBounceKeysMask</symbol></entry>
+ <entry><link linkend="The_BounceKeys_Control">10.6.7</link></entry>
+ </row>
+ <row>
+ <entry>Detectable-Autorepeat</entry>
+ <entry></entry>
+ <entry></entry>
+ <entry></entry>
+ <entry><link linkend="The_DetectableAutorepeat_Control">10.3.3</link></entry>
+ </row>
+ <row>
+ <entry>EnabledControls</entry>
+ <entry><symbol>XkbControlsEnabledMask</symbol></entry>
+ <entry>enabled_ctrls</entry>
+ <entry><emphasis>Non-Boolean Control</emphasis></entry>
+ <entry><link linkend="The_EnabledControls_Control">10.1.1</link></entry>
+ </row>
+ <row>
+ <entry>GroupsWrap</entry>
+ <entry><symbol>XkbGroupsWrapMask</symbol></entry>
+ <entry>groups_wrap</entry>
+ <entry><emphasis>Non-Boolean Control</emphasis></entry>
+ <entry><link linkend="The_GroupsWrap_Control">10.7.1</link></entry>
+ </row>
+ <row>
+ <entry>IgnoreGroupLock</entry>
+ <entry></entry>
+ <entry></entry>
+ <entry>XkbIgnoreGroupLock­Mask</entry>
+ <entry><link linkend="The_IgnoreGroupLock_Control">10.7.3</link></entry>
+ </row>
+ <row>
+ <entry>IgnoreLockMods</entry>
+ <entry><symbol>XkbIgnoreLockModsMask</symbol></entry>
+ <entry>ignore_lock</entry>
+ <entry><emphasis>Non-Boolean Control</emphasis></entry>
+ <entry><link linkend="Keyboard_State_Description">5.1</link></entry>
+ </row>
+ <row>
+ <entry>InternalMods</entry>
+ <entry><symbol>XkbInternalModsMask</symbol></entry>
+ <entry>internal</entry>
+ <entry><emphasis>Non-Boolean Control</emphasis></entry>
+ <entry><link linkend="Keyboard_State_Description">5.1</link></entry>
+ </row>
+ <row>
+ <entry>MouseKeys</entry>
+ <entry><symbol>XkbMouseKeysMask</symbol></entry>
+ <entry>mk_dflt_btn</entry>
+ <entry><symbol>XkbMouseKeysMask</symbol></entry>
+ <entry><link linkend="The_MouseKeys_Control">10.5.1</link></entry>
+ </row>
+ <row>
+ <entry>MouseKeysAccel</entry>
+ <entry><symbol>XkbMouseKeysAccelMask</symbol></entry>
+ <entry>
+ <para>mk_delay</para>
+ <para>mk_interval</para>
+ <para>mk_time_to_max</para>
+ <para>mk_max_speed</para>
+ <para>mk_curve</para>
+ </entry>
+ <entry>XkbMouseKeysAccel­Mask</entry>
+ <entry><link linkend="The_MouseKeysAccel_Control">10.5.2</link></entry>
+ </row>
+ <row>
+ <entry>Overlay1</entry>
+ <entry></entry>
+ <entry></entry>
+ <entry><symbol>XkbOverlay1Mask</symbol></entry>
+ <entry><link linkend="Controls_for_Keyboard_Overlays_Overlay1_and_Overlay2_Controls">10.4</link></entry>
+ </row>
+ <row>
+ <entry>Overlay2</entry>
+ <entry></entry>
+ <entry></entry>
+ <entry><symbol>XkbOverlay2Mask</symbol></entry>
+ <entry><link linkend="Controls_for_Keyboard_Overlays_Overlay1_and_Overlay2_Controls">10.4</link></entry>
+ </row>
+ <row>
+ <entry>PerKeyRepeat</entry>
+ <entry><symbol>XkbPerKeyRepeatMask</symbol></entry>
+ <entry>per_key_repeat</entry>
+ <entry><emphasis>Non-Boolean Control</emphasis></entry>
+ <entry><link linkend="The_PerKeyRepeat_Control">10.3.1</link></entry>
+ </row>
+ <row>
+ <entry>RepeatKeys</entry>
+ <entry><symbol>XkbRepeatKeysMask</symbol></entry>
+ <entry>
+ <para>repeat_delay</para>
+ <para>repeat_interval</para>
+ </entry>
+ <entry><symbol>XkbRepeatKeysMask</symbol></entry>
+ <entry><link linkend="Controls_for_Repeat_Key_Behavior">10.3</link></entry>
+ </row>
+ <row>
+ <entry>SlowKeys</entry>
+ <entry><symbol>XkbSlowKeysMask</symbol></entry>
+ <entry>slow_keys_delay</entry>
+ <entry><symbol>XkbSlowKeysMask</symbol></entry>
+ <entry><link linkend="The_SlowKeys_Control">10.6.6</link></entry>
+ </row>
+ <row>
+ <entry>StickyKeys</entry>
+ <entry><symbol>XkbStickyKeysMask</symbol></entry>
+ <entry>
+ <para>ax_options:</para>
+ <para>XkbAX_Two­KeysMask</para>
+ <para>XkbAX_Latch­ToLockMask</para>
+ </entry>
+ <entry><symbol>XkbStickyKeysMask</symbol></entry>
+ <entry><link linkend="The_StickyKeys_Control">10.6.8</link></entry>
+ </row>
+</tbody>
+</tgroup>
+</table>
+
+<para>
+<link linkend="table10.7">Table 10.7</link>
+shows the actual values for the individual mask bits used to select
+controls for modification and to enable and disable the control. Note that the
+same mask bit is used to specify general modifications to the parameters used
+to configure the control
+(<structfield>which</structfield>),
+and to enable and disable the control
+(<structfield>enabled_ctrls</structfield>).
+The anomalies in the table (no <quote>ok</quote> in column) are for controls that have no
+configurable attributes; and for controls that are not boolean controls and
+therefore cannot be enabled or disabled.
+</para>
+
+<table id='table10.7' frame='topbot'>
+<title>Controls Mask Bits</title>
+<?dbfo keep-together="always" ?>
+<tgroup cols='4' align='left' colsep='0' rowsep='0'>
+<colspec colname='c1' colwidth='2.6*'/>
+<colspec colname='c2' colwidth='2.0*'/>
+<colspec colname='c3' colwidth='1.3*'/>
+<colspec colname='c4' colwidth='2.0*'/>
+<thead>
+<row rowsep='1'>
+ <entry>Mask Bit</entry>
+ <entry>which or changed_ctrls</entry>
+ <entry>enabled_ctrls</entry>
+ <entry>Value</entry>
+</row>
+</thead>
+<tbody>
+<row>
+ <entry><symbol>XkbRepeatKeysMask</symbol></entry>
+ <entry>ok</entry>
+ <entry>ok</entry>
+ <entry>(1L<<0)</entry>
+ </row>
+ <row>
+ <entry><symbol>XkbSlowKeysMask</symbol></entry>
+ <entry>ok</entry>
+ <entry>ok</entry>
+ <entry>(1L<<1)</entry>
+ </row>
+ <row>
+ <entry><symbol>XkbBounceKeysMask</symbol></entry>
+ <entry>ok</entry>
+ <entry>ok</entry>
+ <entry>(1L<<2)</entry>
+ </row>
+ <row>
+ <entry><symbol>XkbStickyKeysMask</symbol></entry>
+ <entry>ok</entry>
+ <entry>ok</entry>
+ <entry>(1L<<3)</entry>
+ </row>
+ <row>
+ <entry><symbol>XkbMouseKeysMask</symbol></entry>
+ <entry>ok</entry>
+ <entry>ok</entry>
+ <entry>(1L<<4)</entry>
+ </row>
+ <row>
+ <entry><symbol>XkbMouseKeysAccelMask</symbol></entry>
+ <entry>ok</entry>
+ <entry>ok</entry>
+ <entry>(1L<<5)</entry>
+ </row>
+ <row>
+ <entry><symbol>XkbAccessXKeysMask</symbol></entry>
+ <entry>ok</entry>
+ <entry>ok</entry>
+ <entry>(1L<<6)</entry>
+ </row>
+ <row>
+ <entry><symbol>XkbAccessXTimeoutMask</symbol></entry>
+ <entry>ok</entry>
+ <entry>ok</entry>
+ <entry>(1L<<7)</entry>
+ </row>
+ <row>
+ <entry><symbol>XkbAccessXFeedbackMask</symbol></entry>
+ <entry>ok</entry>
+ <entry>ok</entry>
+ <entry>(1L<<8)</entry>
+ </row>
+ <row>
+ <entry><symbol>XkbAudibleBellMask</symbol></entry>
+ <entry></entry>
+ <entry>ok</entry>
+ <entry>(1L<<9)</entry>
+ </row>
+ <row>
+ <entry><symbol>XkbOverlay1Mask</symbol></entry>
+ <entry></entry>
+ <entry>ok</entry>
+ <entry>(1L<<10)</entry>
+ </row>
+ <row>
+ <entry><symbol>XkbOverlay2Mask</symbol></entry>
+ <entry></entry>
+ <entry>ok</entry>
+ <entry>(1L<<11)</entry>
+ </row>
+ <row>
+ <entry><symbol>XkbIgnoreGroupLockMask</symbol></entry>
+ <entry></entry>
+ <entry>ok</entry>
+ <entry>(1L<<12)</entry>
+</row>
+<row>
+ <entry><symbol>XkbGroupsWrapMask</symbol></entry>
+ <entry>ok</entry>
+ <entry></entry>
+ <entry>(1L<<27)</entry>
+</row>
+<row>
+ <entry><symbol>XkbInternalModsMask</symbol></entry>
+ <entry>ok</entry>
+ <entry></entry>
+ <entry>(1L<<28)</entry>
+</row>
+<row>
+ <entry><symbol>XkbIgnoreLockModsMask</symbol></entry>
+ <entry>ok</entry>
+ <entry></entry>
+ <entry>(1L<<29)</entry>
+</row>
+<row>
+ <entry><symbol>XkbPerKeyRepeatMask</symbol></entry>
+ <entry>ok</entry>
+ <entry></entry>
+ <entry>(1L<<30)</entry>
+</row>
+<row>
+ <entry><symbol>XkbControlsEnabledMask</symbol></entry>
+ <entry>ok</entry>
+ <entry></entry>
+ <entry>(1L<<31)</entry>
+</row>
+<row>
+ <entry><symbol>XkbAccessXOptionsMask</symbol></entry>
+ <entry>ok</entry>
+ <entry>ok</entry>
+ <entry>(XkbStickyKeysMask | XkbAccessXFeedbackMask)</entry>
+ </row>
+ <row>
+ <entry><symbol>XkbAllBooleanCtrlsMask</symbol></entry>
+ <entry></entry>
+ <entry>ok</entry>
+ <entry>(0x00001FFF) </entry>
+ </row>
+ <row>
+ <entry><symbol>XkbAllControlsMask</symbol></entry>
+ <entry>ok</entry>
+ <entry></entry>
+ <entry>(0xF8001FFF)</entry>
+ </row>
+</tbody>
+</tgroup>
+</table>
+
+<para>
+The individual fields of the
+<structname>XkbControlsRec</structname>
+structure are defined as follows.
+</para>
+
+<sect2>
+<title/>
+<sect3 id='mk_dflt_btn'>
+<title>mk_dflt_btn</title>
+
+<para>
+<structfield>mk_dflt_btn</structfield> is an attribute of the
+<emphasis>MouseKeys</emphasis>
+control
+(see <link linkend="Controls_for_Using_the_Mouse_from_the_Keyboard">section 10.5</link>). It
+specifies the mouse button number to use for keyboard simulated mouse button
+operations. Its value should be one of the core symbols
+<symbol>Button1</symbol>
+–
+<symbol>Button5</symbol>.
+</para>
+
+
+</sect3>
+<sect3 id='num_groups'>
+<title>num_groups</title>
+
+<para>
+<structfield>num_groups</structfield>
+is not a part of any control, but is reported in the
+<structname>XkbControlsRec</structname>
+structure whenever any of its components are fetched from the server. It
+reports the number of groups the particular keyboard configuration uses and is
+computed automatically by the server whenever the keyboard mapping changes.
+</para>
+
+
+</sect3>
+<sect3 id='groups_wrap'>
+<title>groups_wrap</title>
+
+<para>
+<structfield>groups_wrap</structfield>
+is an attribute of the
+<emphasis>GroupsWrap</emphasis>
+control (see <link linkend="The_GroupsWrap_Control">section 10.7.1</link>). It specifies the handling of illegal groups on a
+global basis. Valid values for
+<structfield>groups_wrap</structfield>
+are shown in <link linkend="table10.8">Table 10.8</link>.
+</para>
+
+<table id='table10.8' frame='topbot'>
+<title>GroupsWrap options (groups_wrap field)</title>
+<?dbfo keep-together="always" ?>
+<tgroup cols='2' align='left' colsep='0' rowsep='0'>
+<colspec colname='c1' colwidth='1.0*'/>
+<colspec colname='c2' colwidth='1.0*'/>
+<thead>
+<row rowsep='1'>
+ <entry>groups_wrap symbolic name</entry>
+ <entry>value</entry>
+ </row>
+</thead>
+<tbody>
+ <row>
+ <entry><symbol>XkbWrapIntoRange</symbol></entry>
+ <entry>(0x00)</entry>
+ </row>
+ <row>
+ <entry><symbol>XkbClampIntoRange</symbol></entry>
+ <entry>(0x40)</entry>
+ </row>
+ <row>
+ <entry><symbol>XkbRedirectIntoRange</symbol></entry>
+ <entry>(0x80)</entry>
+ </row>
+</tbody>
+</tgroup>
+</table>
+
+<para>
+When
+<structfield>groups_wrap</structfield>
+is set to
+<symbol>XkbRedirectIntoRange</symbol>,
+its four low-order bits specify the index of the group to use.
+</para>
+
+
+</sect3>
+<sect3 id='internal'>
+<title>internal</title>
+
+<para>
+<structfield>internal</structfield>
+is an attribute of the
+<emphasis>InternalMods</emphasis>
+control (see <link linkend="The_InternalMods_Control">section 10.7.4</link>). It specifies modifiers to be consumed in the
+server and not passed on to clients when events are reported. Valid values
+consist of any combination of the eight core modifier bits:
+<symbol>ShiftMask</symbol>,
+<symbol>LockMask</symbol>,
+<symbol>ControlMask</symbol>,
+<symbol>Mod1Mask</symbol>
+–
+<symbol>Mod5Mask</symbol>.
+</para>
+
+
+</sect3>
+<sect3 id='ignore_lock'>
+<title>ignore_lock</title>
+
+<para>
+<structfield>ignore_lock</structfield>
+is an attribute of the
+<emphasis>IgnoreLockMods</emphasis>
+control (see <link linkend="The_IgnoreLockMods_Control">section 10.7.2</link>). It specifies modifiers to be ignored in grab
+calculations. Valid values consist of any combination of the eight core
+modifier bits:
+<symbol>ShiftMask</symbol>,
+<symbol>LockMask</symbol>,
+<symbol>ControlMask</symbol>,
+<symbol>Mod1Mask</symbol>
+–
+<symbol>Mod5Mask</symbol>.
+</para>
+
+
+</sect3>
+<sect3 id='enabled_ctrls'>
+<title>enabled_ctrls</title>
+
+<para>
+<structfield>enabled_ctrls</structfield>
+is an attribute of the
+<emphasis>EnabledControls</emphasis>
+control (see <link linkend="The_EnabledControls_Control">section 10.1.1</link>). It contains one bit per boolean control. Each
+bit determines whether the corresponding control is enabled or disabled; a one
+bit means the control is enabled. The mask bits used to enable these controls
+are listed in <link linkend="table10.7">Table 10.7</link>,
+using only those masks with <quote>ok</quote> in the
+<structfield>enabled_ctrls</structfield>
+column.
+</para>
+
+
+</sect3>
+<sect3 id='repeat_delay_and_repeat_interval'>
+<title>repeat_delay and repeat_interval</title>
+
+<para>
+<structfield>repeat_delay</structfield>
+and
+<structfield>repeat_interval</structfield>
+are attributes of the
+<emphasis>RepeatKeys</emphasis>
+control (see <link linkend="The_RepeatKeys_Control">section 10.3.2</link>).
+<structfield>repeat_delay</structfield>
+is the initial delay before a key begins repeating, in milliseconds;
+<structfield>repeat_interval</structfield>
+is the delay between subsequent key events, in milliseconds.
+</para>
+
+
+</sect3>
+<sect3 id='slow_keys_delay'>
+<title>slow_keys_delay</title>
+
+<para>
+<structfield>slow_keys_delay</structfield>
+is an attribute of the
+<emphasis>SlowKeys</emphasis>
+control (see <link linkend="The_SlowKeys_Control">section 10.6.6</link>). Its value specifies the
+<emphasis>SlowKeys</emphasis>
+acceptance delay period in milliseconds before a key press is accepted by the
+server.
+</para>
+
+
+</sect3>
+<sect3 id='debounce_delay'>
+<title>debounce_delay</title>
+
+<para>
+<structfield>debounce_delay</structfield>
+is an attribute of the
+<emphasis>BounceKeys</emphasis>
+control (see <link linkend="The_BounceKeys_Control">section 10.6.7</link>). Its value specifies the
+<emphasis>BounceKeys</emphasis>
+delay period in milliseconds for which the key is disabled after having been
+pressed before another press of the same key is accepted by the server.
+</para>
+
+
+</sect3>
+<sect3 id='mk_delay_mk_interval_mk_time_to_max_mk_max_speed_and_mk_curve'>
+<title>mk_delay, mk_interval, mk_time_to_max, mk_max_speed, and mk_curve</title>
+
+<para>
+<structfield>mk_delay</structfield>,
+<structfield>mk_interval</structfield>,
+<structfield>mk_time_to_max</structfield>,
+<structfield>mk_max_speed</structfield>,
+and
+<structfield>mk_curve</structfield>
+are attributes of the
+<emphasis>MouseKeysAccel</emphasis>
+control. Refer to <link linkend="The_MouseKeysAccel_Control">section 10.5.2</link> for a description of these fields and the
+units involved.
+</para>
+
+
+</sect3>
+<sect3 id='ax_options'>
+<title>ax_options</title>
+
+<para>
+The
+<structfield>ax_options</structfield>
+field contains attributes used to configure two different controls, the
+<emphasis>StickyKeys</emphasis>
+control (see <link linkend="The_StickyKeys_Control">section 10.6.8</link>) and the
+<emphasis>AccessXFeedback</emphasis>
+control (see <link linkend="The_AccessXFeedback_Control">section 10.6.3</link>). The
+<structfield>ax_options</structfield>
+field is a bitmask and may include any combination of the bits defined in
+<link linkend="table10.9">Table 10.9</link>.
+</para>
+
+<table id='table10.9' frame='topbot'>
+<title>Access X Enable/Disable Bits (ax_options field)</title>
+<?dbfo keep-together="always" ?>
+<tgroup cols='3' align='left' colsep='0' rowsep='0'>
+<colspec colname='c1' colwidth='1.0*'/>
+<colspec colname='c2' colwidth='1.3*'/>
+<colspec colname='c3' colwidth='0.7*'/>
+<thead>
+<row rowsep='1'>
+ <entry>Access X Control</entry>
+ <entry>ax_options bit</entry>
+ <entry>value</entry>
+ </row>
+</thead>
+<tbody>
+ <row>
+ <entry>AccessXFeedback</entry>
+ <entry><symbol>XkbAX_SKPressFBMask</symbol></entry>
+ <entry>(1L<<0)</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry><symbol>XkbAX_SKAcceptFBMask</symbol></entry>
+ <entry>(1L << 1)</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry><symbol>XkbAX_FeatureFBMask</symbol></entry>
+ <entry>(1L << 2)</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry><symbol>XkbAX_SlowWarnFBMask</symbol></entry>
+ <entry>(1L << 3)</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry><symbol>XkbAX_IndicatorFBMask</symbol></entry>
+ <entry>(1L << 4)</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry><symbol>XkbAX_StickyKeysFBMask</symbol></entry>
+ <entry>(1L << 5)</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry><symbol>XkbAX_SKReleaseFBMask</symbol></entry>
+ <entry>(1L << 8)</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry><symbol>XkbAX_SKRejectFBMask</symbol></entry>
+ <entry>(1L << 9)</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry><symbol>XkbAX_BKRejectFBMask</symbol></entry>
+ <entry>(1L << 10)</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry><symbol>XkbAX_DumbBellFBMask</symbol></entry>
+ <entry>(1L << 11)</entry>
+ </row>
+ <row>
+ <entry>StickyKeys</entry>
+ <entry><symbol>XkbAX_TwoKeysMask</symbol></entry>
+ <entry>(1L << 6)</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry><symbol>XkbAX_LatchToLockMask</symbol></entry>
+ <entry>(1L << 7)</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry><symbol>XkbAX_AllOptionsMask</symbol></entry>
+ <entry>(0xFFF)</entry>
+ </row>
+</tbody>
+</tgroup>
+</table>
+
+<para>
+The fields pertaining to each control are relevant only when the control is
+enabled
+(<symbol>XkbAccessXFeedbackMask</symbol>
+or
+<symbol>XkbStickyKeysMask</symbol>
+bit is turned on in the
+<structfield>enabled_ctrls</structfield>
+field).
+</para>
+
+
+<para>
+Xkb provides a set of convenience macros for working with the
+<structfield>ax_options</structfield>
+field of an
+<structname>XkbControlsRec</structname>
+structure:
+
+<programlisting>
+#define <symbol>XkbAX_NeedOption</symbol>(c,w) ((c)->ax_options & (w))
+</programlisting></para>
+
+<para>
+The
+<symbol>XkbAX_NeedOption</symbol>
+macro is useful for determining whether a particular AccessX option is enabled
+or not. It accepts a pointer to an
+<structname>XkbControlsRec</structname>
+structure and a valid mask bit from
+<link linkend="table10.9">Table 10.9</link>.
+If the specified mask bit in the
+<structfield>ax_options</structfield>
+field of the controls structure is set, the macro returns the mask bit.
+Otherwise, it returns zero. Thus,
+
+<programlisting>
+ XkbAX_NeedOption(ctlrec, XkbAX_LatchToLockMask)
+</programlisting>
+
+is nonzero if the latch to lock transition for latching keys is enabled, and
+zero if it is disabled. Note that
+<symbol>XkbAX_NeedOption</symbol>
+only determines whether or not the particular capability is configured to
+operate; the
+<symbol>XkbAccessXFeedbackMask</symbol>
+bit must also be turned on in
+<structfield>enabled_ctrls</structfield>
+for the capability to actually be functioning.
+</para>
+
+<para><programlisting>
+#define <symbol>XkbAX_AnyFeedback</symbol>(c) \
+ ((c)->enabled_ctrls & XkbAccessXFeedbackMask)
+</programlisting></para>
+
+<para>
+The
+<symbol>XkbAX_AnyFeedback</symbol>
+macro accepts a pointer to an
+<structname>XkbControlsRec</structname>
+structure and tells whether the
+<emphasis>AccessXFeedback</emphasis>
+control is enabled or not. If the
+<emphasis>AccessXFeedback</emphasis>
+control is enabled, the macro returns
+<symbol>XkbAccessXFeedbackMask</symbol>.
+Otherwise, it returns zero.
+</para>
+
+<para><programlisting>
+#define <symbol>XkbAX_NeedFeedback</symbol>(c,w) \
+ (XkbAX_AnyFeedback(c) && XkbAX_NeedOption(c,w))
+</programlisting></para>
+
+<para>
+The
+<symbol>XkbAX_NeedFeedback</symbol>
+macro is useful for determining if both the
+<emphasis>AccessXFeedback</emphasis>
+control and a particular AccessX feedback option are enabled. The macro
+accepts a pointer to an
+<structname>XkbControlsRec</structname>
+structure and a feedback option from the table above. If both the
+<emphasis>AccessXFeedback</emphasis>
+control and the specified feedback option are enabled, the macro returns
+<symbol>True</symbol>.
+Otherwise it returns
+<symbol>False</symbol>.
+</para>
+
+
+</sect3>
+<sect3
+id='ax_timeout_axt_opts_mask_axt_opts_values_axt_ctrls_mask_and_axt_ctrls_values'>
+<title>ax_timeout, axt_opts_mask, axt_opts_values, axt_ctrls_mask, and axt_ctrls_values</title>
+
+<para>
+<structfield>ax_timeout</structfield>,
+<structfield>axt_opts_mask</structfield>,
+<structfield>axt_opts_values</structfield>,
+<structfield>axt_ctrls_mask</structfield>,
+and
+<structfield>axt_ctrls_values</structfield>
+are attributes of the
+<emphasis>AccessXTimeout</emphasis>
+control. Refer to <link linkend="The_AccessXTimeout_Control">section 10.6.2</link> for a description of these fields and the
+units involved.
+</para>
+
+
+</sect3>
+<sect3 id='per_key_repeat'>
+<title>per_key_repeat</title>
+
+<para>
+The
+<structfield>per_key_repeat</structfield>
+field mirrors the
+<structfield>auto_repeats</structfield>
+field of the core protocol
+<structname>XKeyboardState</structname>
+structure: changing the
+<structfield>auto_repeats</structfield>
+field automatically changes
+<structfield>per_key_repeat</structfield>
+and vice versa. It is provided for convenience and to reduce protocol traffic.
+For example, to obtain the individual repeat key behavior as well as the repeat
+delay and rate, use
+<function>XkbGetControls</function>.
+If the
+<structfield>per_key_repeat</structfield>
+were not in this structure, you would have to call both
+<function>XGetKeyboardControl</function>
+and
+<function>XkbGetControls</function>
+to get this information. The bits correspond to keycodes. The first seven keys
+(keycodes 1–7) are indicated in
+<structfield>per_key_repeat</structfield>[0],
+with bit position 0 (low order) corresponding to the fictitious keycode 0.
+Following array elements correspond to 8 keycodes per element. A 1 bit
+indicates that the key is a repeating key.
+</para>
+
+
+</sect3>
+</sect2>
+</sect1>
+<sect1 id='Querying_Controls'>
+<title>Querying Controls</title>
+
+<para>
+Use
+<function>XkbGetControls</function>
+to find the current state of Xkb server controls.
+</para>
+
+<indexterm significance="preferred" zone="XkbGetControls"><primary><function>XkbGetControls</function></primary></indexterm>
+<funcsynopsis id="XkbGetControls">
+ <funcprototype>
+ <funcdef>Status <function>XkbGetControls</function></funcdef>
+<!-- (
+<parameter>display, which, xkb)</parameter> -->
+
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>unsigned long <parameter>which</parameter></paramdef>
+ <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef>
+ </funcprototype>
+</funcsynopsis>
+<variablelist>
+ <varlistentry>
+ <term>
+ <parameter>display</parameter>
+ </term>
+ <listitem>
+ <para>
+ connection to X server
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>which</parameter>
+ </term>
+ <listitem>
+ <para>
+ mask of controls requested
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>xkb</parameter>
+ </term>
+ <listitem>
+ <para>
+ keyboard description for controls information
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<function>XkbGetControls</function>
+queries the server for the requested control information, waits for a reply,
+and then copies the server’s values for the requested information into the
+<structfield>ctrls</structfield>
+structure of the
+<parameter>xkb</parameter>
+argument. Only those components specified by the
+<parameter>which</parameter>
+parameter are copied. Valid values for
+<parameter>which</parameter>
+are any combination of the masks listed in
+<link linkend="table10.7">Table 10.7</link> that have <quote>ok</quote> in the
+<parameter>which</parameter>
+column.
+</para>
+
+
+<para>
+If
+<parameter>xkb</parameter>-><structfield>ctrls</structfield>
+is
+<symbol>NULL</symbol>,
+<function>XkbGetControls</function>
+allocates and initializes it before obtaining the values specified by
+<parameter>which</parameter>.
+If
+<parameter>xkb</parameter>-><structfield>ctrls</structfield>
+is not
+<symbol>NULL</symbol>,
+<function>XkbGetControls</function>
+modifies only those portions of
+<parameter>xkb</parameter>-><structfield>ctrls</structfield>
+corresponding to the values specified by
+<parameter>which</parameter>.
+</para>
+
+
+<para>
+<function>XkbGetControls</function>
+returns
+<symbol>Success</symbol>
+if successful; otherwise, it returns
+<errorname>BadAlloc</errorname>
+if it cannot obtain sufficient storage,
+<errorname>BadMatch</errorname>
+if
+<parameter>xkb</parameter>
+is
+<symbol>NULL</symbol>
+or
+<parameter>which</parameter>
+is empty, or
+<errorname>BadImplementation</errorname>.
+</para>
+
+
+<para>
+To free the
+<structfield>ctrls</structfield>
+member of a keyboard description, use
+<function>XkbFreeControls</function>
+(see <link linkend="Allocating_and_Freeing_an_XkbControlsRec">section 10.12</link>)
+</para>
+
+
+<para>
+The
+<structfield>num_groups</structfield>
+field in the
+<structfield>ctrls</structfield>
+structure is always filled in by
+<function>XkbGetControls</function>,
+regardless of which bits are selected by
+<parameter>which</parameter>.
+</para>
+
+
+</sect1>
+<sect1 id='Changing_Controls'>
+<title>Changing Controls</title>
+
+<para>
+There are two ways to make changes to controls: either change a local copy
+keyboard description and call
+<function>XkbSetControls</function>,
+or, to reduce network traffic, use an
+<structname>XkbControlsChangesRec</structname>
+structure and call
+<function>XkbChangeControls</function>.
+</para>
+
+
+<para>
+To change the state of one or more controls, first modify the
+<structfield>ctrls</structfield>
+structure in a local copy of the keyboard description and then use
+<function>XkbSetControls</function>
+to copy those changes to the X server.
+</para>
+
+<indexterm significance="preferred" zone="XkbSetControls"><primary><function>XkbSetControls</function></primary></indexterm>
+<funcsynopsis id="XkbSetControls">
+ <funcprototype>
+ <funcdef>Bool <function>XkbSetControls</function></funcdef>
+<!-- (
+<parameter>display, which, xkb)</parameter> -->
+
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>unsigned long <parameter>which</parameter></paramdef>
+ <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef>
+ </funcprototype>
+</funcsynopsis>
+<variablelist>
+ <varlistentry>
+ <term>
+ <parameter>display</parameter>
+ </term>
+ <listitem>
+ <para>
+ connection to X server
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>which</parameter>
+ </term>
+ <listitem>
+ <para>
+ mask of controls to change
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>xkb</parameter>
+ </term>
+ <listitem>
+ <para>
+ <structfield>ctrls</structfield> field contains new values to be set
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+For each bit that is set in the
+<parameter>which</parameter>
+parameter,
+<function>XkbSetControls</function>
+sends the corresponding values from the
+<parameter>xkb</parameter>-><structfield>ctrls</structfield>
+field to the server. Valid values for
+<parameter>which</parameter>
+are any combination of the masks listed in
+<link linkend="table10.7">Table 10.7</link> that have <quote>ok</quote> in the
+<parameter>which</parameter>
+column.
+</para>
+
+
+<para>
+If
+<parameter>xkb</parameter>-><structfield>ctrls</structfield>
+is
+<symbol>NULL</symbol>,
+the server does not support a compatible version of Xkb, or the Xkb extension
+has not been properly initialized,
+<function>XkbSetControls</function>
+returns
+<symbol>False</symbol>.
+Otherwise, it sends the request to the X server and returns
+<symbol>True</symbol>.
+</para>
+
+
+<para>
+Note that changes to attributes of controls in the
+<structname>XkbControlsRec</structname>
+structure are apparent only when the associated control is enabled, although
+the corresponding values are still updated in the X server. For example, the
+<structfield>repeat_delay</structfield>
+and
+<structfield>repeat_interval</structfield>
+fields are ignored unless the
+<emphasis>RepeatKeys</emphasis>
+control is enabled (that is, the X server’s equivalent of
+<structfield>xkb->ctrls</structfield>
+has
+<symbol>XkbRepeatKeysMask</symbol>
+set in
+<structfield>enabled_ctrls</structfield>).
+It is permissible to modify the attributes of a control in one call to
+XkbSetControls and enable the control in a subsequent call. See <link linkend="The_EnabledControls_Control">section 10.1.1</link>
+for more information on enabling and disabling controls.
+</para>
+
+
+<para>
+Note that the
+<structfield>enabled_ctrls</structfield>
+field is itself a control — the
+<emphasis>EnabledControls</emphasis>
+control. As such, to set a specific configuration of enabled and disabled
+boolean controls, you must set
+<structfield>enabled_ctrls</structfield>
+to the appropriate bits to enable only the controls you want and disable all
+others, then specify the
+<symbol>XkbControlsEnabledMask</symbol>
+in a call to
+<function>XkbSetControls</function>.
+Because this is somewhat awkward if all you want to do is enable and disable
+controls, and not modify any of their attributes, a convenience function is
+also provided for this purpose
+(<function>XkbChangeEnabledControls</function>,
+<link linkend="The_EnabledControls_Control">section 10.1.1</link>).
+</para>
+
+
+<sect2 id='The_XkbControlsChangesRec_Structure'>
+<title>The XkbControlsChangesRec Structure</title>
+
+<indexterm significance="preferred" zone="The_XkbControlsChangesRec_Structure">
+<primary><structname>XkbControlsChangesRec</structname></primary></indexterm>
+
+<para>
+The
+<structname>XkbControlsChangesRec</structname>
+structure allows applications to track modifications to an
+<structname>XkbControlsRec</structname>
+structure and thereby reduce the amount of traffic sent to the server. The
+same
+<structname>XkbControlsChangesRec</structname>
+structure may be used in several successive modifications to the same
+<structname>XkbControlsRec</structname>
+structure, then subsequently used to cause all of the changes, and only the
+changes, to be propagated to the server. The
+<structname>XkbControlsChangesRec</structname>
+structure is defined as follows:
+
+<programlisting>
+typedef struct _XkbControlsChanges {
+ unsigned int changed_ctrls; /* bits indicating changed
+ control data */
+ unsigned int enabled_ctrls_changes; /* bits indicating
+ enabled/disabled controls */
+ Bool num_groups_changed; /* <symbol>True</symbol> if number of keyboard
+ groups changed */
+} <structname>XkbControlsChangesRec</structname>, *XkbControlsChangesPtr;
+</programlisting></para>
+
+<para>
+The
+<structfield>changed_ctrls</structfield>
+field is a mask specifying which logical sets of data in the controls
+structure have been modified. In this context, modified means
+<emphasis>set</emphasis>,
+that is, if a value is set to the same value it previously contained, it has
+still been modified, and is noted as changed. Valid values for
+<structfield>changed_ctrls</structfield>
+are any combination of the masks listed in
+<link linkend="table10.7">Table 10.7</link> that have <quote>ok</quote> in the
+<structfield>changed_ctrls</structfield>
+column. Setting a bit implies the corresponding data fields from the
+<quote>Relevant XkbControlsRec Data Fields</quote> column in
+<link linkend="table10.6">Table 10.6</link> have been modified. The
+<structfield>enabled_ctrls_changes</structfield>
+field specifies which bits in the
+<structfield>enabled_ctrls</structfield>
+field have changed. If the number of keyboard groups has changed, the
+<structfield>num_groups_changed</structfield>
+field is set to <symbol>True</symbol>.
+</para>
+
+
+<para>
+If you have an Xkb description with controls that have been modified and an
+<structname>XkbControlsChangesRec</structname>
+that describes the changes that have been made, the
+<function>XkbChangeControls</function>
+function provides a flexible method for updating the controls in a server to
+match those in the changed keyboard description.
+</para>
+
+<indexterm significance="preferred" zone="XkbChangeControls"><primary><function>XkbChangeControls</function></primary></indexterm>
+<funcsynopsis id="XkbChangeControls">
+ <funcprototype>
+ <funcdef>Bool <function>XkbChangeControls</function></funcdef>
+<!-- (
+<parameter>dpy, xkb, changes</parameter>
+) -->
+
+ <paramdef>Display *<parameter>dpy</parameter></paramdef>
+ <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef>
+ <paramdef>XkbControlsChangesPtr <parameter>changes</parameter></paramdef>
+ </funcprototype>
+</funcsynopsis>
+<variablelist>
+ <varlistentry>
+ <term>
+ <parameter>dpy</parameter>
+ </term>
+ <listitem>
+ <para>
+ connection to X server
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>xkb</parameter>
+ </term>
+ <listitem>
+ <para>
+ keyboard description with changed <structfield>xkb->ctrls</structfield>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>changes</parameter>
+ </term>
+ <listitem>
+ <para>
+ which parts of <structfield>xkb->ctrls</structfield> have changed
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<function>XkbChangeControls</function>
+copies any controls fields specified by
+<parameter>changes</parameter>
+from the keyboard description controls structure,
+<parameter>xkb</parameter>-><structfield>ctrls</structfield>,
+to the server specified by
+<parameter>dpy</parameter>.
+</para>
+
+
+</sect2>
+</sect1>
+<sect1 id='Tracking_Changes_to_Keyboard_Controls'>
+<title>Tracking Changes to Keyboard Controls</title>
+
+<indexterm significance="preferred" zone="Tracking_Changes_to_Keyboard_Controls">
+<primary>events</primary><secondary><symbol>XkbControlsNotify</symbol></secondary></indexterm>
+<indexterm significance="preferred" zone="Tracking_Changes_to_Keyboard_Controls">
+<primary><structname>XkbControlsNotifyEvent</structname></primary></indexterm>
+
+<para>
+Whenever a field in the controls structure changes in the server’s keyboard
+description, the server sends an
+<symbol>XkbControlsNotify</symbol>
+event to all interested clients.To receive
+<symbol>XkbControlsNotify</symbol>
+events under all possible conditions, use
+<function>XkbSelectEvents</function>
+(see <link linkend="Selecting_Xkb_Events">section 4.3</link>) and pass
+<symbol>XkbControlsNotifyMask</symbol>
+in both
+<parameter>bits_to_change</parameter>
+and
+<parameter>values_for_bits</parameter>.
+</para>
+
+
+<para>
+To receive
+<symbol>XkbControlsNotify</symbol>
+events only under certain conditions, use
+<function>XkbSelectEventDetails</function>
+using
+<symbol>XkbControlsNotify</symbol>
+as the
+<structfield>event_type</structfield>
+and specifying the desired state changes in
+<parameter>bits_to_change</parameter>
+and
+<parameter>values_for_bits</parameter>
+using mask bits from <link linkend="table10.7">Table 10.7</link>.
+</para>
+
+
+<para>
+The structure for the
+<symbol>XkbControlsNotify</symbol>
+event is defined as follows:
+
+<programlisting>
+typedef struct {
+ int type; /* Xkb extension base event code */
+ unsigned long serial; /* X server serial number for event */
+ Bool send_event; /* <symbol>True</symbol> ⇒ synthetically generated */
+ Display * display; /* server connection where event generated */
+ Time time; /* server time when event generated */
+ int xkb_type; /* <symbol>XkbCompatMapNotify</symbol> */
+ int device; /* Xkb device ID,
+ will not be <symbol>XkbUseCoreKbd</symbol> */
+ unsigned int changed_ctrls; /* bits indicating which controls
+ data have changed */
+ unsigned int enabled_ctrls; /* controls currently enabled in server */
+ unsigned int enabled_ctrl_changes; /* bits indicating
+ enabled/disabled controls */
+ int num_groups; /* current number of keyboard groups */
+ KeyCode keycode; /* != 0 ⇒ keycode of key causing change */
+ char event_type; /* Type of event causing change */
+ char req_major; /* major event code of event causing change */
+ char req_minor; /* minor event code of event causing change */
+} <structname>XkbControlsNotifyEvent</structname>;
+</programlisting></para>
+
+<para>
+The
+<structfield>changed_ctrls</structfield>
+field specifies the controls components that have changed and consists of bits
+taken from the masks defined in
+<link linkend="table10.7">Table 10.7</link> with <quote>ok</quote> in the
+<structfield>changed_ctrls</structfield>
+column.
+</para>
+
+
+<para>
+The controls currently enabled in the server are reported in the
+<structfield>enabled_ctrls</structfield>
+field. If any controls were just enabled or disabled (that is, the contents of
+the
+<structfield>enabled_ctrls</structfield>
+field changed), they are flagged in the
+<structfield>enabled_ctrl_changes</structfield>
+field. The valid bits for these fields are the masks listed in
+<link linkend="table10.7">Table 10.7</link> with
+<quote>ok</quote> in the
+<structfield>enabled_ctrls</structfield>
+column. The
+<structfield>num_groups</structfield>
+field reports the number of groups bound to the key belonging to the most
+number of groups and is automatically updated when the keyboard mapping changes.
+</para>
+
+
+<para>
+If the change was caused by a request from a client, the
+<structfield>keycode</structfield>
+and
+<structfield>event_type</structfield>
+fields are set to
+<emphasis>zero</emphasis>
+and the
+<structfield>req_major</structfield>
+and
+<structfield>req_minor</structfield>
+fields identify the request. The
+<structfield>req_major</structfield>
+value is the same as the major extension opcode. Otherwise,
+<structfield>event_type</structfield>
+is set to the type of event that caused the change (one of
+<symbol>KeyPress</symbol>,
+<symbol>KeyRelease</symbol>,
+<symbol>DeviceKeyPress</symbol>,
+<symbol>DeviceKeyRelease</symbol>,
+<symbol>ButtonPress</symbol>
+or
+<symbol>ButtonRelease</symbol>),
+and
+<structfield>req_major</structfield>
+and
+<structfield>req_minor</structfield>
+are undefined. If
+<structfield>event_type</structfield>
+is
+<symbol>KeyPress</symbol>,
+<symbol>KeyRelease</symbol>,
+<symbol>DeviceKeyPress</symbol>,
+or
+<symbol>DeviceKeyRelease</symbol>,
+the
+<structfield>keycode</structfield>
+field is set to the key that caused the change. If
+<structfield>event_type</structfield>
+is
+<symbol>ButtonPress</symbol>
+or
+<symbol>ButtonRelease</symbol>,
+<structfield>keycode</structfield>
+contains the button number.
+</para>
+
+
+<para>
+When a client receives an
+<symbol>XkbControlsNotify</symbol>
+event, it can note the changes in a changes structure using
+<function>XkbNoteControlsChanges</function>.
+</para>
+
+<indexterm significance="preferred" zone="XkbNoteControlsChanges"><primary><function>XkbNoteControlsChanges</function></primary></indexterm>
+<funcsynopsis id="XkbNoteControlsChanges">
+ <funcprototype>
+ <funcdef>void <function>XkbNoteControlsChanges</function></funcdef>
+<!-- (
+<parameter>changes</parameter>,
+<parameter>new</parameter>,
+<parameter>wanted</parameter>
+) -->
+
+ <paramdef>XkbControlsChangesPtr <parameter>changes</parameter></paramdef>
+ <paramdef>XkbControlsNotifyEvent *<parameter>new</parameter></paramdef>
+ <paramdef>unsigned int <parameter>wanted</parameter></paramdef>
+ </funcprototype>
+</funcsynopsis>
+<variablelist>
+ <varlistentry>
+ <term>
+ <parameter>changes</parameter>
+ </term>
+ <listitem>
+ <para>
+ records changes indicated by new
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>new</parameter>
+ </term>
+ <listitem>
+ <para>
+ tells which things have changed
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>wanted</parameter>
+ </term>
+ <listitem>
+ <para>
+ tells which parts of new to record in changes
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The
+<parameter>wanted</parameter>
+parameter is a bitwise inclusive OR of bits taken from the set of masks
+specified in <link linkend="table10.7">Table 10.7</link> with <quote>ok</quote>
+in the
+<structfield>changed_ctrls</structfield>
+column.
+<function>XkbNoteControlsChanges</function>
+copies any changes reported in
+<parameter>new</parameter>
+and specified in
+<parameter>wanted</parameter>
+into the changes record specified by
+<parameter>changes</parameter>.
+</para>
+
+
+<para>
+Use
+<function>XkbGetControlsChanges</function>
+to update a local copy of a keyboard description with the changes previously
+noted by one or more calls to
+<function>XkbNoteControlsChanges</function>.
+</para>
+
+
+<indexterm significance="preferred" zone="XkbGetControlsChanges"><primary><function>XkbGetControlsChanges</function></primary></indexterm>
+<funcsynopsis id="XkbGetControlsChanges">
+ <funcprototype>
+ <funcdef>Status <function>XkbGetControlsChanges</function></funcdef>
+<!-- (
+<parameter>dpy</parameter>,
+<parameter>xkb</parameter>,
+<parameter>changes</parameter>
+) -->
+
+ <paramdef>Display *<parameter>dpy</parameter></paramdef>
+ <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef>
+ <paramdef>XkbNameChangesPtr <parameter>changes</parameter></paramdef>
+ </funcprototype>
+</funcsynopsis>
+<variablelist>
+ <varlistentry>
+ <term>
+ <parameter>dpy</parameter>
+ </term>
+ <listitem>
+ <para>
+ connection to X server
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>xkb</parameter>
+ </term>
+ <listitem>
+ <para>
+ <structfield>xkb->ctrls</structfield> will be updated
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>changes</parameter>
+ </term>
+ <listitem>
+ <para>
+ indicates which parts of <structfield>xkb->ctrls</structfield> to update
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<function>XkbGetControlsChanges</function>
+examines the
+<parameter>changes</parameter>
+parameter, queries the server for the necessary information, and copies the
+results into the
+<parameter>xkb</parameter>-><structfield>ctrls</structfield>
+keyboard description. If the
+<structfield>ctrls</structfield>
+field of
+<parameter>xkb</parameter>
+is
+<symbol>NULL</symbol>,
+<function>XkbGetControlsChanges</function>
+allocates and initializes it. To free the
+<structfield>ctrls</structfield>
+field, use
+<function>XkbFreeControls</function>
+(see <link linkend="Allocating_and_Freeing_an_XkbControlsRec">section 10.12</link>).
+</para>
+
+
+<para>
+<function>XkbGetControlsChanges</function>
+returns
+<symbol>Success</symbol>
+if successful and can generate
+<errorname>BadAlloc</errorname>,
+<errorname>BadImplementation</errorname>,
+and
+<errorname>BadMatch</errorname>
+errors.
+</para>
+
+
+</sect1>
+<sect1 id='Allocating_and_Freeing_an_XkbControlsRec'>
+<title>Allocating and Freeing an XkbControlsRec</title>
+
+<para>
+The need to allocate an
+<structname>XkbControlsRec</structname>
+structure seldom arises; Xkb creates one when an application calls
+<function>XkbGetControls</function>
+or a related function. For those situations where there is not an
+<structname>XkbControlsRec</structname>
+structure allocated in the
+<structname>XkbDescRec</structname>,
+allocate one by calling
+<function>XkbAllocControls</function>.
+</para>
+
+<indexterm significance="preferred" zone="XkbAllocControls"><primary><function>XkbAllocControls</function></primary></indexterm>
+<funcsynopsis id="XkbAllocControls">
+ <funcprototype>
+ <funcdef>Status <function>XkbAllocControls</function></funcdef>
+<!-- (
+<parameter>xkb, which</parameter>
+) -->
+
+ <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef>
+ <paramdef>unsigned int <parameter>which</parameter></paramdef>
+ </funcprototype>
+</funcsynopsis>
+<variablelist>
+ <varlistentry>
+ <term>
+ <parameter>xkb</parameter>
+ </term>
+ <listitem>
+ <para>
+ Xkb description in which to allocate ctrls rec
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>which</parameter>
+ </term>
+ <listitem>
+ <para>
+ mask of components of <structfield>ctrls</structfield> to allocate
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<function>XkbAllocControls</function>
+allocates the
+<structfield>ctrls</structfield>
+field of the
+<parameter>xkb</parameter>
+parameter, initializes all fields to zero, and returns
+<symbol>Success</symbol>.
+If the
+<structfield>ctrls</structfield>
+field is not
+<symbol>NULL</symbol>,
+<function>XkbAllocControls</function>
+simply returns
+<symbol>Success</symbol>.
+If
+<parameter>xkb</parameter>
+is
+<symbol>NULL</symbol>,
+<function>XkbAllocControls</function>
+reports a
+<errorname>BadMatch</errorname>
+error. If the
+<structfield>ctrls</structfield>
+field could not be allocated, it reports a
+<errorname>BadAlloc</errorname>
+error.
+</para>
+
+
+<para>
+The
+<parameter>which</parameter>
+mask specifies the individual fields of the
+<structfield>ctrls</structfield>
+structure to be allocated and can contain any of the valid masks defined in
+<link linkend="table10.7">Table 10.7</link>.
+Because none of the currently existing controls have any structures
+associated with them, which is currently of little practical value in this call.
+</para>
+
+
+<para>
+To free memory used by the
+<structfield>ctrls</structfield>
+member of an
+<structname>XkbDescRec</structname>
+structure, use
+<function>XkbFreeControls</function>:
+</para>
+
+
+<indexterm significance="preferred" zone="XkbFreeControls"><primary><function>XkbFreeControls</function></primary></indexterm>
+<funcsynopsis id="XkbFreeControls">
+ <funcprototype>
+ <funcdef>void <function>XkbFreeControls</function></funcdef>
+<!-- (
+<parameter>xkb, which, free_all</parameter>
+) -->
+
+ <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef>
+ <paramdef>unsigned int <parameter>which</parameter></paramdef>
+ <paramdef>Bool <parameter>free_all</parameter></paramdef>
+ </funcprototype>
+</funcsynopsis>
+<variablelist>
+ <varlistentry>
+ <term>
+ <parameter>xkb</parameter>
+ </term>
+ <listitem>
+ <para>
+ Xkb description in which to free controls components
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>which</parameter>
+ </term>
+ <listitem>
+ <para>
+ mask of components of <structfield>ctrls</structfield> to free
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>free_all</parameter>
+ </term>
+ <listitem>
+ <para>
+ <symbol>True</symbol> ⇒ free everything + ctrls itself
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<function>XkbFreeControls</function>
+frees the specified components of the
+<structfield>ctrls</structfield>
+field in the
+<parameter>xkb</parameter>
+keyboard description and sets the corresponding structure component values to
+<symbol>NULL</symbol>
+or
+<emphasis>zero</emphasis>.
+The
+<parameter>which</parameter>
+mask specifies the fields of
+<structfield>ctrls</structfield>
+to be freed and can contain any of the controls components specified in
+<link linkend="table10.7">Table 10.7</link>.
+</para>
+
+
+<para>
+If
+<parameter>free_all</parameter>
+is
+<symbol>True</symbol>,
+<function>XkbFreeControls</function>
+frees every non-
+<symbol>NULL</symbol>
+structure component in the controls, frees the
+<structname>XkbControlsRec</structname>
+structure referenced by the
+<structfield>ctrls</structfield>
+member of
+<parameter>xkb</parameter>,
+and sets
+<structfield>ctrls</structfield>
+to
+<symbol>NULL</symbol>.
+</para>
+
+</sect1>
+<sect1 id='The_Miscellaneous_Per_client_Controls'>
+<title>The Miscellaneous Per-client Controls</title>
+
+<para>
+You can configure the boolean per-client controls which affect the state
+reported in button and key events. See
+section 12.1.1,
+12.3,
+12.5,
+and
+16.3.11
+of the
+<citetitle>XKB Protocol specification</citetitle>
+for more details.
+</para>
+
+
+<para>
+To get the current values of the
+<emphasis>per-client</emphasis>
+controls, use
+<function>XkbGetPerClientControls</function>.
+</para>
+
+<indexterm significance="preferred" zone="XkbGetPerClientControls"><primary><function>XkbGetPerClientControls</function></primary></indexterm>
+<funcsynopsis id="XkbGetPerClientControls">
+ <funcprototype>
+ <funcdef>Bool <function>XkbGetPerClientControls</function></funcdef>
+<!-- (
+<parameter>dpy</parameter>,
+<parameter>ctrls</parameter>
+) -->
+
+ <paramdef>Display *<parameter>dpy</parameter></paramdef>
+ <paramdef>unsigned int *<parameter>ctrls</parameter></paramdef>
+ </funcprototype>
+</funcsynopsis>
+<variablelist>
+ <varlistentry>
+ <term>
+ <parameter>dpy</parameter>
+ </term>
+ <listitem>
+ <para>
+ connection to X server
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>ctrls</parameter>
+ </term>
+ <listitem>
+ <para>
+ 1 bit ⇒ corresponding control is on
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<function>XkbGetPerClientControls</function>
+backfills
+<parameter>ctrls</parameter>
+with the
+<emphasis>per-client</emphasis>
+control attributes for this particular client. It returns
+<symbol>True</symbol>
+if successful, and
+<symbol>False</symbol>
+otherwise.
+</para>
+
+
+<para>
+To change the current values of the
+<emphasis>per-client</emphasis>
+control attributes, use
+<function>XkbSetPerClientControls</function>.
+</para>
+
+
+<indexterm significance="preferred" zone="XkbSetPerClientControls"><primary><function>XkbSetPerClientControls</function></primary></indexterm>
+<funcsynopsis id="XkbSetPerClientControls">
+ <funcprototype>
+ <funcdef>Bool <function>XkbSetPerClientControls</function></funcdef>
+<!-- (
+<parameter>dpy</parameter>,
+<parameter>ctrls</parameter>
+) -->
+
+ <paramdef>Display *<parameter>dpy</parameter></paramdef>
+ <paramdef>unsigned int <parameter>change</parameter></paramdef>
+ <paramdef>unsigned int *<parameter>value</parameter></paramdef>
+ </funcprototype>
+</funcsynopsis>
+<variablelist>
+ <varlistentry>
+ <term>
+ <parameter>dpy</parameter>
+ </term>
+ <listitem>
+ <para>
+ connection to X server
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>change</parameter>
+ </term>
+ <listitem>
+ <para>
+ 1 bit ⇒ change control
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>value</parameter>
+ </term>
+ <listitem>
+ <para>
+ 1 bit ⇒ control on
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<function>XkbSetPerClientControls</function>
+changes the per-client values for the controls selected by
+<parameter>change</parameter> to the corresponding value in
+<parameter>value</parameter>. Legal values for
+<parameter>change</parameter> and <parameter>value</parameter>
+are: XkbPCF_GrabsUseXKBStateMask, XkbPCF_LookupStateWhenGrabbed, and
+XkbPCF_SendEventUsesXKBState. More than one control may be changed at one time
+by OR-ing the values together. XkbSetPerClientControls backfills value with the
+<emphasis>per-client</emphasis>
+control attributes for this particular client.
+It returns
+<symbol>True</symbol>
+if successful, and
+<symbol>False</symbol>
+otherwise.
+</para>
+
+</sect1>
+</chapter>
Index: create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/XKB/ch12.xml
===================================================================
--- create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/XKB/ch12.xml (nonexistent)
+++ create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/XKB/ch12.xml (revision 5)
@@ -0,0 +1,886 @@
+<?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='Interpreting_Key_Events'>
+<title>Interpreting Key Events</title>
+
+<para>
+Xkb provides functions to help developers interpret key events without having
+to directly interpret Xkb data structures. Xkb also modifies the behavior of
+several core X library functions.
+</para>
+
+<sect1 id='Effects_of_Xkb_on_the_Core_X_Library'>
+<title>Effects of Xkb on the Core X Library</title>
+
+<para>
+When support for Xkb is built into the X library, the
+<function>XOpenDisplay</function>
+function looks for a compatible version of Xkb on the server. If it finds a
+compatible version, it initializes the extension and enables
+<firstterm>implicit support</firstterm>
+for Xkb in a number of X library functions. This makes it possible for clients
+to take advantage of nearly all Xkb features without having to be rewritten or
+even recompiled, if they are built with shared libraries. This implicit support
+is invisible to most clients, but it can have side effects, so the extension
+includes ways to control or disable it.
+</para>
+
+
+<sect2 id='Effects_of_Xkb_on_Event_State'>
+<title>Effects of Xkb on Event State</title>
+
+<para>
+Because
+<function>XOpenDisplay</function>
+initializes Xkb, some events contain an Xkb description of the keyboard state
+instead of that normally used by the core protocol. See <link linkend="Xkb_State_to_Core_Protocol_State_Transformation">section 17.1.1</link> for more
+information about the differences between Xkb keyboard state and that reported
+by the core protocol.
+</para>
+
+
+</sect2>
+<sect2 id='Effects_of_Xkb_on_MappingNotify_Events'>
+<title>Effects of Xkb on MappingNotify Events</title>
+
+<indexterm zone="Effects_of_Xkb_on_MappingNotify_Events">
+<primary>events</primary><secondary><symbol>MappingNotify</symbol></secondary></indexterm>
+
+<para>
+When Xkb is missing or disabled, the X library tracks changes to the keyboard
+mapping using
+<symbol>MappingNotify</symbol>
+events. Whenever the keyboard mapping is changed, the server sends all clients
+a
+<symbol>MappingNotify</symbol>
+event to report the change. When a client receives a
+<symbol>MappingNotify</symbol>
+event, it is supposed to call
+<function>XRefreshKeyboardMapping</function>
+to update the keyboard description used internally by the X library.
+</para>
+
+
+<para>
+The X Keyboard Extension uses
+<symbol>XkbMapNotify</symbol>
+and
+<symbol>XkbNewKeyboardNotify</symbol>
+events to track changes to the keyboard mapping. When an Xkb-aware client
+receives either event, it should call
+<function>XkbRefreshKeyboardMapping</function>
+to update the keyboard description used internally by the X library. To avoid
+duplicate events, the X server does not send core protocol
+<symbol>MappingNotify</symbol>
+events to a client that has selected for
+<symbol>XkbMapNotify</symbol>
+events.
+</para>
+
+
+<para>
+The implicit support for Xkb selects for
+<symbol>XkbMapNotify</symbol>
+events. This means that clients that do not explicitly use Xkb but that are
+using a version of the X library that has implicit support for Xkb do not
+receive
+<symbol>MappingNotify</symbol>
+events over the wire. Clients that were not written with Xkb in mind do not
+recognize or properly handle the new Xkb events, so the implicit support
+converts them to
+<symbol>MappingNotify</symbol>
+events that report approximately the same information, unless the client has
+explicitly selected for the Xkb version of the event.
+</para>
+
+
+<para>
+An Xkb-capable X server does not send events from keys that fall outside the
+legal range of keycodes expected by that client. Once the server sends a client
+an
+<symbol>XkbNewKeyboardNotify</symbol>
+event, it reports events from all keys because it assumes that any client that
+has received an
+<symbol>XkbNewKeyboardNotify</symbol>
+event expects key events from the new range of keycodes. The implicit support
+for Xkb asks for
+<symbol>XkbNewKeyboardNotify</symbol>
+events, so the range of keycodes reported to the client might vary without the
+client’s knowledge. Most clients don’t really care about the range of legal
+keycodes, but some clients maintain information about each key and might have
+problems with events that come from unexpected keys. Such clients can set the
+<symbol>XkbLC_IgnoreNewKeyboards</symbol>
+library control (see <link linkend="IgnoreNewKeyboards">section 11.3.1</link>) to prevent the implicit support from
+requesting notification of changes to the legal range of keycodes.
+</para>
+
+
+</sect2>
+<sect2 id='X_Library_Functions_Affected_by_Xkb'>
+<title>X Library Functions Affected by Xkb</title>
+
+<para>
+The following X library functions are modified by Xkb:
+
+ <simplelist type='vert' columns='1'>
+ <member><function>XKeycodeToKeysym</function></member>
+ <member><function>XKeysymToKeycode</function></member>
+ <member><function>XLookupKeysym</function></member>
+ <member><function>XLookupString</function></member>
+ <member><function>XRefreshKeyboardMapping</function></member>
+ <member><function>XRebindKeysym</function></member>
+ </simplelist>
+</para>
+
+<para>
+The implicit support for Xkb replaces a number of X library functions with
+versions that understand and use the X Keyboard Extension. In most cases, the
+semantics of the new versions are identical to those of the old, but there are
+occasional visible differences. This section lists all of the functions that
+are affected and the differences in behavior, if any, that are visible to
+clients.
+</para>
+
+
+<para id='XKeycodeToKeysym'>
+The
+<function>XKeycodeToKeysym</function>
+<indexterm significance="preferred" zone="XKeycodeToKeysym"><primary><function>XKeycodeToKeysym</function></primary></indexterm>
+function reports the keysym associated with a particular index for a single
+key. The index specifies a column of symbols in the core keyboard mapping (that
+is, as reported by the core protocol
+<systemitem>GetKeyboardMapping</systemitem>
+request). The order of the symbols in the core mapping does not necessarily
+correspond to the order of the symbols used by Xkb; <link linkend="Xkb_Keyboard_Mapping_to_Core_Keyboard_Mapping_Transformations">section 17.1.3</link> describes
+the differences.
+</para>
+
+
+<para id='XKeysymToKeycode'>
+The
+<function>XKeysymToKeycode</function>
+<indexterm significance="preferred" zone="XKeysymToKeycode"><primary><function>XKeysymToKeycode</function></primary></indexterm>
+function reports a keycode to which a particular keysym is bound. When Xkb is
+missing or disabled, this function looks in each column of the core keyboard
+mapping in turn and returns the lowest numbered key that matches in the lowest
+numbered group. When Xkb is present, this function uses the Xkb ordering for
+symbols instead.
+</para>
+
+
+<para id='XLookupKeysym'>
+The
+<function>XLookupKeysym</function>
+<indexterm significance="preferred" zone="XLookupKeysym"><primary><function>XLookupKeysym</function></primary></indexterm>
+function reports the symbol in a specific column of the key associated with an
+event. Whether or not Xkb is present, the column specifies an index into the
+core symbol mapping.
+</para>
+
+
+<para id='XLookupString'>
+The
+<function>XLookupString</function>
+<indexterm significance="preferred" zone="XLookupString"><primary><function>XLookupString</function></primary></indexterm>
+function reports the symbol and string associated with a key event, taking
+into account the keycode and keyboard state as reported in the event. When Xkb
+is disabled or missing,
+<function>XLookupString</function>
+uses the rules specified by the core protocol and reports only ISO Latin-1
+characters. When Xkb is present,
+<function>XLookupString</function>
+uses the explicit keyboard group, key types, and rules specified by Xkb. When
+Xkb is present,
+<function>XLookupString</function>
+is allowed, but not required, to return strings in character sets other than
+ISO Latin-1, depending on the current locale. If any key bindings are defined,
+<function>XLookupString</function>
+does not use any consumed modifiers (see <link linkend="ConsumeLookupMods">section 11.1.2</link> and <link linkend="Key_Types">section 15.2</link>) to
+determine matching bindings.
+</para>
+
+
+<para id='XRefreshKeyboardMapping'>
+The
+<function>XRefreshKeyboardMapping</function>
+<indexterm significance="preferred" zone="XRefreshKeyboardMapping"><primary><function>XRefreshKeyboardMapping</function></primary></indexterm>
+function updates the X library’s internal representation of the keyboard to
+reflect changes reported via
+<symbol>MappingNotify</symbol>
+events. When Xkb is missing or disabled, this function reloads the entire
+modifier map or keyboard mapping. When Xkb is present, the implicit Xkb support
+keeps track of the changed components reported by each
+<symbol>XkbMapNotify</symbol>
+event and updates only those pieces of the keyboard description that have
+changed. If the implicit support has not noted any keyboard mapping changes,
+<function>XRefreshKeyboardMapping</function>
+updates the entire keyboard description.
+</para>
+
+
+<para id='XRebindKeysym'>
+The
+<function>XRebindKeysym</function>
+<indexterm significance="preferred" zone="XRebindKeysym"><primary><function>XRebindKeysym</function></primary></indexterm>
+function associates a string with a keysym and a set of modifiers. Xkb does
+not directly change this function, but it does affect the way that the state
+reported in the event is compared to the state specified to
+<function>XRebindKeysym</function>.
+When Xkb is missing or disabled,
+<function>XLookupString</function>
+returns the specified string if the modifiers in the event exactly match the
+modifiers from this call. When Xkb is present, any modifiers used to determine
+the keysym are consumed and are not used to look up the string.
+</para>
+
+
+</sect2>
+</sect1>
+<sect1 id='Xkb_Event_and_Keymap_Functions'>
+<title>Xkb Event and Keymap Functions</title>
+
+<para>
+To find the keysym bound to a particular key at a specified group and shift
+level, use <function>XkbKeycodeToKeysym</function>.
+</para>
+
+<indexterm significance="preferred" zone="XkbKeycodeToKeysym"><primary><function>XkbKeycodeToKeysym</function></primary></indexterm>
+<funcsynopsis id="XkbKeycodeToKeysym">
+ <funcprototype>
+ <funcdef>KeySym <function>XkbKeycodeToKeysym</function></funcdef>
+<!-- (
+<parameter>dpy, kc, group, level</parameter>
+) -->
+
+ <paramdef>Display *<parameter>dpy</parameter></paramdef>
+ <paramdef>KeyCode <parameter>kc</parameter></paramdef>
+ <paramdef>unsigned int <parameter>group</parameter></paramdef>
+ <paramdef>unsigned int <parameter>level</parameter></paramdef>
+ </funcprototype>
+</funcsynopsis>
+<variablelist>
+ <varlistentry>
+ <term>
+ <parameter>dpy</parameter>
+ </term>
+ <listitem>
+ <para>
+ connection to X server
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>kc</parameter>
+ </term>
+ <listitem>
+ <para>
+ key of interest
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>group</parameter>
+ </term>
+ <listitem>
+ <para>
+ group of interest
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>level</parameter>
+ </term>
+ <listitem>
+ <para>
+ shift level of interest
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<function>XkbKeycodeToKeysym</function>
+returns the keysym bound to a particular group and shift level for a
+particular key on the core keyboard. If
+<parameter>kc</parameter>
+is not a legal keycode for the core keyboard, or if
+<parameter>group</parameter>
+or
+<parameter>level</parameter>
+are out of range for the specified key,
+<function>XkbKeycodeToKeysym</function>
+returns
+<symbol>NoSymbol</symbol>.
+</para>
+
+
+<para>
+To find the set of modifiers bound to a particular keysym on the core keyboard,
+use
+<function>XkbKeysymToModifiers</function>.
+</para>
+
+
+<indexterm significance="preferred" zone="XkbKeysymToModifiers"><primary><function>XkbKeysymToModifiers</function></primary></indexterm>
+<funcsynopsis id="XkbKeysymToModifiers">
+ <funcprototype>
+ <funcdef>unsigned int <function>XkbKeysymToModifiers</function></funcdef>
+<!-- (
+<parameter>dpy</parameter>,
+<parameter>ks</parameter>
+) -->
+
+ <paramdef>Display *<parameter>dpy</parameter></paramdef>
+ <paramdef>KeySym <parameter>ks</parameter></paramdef>
+ </funcprototype>
+</funcsynopsis>
+<variablelist>
+ <varlistentry>
+ <term>
+ <parameter>dpy</parameter>
+ </term>
+ <listitem>
+ <para>
+ connection to X server
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>ks</parameter>
+ </term>
+ <listitem>
+ <para>
+ keysym of interest
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<function>XkbKeysymToModifiers</function>
+finds the set of modifiers currently bound to the keysym
+<parameter>ks</parameter>
+on the core keyboard. The value returned is the mask of modifiers bound to the
+keysym
+<parameter>ks</parameter>.
+If no modifiers are bound to the keysym,
+<function>XkbKeysymToModifiers</function>
+returns zero; otherwise, it returns the inclusive OR of zero or more of the
+following:
+<symbol>ShiftMask</symbol>,
+<symbol>ControlMask</symbol>,
+<symbol>LockMask</symbol>,
+<symbol>Mod1Mask</symbol>,
+<symbol>Mod2Mask</symbol>,
+<symbol>Mod3Mask</symbol>,
+<symbol>Mod4Mask</symbol>,
+and
+<symbol>Mod5Mask</symbol>.
+</para>
+
+
+<para>
+Use
+<function>XkbLookupKeySym</function>
+to find the symbol associated with a key for a particular state.
+</para>
+
+
+<indexterm significance="preferred" zone="XkbLookupKeySym"><primary><function>XkbLookupKeySym</function></primary></indexterm>
+<funcsynopsis id="XkbLookupKeySym">
+ <funcprototype>
+ <funcdef>Bool <function>XkbLookupKeySym</function></funcdef>
+<!-- (
+<parameter>dpy</parameter>,
+<parameter>key</parameter>,
+<parameter>state</parameter>,
+<parameter>mods_rtrn</parameter>,
+<parameter>sym_rtrn</parameter>
+) -->
+
+ <paramdef>Display *<parameter>dpy</parameter></paramdef>
+ <paramdef>KeyCode <parameter>key</parameter></paramdef>
+ <paramdef>unsigned int <parameter>state</parameter></paramdef>
+ <paramdef>unsigned int *<parameter>mods_rtrn</parameter></paramdef>
+ <paramdef>KeySym *<parameter>sym_rtrn</parameter></paramdef>
+ </funcprototype>
+</funcsynopsis>
+<variablelist>
+ <varlistentry>
+ <term>
+ <parameter>dpy</parameter>
+ </term>
+ <listitem>
+ <para>
+ connection to X server
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>key</parameter>
+ </term>
+ <listitem>
+ <para>
+ key for which symbols are to be found
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>state</parameter>
+ </term>
+ <listitem>
+ <para>
+ state for which symbol should be found
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>mods_rtrn</parameter>
+ </term>
+ <listitem>
+ <para>
+ backfilled with consumed modifiers
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>sym_rtrn</parameter>
+ </term>
+ <listitem>
+ <para>
+ backfilled with symbol associated with key + state
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<function>XkbLookupKeySym</function>
+is the equivalent of the core
+<symbol>XLookupKeySym</symbol>
+function. For the core keyboard, given a keycode
+<parameter>key</parameter>
+and an Xkb state
+<parameter>state</parameter>,
+<function>XkbLookupKeySym</function>
+returns the symbol associated with the key in
+<parameter>sym_rtrn</parameter>
+and the list of modifiers that should still be applied in
+<parameter>mods_rtrn</parameter>.
+The
+<parameter>state</parameter>
+parameter is the state from a
+<symbol>KeyPress</symbol>
+or
+<symbol>KeyRelease</symbol>
+event.
+<function>XkbLookupKeySym</function>
+returns
+<symbol>True</symbol>
+if it succeeds.
+</para>
+
+
+<para>
+Use
+<function>XkbLookupKeyBinding</function>
+to find the string bound to a key by
+<function>XRebindKeysym</function>.
+<function>XkbLookupKeyBinding</function>
+is the equivalent of the core
+<function>XLookupString</function>
+function.
+</para>
+
+
+<indexterm significance="preferred" zone="XkbLookupKeyBinding"><primary><function>XkbLookupKeyBinding</function></primary></indexterm>
+<funcsynopsis id="XkbLookupKeyBinding">
+ <funcprototype>
+ <funcdef>int <function>XkbLookupKeyBinding</function></funcdef>
+<!-- (
+<parameter>dpy</parameter>,
+<parameter>sym</parameter>,
+<parameter>state</parameter>,
+<parameter>buf</parameter>,
+<parameter>nbytes</parameter>,
+<parameter>extra_rtrn</parameter>
+) -->
+
+ <paramdef>Display *<parameter>dpy</parameter></paramdef>
+ <paramdef>KeySym <parameter>sym</parameter></paramdef>
+ <paramdef>unsigned int <parameter>state</parameter></paramdef>
+ <paramdef>char *<parameter>buf</parameter></paramdef>
+ <paramdef>int <parameter>nbytes</parameter></paramdef>
+ <paramdef>int *<parameter>extra_rtrn</parameter></paramdef>
+ </funcprototype>
+</funcsynopsis>
+<variablelist>
+ <varlistentry>
+ <term>
+ <parameter>dpy</parameter>
+ </term>
+ <listitem>
+ <para>
+ connection to server
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>sym</parameter>
+ </term>
+ <listitem>
+ <para>
+ symbol to be looked up
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>state</parameter>
+ </term>
+ <listitem>
+ <para>
+ state for which string is to be looked up
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>buf</parameter>
+ </term>
+ <listitem>
+ <para>
+ buffer into which returned string is written
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>nbytes</parameter>
+ </term>
+ <listitem>
+ <para>
+ size of buffer in bytes
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>extra_rtrn</parameter>
+ </term>
+ <listitem>
+ <para>
+ backfilled with number bytes overflow
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<function>XRebindKeysym</function>
+binds an ASCII string to a specified keysym, so that the string and keysym are
+returned when the key is pressed and a specified list of modifiers are also
+being held down.
+<function>XkbLookupKeyBinding</function>
+returns in
+<parameter>buf</parameter>
+the string associated with the keysym
+<parameter>sym</parameter>
+and modifier state
+<parameter>state</parameter>.
+<parameter>buf</parameter>
+is
+<symbol>NULL</symbol>
+terminated unless there’s an overflow. If the string returned is larger than
+<parameter>nbytes</parameter>,
+a count of bytes that does not fit into the buffer is returned in extra_rtrn.
+<function>XkbTranslateKeySym</function>
+returns the number of bytes that it placed into
+<parameter>buf</parameter>.
+</para>
+
+
+<para>
+To find the string and symbol associated with a keysym for a given keyboard
+state, use
+<function>XkbTranslateKeySym</function>.
+</para>
+
+
+<indexterm significance="preferred" zone="XkbTranslateKeySym"><primary><function>XkbTranslateKeySym</function></primary></indexterm>
+<funcsynopsis id="XkbTranslateKeySym">
+ <funcprototype>
+ <funcdef>int <function>XkbTranslateKeySym</function></funcdef>
+<!-- (
+<parameter>dpy</parameter>,
+<parameter>sym_inout</parameter>,
+<parameter>mods</parameter>,
+<parameter>buf</parameter>,
+<parameter>nbytes</parameter>,
+<parameter>extra_rtrn</parameter>
+) -->
+
+ <paramdef>Display *<parameter>dpy</parameter></paramdef>
+ <paramdef>KeySym *<parameter>sym_inout</parameter></paramdef>
+ <paramdef>unsigned int <parameter>mods</parameter></paramdef>
+ <paramdef>char *<parameter>buf</parameter></paramdef>
+ <paramdef>int <parameter>nbytes</parameter></paramdef>
+ <paramdef>int *<parameter>extra_rtrn</parameter></paramdef>
+ </funcprototype>
+</funcsynopsis>
+<variablelist>
+ <varlistentry>
+ <term>
+ <parameter>dpy</parameter>
+ </term>
+ <listitem>
+ <para>
+ connection to X server
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>sym_inout</parameter>
+ </term>
+ <listitem>
+ <para>
+ symbol to be translated; result of translation
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>mods</parameter>
+ </term>
+ <listitem>
+ <para>
+ modifiers to apply to <parameter>sym_inout</parameter>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>buf</parameter>
+ </term>
+ <listitem>
+ <para>
+ buffer into which returned string is written
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>nbytes</parameter>
+ </term>
+ <listitem>
+ <para>
+ size of buffer in bytes
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>extra_rtrn</parameter>
+ </term>
+ <listitem>
+ <para>
+ number of bytes overflow
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<function>XkbTranslateKeySym</function>
+applies the transformations specified in
+<parameter>mods</parameter>
+to the symbol specified by
+<parameter>sym_inout</parameter>.
+It returns in
+<parameter>buf</parameter>
+the string, if any, associated with the keysym for the current locale. If the
+transformations in
+<parameter>mods</parameter>
+changes the keysym,
+<parameter>sym_inout</parameter>
+is updated accordingly. If the string returned is larger than
+<parameter>nbytes</parameter>,
+a count of bytes that does not fit into the buffer is returned in extra_rtrn.
+<function>XkbTranslateKeySym</function>
+returns the number of bytes it placed into
+<parameter>buf</parameter>.
+</para>
+
+
+<para>
+To update the keyboard description that is internal to the X library, use
+<function>XkbRefreshKeyboardMapping</function>.
+</para>
+
+
+<indexterm significance="preferred" zone="XkbRefreshKeyboardMapping"><primary><function>XkbRefreshKeyboardMapping</function></primary></indexterm>
+<funcsynopsis id="XkbRefreshKeyboardMapping">
+ <funcprototype>
+ <funcdef>Status <function>XkbRefreshKeyboardMapping</function></funcdef>
+<!-- (
+<parameter>event)</parameter> -->
+
+ <paramdef>XkbMapNotifyEvent *<parameter>event</parameter></paramdef>
+ </funcprototype>
+</funcsynopsis>
+<variablelist>
+ <varlistentry>
+ <term>
+ <parameter>event</parameter>
+ </term>
+ <listitem>
+ <para>
+ event initiating remapping
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<function>XkbRefreshKeyboardMapping</function>
+is the Xkb equivalent of the core
+<function>XRefreshKeyboardMapping</function>
+function. It requests that the X server send the current key mapping
+information to this client. A client usually invokes
+<function>XkbRefreshKeyboardMapping</function>
+after receiving an
+<symbol>XkbMapNotify</symbol>
+event.
+<function>XkbRefreshKeyboardMapping</function>
+returns
+<symbol>Success</symbol>
+if it succeeds and
+<errorname>BadMatch</errorname>
+if the event is not an Xkb event.
+</para>
+
+
+<para>
+The
+<symbol>XkbMapNotify</symbol>
+event can be generated when some client calls
+<function>XkbSetMap</function>,
+<function>XkbChangeMap</function>,
+<function>XkbGetKeyboardByName</function>,
+or any of the standard X library functions that change the keyboard mapping
+or modifier mapping.
+</para>
+
+
+<para>
+To translate a keycode to a key symbol and modifiers, use
+<function>XkbTranslateKeyCode</function>.
+</para>
+
+
+<indexterm significance="preferred" zone="XkbTranslateKeyCode"><primary><function>XkbTranslateKeyCode</function></primary></indexterm>
+<funcsynopsis id="XkbTranslateKeyCode">
+ <funcprototype>
+ <funcdef>Bool <function>XkbTranslateKeyCode</function></funcdef>
+<!-- (
+<parameter>xkb, key, mods, mods_rtrn, keysym_rtrn)</parameter> -->
+
+ <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef>
+ <paramdef>KeyCode <parameter>key</parameter></paramdef>
+ <paramdef>unsigned int <parameter>mods</parameter></paramdef>
+ <paramdef>unsigned int *<parameter>mods_rtrn</parameter></paramdef>
+ <paramdef>KeySym *<parameter>keysym_rtrn</parameter></paramdef>
+ </funcprototype>
+</funcsynopsis>
+<variablelist>
+ <varlistentry>
+ <term>
+ <parameter>xkb</parameter>
+ </term>
+ <listitem>
+ <para>
+ keyboard description to use for translation
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>key</parameter>
+ </term>
+ <listitem>
+ <para>
+ keycode to translate
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>mods</parameter>
+ </term>
+ <listitem>
+ <para>
+ modifiers to apply when translating <parameter>key</parameter>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>mods_rtrn</parameter>
+ </term>
+ <listitem>
+ <para>
+ backfilled with consumed modifiers
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <parameter>keysym_rtrn</parameter>
+ </term>
+ <listitem>
+ <para>
+ keysym resulting from translation
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<parameter>mods_rtrn</parameter>
+is backfilled with the modifiers consumed by the translation process.
+<parameter>mods</parameter>
+is a bitwise inclusive OR of the legal modifier masks:
+<symbol>ShiftMask</symbol>,
+<symbol>LockMask</symbol>,
+<symbol>ControlMask</symbol>,
+<symbol>Mod1Mask</symbol>,
+<symbol>Mod2Mask</symbol>,
+<symbol>Mod3Mask</symbol>,
+<symbol>Mod4Mask</symbol>,
+<symbol>Mod5Mask</symbol>.
+The
+<emphasis>AlwaysConsumeShiftAndLock</emphasis>
+library control (see <link linkend="AlwaysConsumeShiftAndLock">section 11.1.3</link>), if enabled, causes
+<function>XkbTranslateKeyCode</function>
+to consume shift and lock.
+<function>XkbTranslateKeyCode</function>
+returns
+<symbol>True</symbol>
+if the translation resulted in a keysym, and
+<symbol>False</symbol>
+if it resulted in
+<symbol>NoSymbol</symbol>.
+</para>
+</sect1>
+</chapter>
Index: create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/XKB
===================================================================
--- create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/XKB (nonexistent)
+++ create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/XKB (revision 5)
Property changes on: create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/XKB
___________________________________________________________________
Added: svn:ignore
## -0,0 +1,73 ##
+
+# install dir
+dist
+
+# Target build dirs
+.a1x-newlib
+.a2x-newlib
+.at91sam7s-newlib
+
+.build-machine
+
+.a1x-glibc
+.a2x-glibc
+.h3-glibc
+.h5-glibc
+.i586-glibc
+.i686-glibc
+.imx6-glibc
+.jz47xx-glibc
+.makefile
+.am335x-glibc
+.omap543x-glibc
+.p5600-glibc
+.power8-glibc
+.power8le-glibc
+.power9-glibc
+.power9le-glibc
+.m1000-glibc
+.riscv64-glibc
+.rk328x-glibc
+.rk33xx-glibc
+.rk339x-glibc
+.s8xx-glibc
+.s9xx-glibc
+.x86_64-glibc
+
+# Hidden files (each file)
+.makefile
+.dist
+.rootfs
+
+# src & hw requires
+.src_requires
+.src_requires_depend
+.requires
+.requires_depend
+
+# Tarballs
+*.gz
+*.bz2
+*.lz
+*.xz
+*.tgz
+*.txz
+
+# Signatures
+*.asc
+*.sig
+*.sign
+*.sha1sum
+
+# Patches
+*.patch
+
+# Descriptions
+*.dsc
+*.txt
+
+# Default linux config files
+*.defconfig
+
+# backup copies
+*~
Index: create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/i18n/localedb/localedb.xml
===================================================================
--- create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/i18n/localedb/localedb.xml (nonexistent)
+++ create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/i18n/localedb/localedb.xml (revision 5)
@@ -0,0 +1,786 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
+[
+<!ENTITY % defs SYSTEM "defs.ent"> %defs;
+]>
+
+<book id="localedb">
+
+<bookinfo>
+ <title>X Locale Database Specification</title>
+ <releaseinfo>X Version 11, Release &fullrelvers;</releaseinfo>
+ <authorgroup>
+ <author>
+ <firstname>Yoshio</firstname><surname>Horiuchi</surname>
+ <affiliation><orgname>IBM Japan</orgname></affiliation>
+ </author>
+ </authorgroup>
+ <copyright><year>1994</year><holder>IBM Corporation</holder></copyright>
+
+<legalnotice>
+<para>
+License to use, copy, modify, and distribute this software and its documentation for
+any purpose and without fee is hereby granted, provided that the above copyright notice
+appear in all copies and that both that copyright notice and this permission notice
+appear in supporting documentation, and that the name of IBM not be used in advertising
+or publicity pertaining to distribution of the software without specific, written
+prior permission.
+</para>
+<para>
+IBM DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED
+WARRANTIES OF MERCHANTABILITY, FITNESS, AND NONINFRINGEMENT OF THIRD PARTY RIGHTS,
+IN NO EVENT SHALL IBM BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES
+OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
+AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
+WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+</para>
+</legalnotice>
+
+<legalnotice>
+<para role="multiLicensing">Copyright © 1994 X Consortium</para>
+<para>
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files
+(the “Software”), to deal in the Software without restriction,
+including without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to permit
+persons to whom the Software is furnished to do so, subject to the following
+conditions:
+</para>
+
+<para>
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+</para>
+
+<para>
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
+NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+</para>
+
+<para>
+Except as contained in this notice, the name of the X Consortium shall not be
+used in advertising or otherwise to promote the sale, use or other dealings in
+this Software without prior written authorization from the X Consortium.
+</para>
+
+<para>X Window System is a trademark of The Open Group.</para>
+
+</legalnotice>
+</bookinfo>
+
+<chapter id='LocaleDB'>
+<title>LocaleDB</title>
+
+<sect1 id="General">
+<title>General</title>
+<para>
+An X Locale Database contains the subset of a user's environment that
+depends on language, in X Window System. It is made up from one or more
+categories. Each category consists of some classes and sub-classes.
+</para>
+
+<para>
+It is provided as a plain ASCII text file, so a user can change its
+contents easily. It allows a user to customize the behavior of
+internationalized portion of Xlib without changing Xlib itself.
+</para>
+
+<para>
+This document describes;
+</para>
+
+<itemizedlist>
+ <listitem>
+ <para>
+Database Format Definition
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Contents of Database in sample implementation
+<!-- .RE -->
+ </para>
+ </listitem>
+</itemizedlist>
+
+<para>
+Since it is hard to define the set of required information for all
+platforms, only the flexible database format is defined.
+The available entries in database are implementation dependent.
+</para>
+
+</sect1>
+<sect1 id="Database_Format_Definition">
+<title>Database Format Definition</title>
+<para>
+The X Locale Database contains one or more category definitions.
+This section describes the format of each category definition.
+</para>
+
+<para>
+The category definition consists of one or more class definitions.
+Each class definition has a pair of class name and class value, or
+has several subclasses which are enclosed by the left brace ({) and
+the right brace (}).
+</para>
+
+<para>
+Comments can be placed by using the number sign character (#).
+Putting the number sign character on the top of the line indicates
+that the entire line is comment. Also, putting any whitespace character
+followed by the number sign character indicates that a part of the line
+(from the number sign to the end of the line) is comment.
+A line can be continued by placing backslash (\) character as the
+last character on the line; this continuation character will be
+discarded from the input. Comment lines cannot be continued on
+a subsequent line using an escaped new line character.
+</para>
+
+<para>
+X Locale Database only accepts XPCS, the X Portable Character Set.
+The reserved symbols are; the quotation mark("), the number sign (#),
+the semicolon(;), the backslash(\), the left brace({) and
+the right brace(}).
+</para>
+
+<para>
+The format of category definition is;
+</para>
+
+<informaltable frame="none">
+ <?dbfo keep-together="auto" ?>
+ <tgroup cols='3' align='left' colsep='0' rowsep='0'>
+ <colspec colname='c1' colwidth='3.0*'/>
+ <colspec colname='c2' colwidth='1.0*'/>
+ <colspec colname='c3' colwidth='6.0*'/>
+ <tbody>
+ <row>
+ <entry>CategoryDefinition</entry>
+ <entry>::=</entry>
+ <entry>CategoryHeader CategorySpec CategoryTrailer</entry>
+ </row>
+ <row>
+ <entry>CategoryHeader</entry>
+ <entry>::=</entry>
+ <entry>CategoryName NL</entry>
+ </row>
+ <row>
+ <entry>CategorySpec</entry>
+ <entry>::=</entry>
+ <entry>{ ClassSpec }</entry>
+ </row>
+ <row>
+ <entry>CategoryTrailer</entry>
+ <entry>::=</entry>
+ <entry>"END" Delimiter CategoryName NL</entry>
+ </row>
+ <row>
+ <entry>CategoryName</entry>
+ <entry>::=</entry>
+ <entry>String</entry>
+ </row>
+ <row>
+ <entry>ClassSpec</entry>
+ <entry>::=</entry>
+ <entry>ClassName Delimiter ClassValue NL</entry>
+ </row>
+ <row>
+ <entry>ClassName</entry>
+ <entry>::=</entry>
+ <entry>String</entry>
+ </row>
+ <row>
+ <entry>ClassValue</entry>
+ <entry>::=</entry>
+ <entry>ValueList | "{" NL { ClassSpec } "}"</entry>
+ </row>
+ <row>
+ <entry>ValueList</entry>
+ <entry>::=</entry>
+ <entry>Value | Value ";" ValueList</entry>
+ </row>
+ <row>
+ <entry>Value</entry>
+ <entry>::=</entry>
+ <entry>ValuePiece | ValuePiece Value</entry>
+ </row>
+ <row>
+ <entry>ValuePiece</entry>
+ <entry>::=</entry>
+ <entry>String | QuotedString | NumericString</entry>
+ </row>
+ <row>
+ <entry>String</entry>
+ <entry>::=</entry>
+ <entry>Char { Char }</entry>
+ </row>
+ <row>
+ <entry>QuotedString</entry>
+ <entry>::=</entry>
+ <entry>""" QuotedChar { QuotedChar } """</entry>
+ </row>
+ <row>
+ <entry>NumericString</entry>
+ <entry>::=</entry>
+ <entry>"\\o" OctDigit { OctDigit }</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>|</entry>
+ <entry>"\\d" DecDigit { DecDigit }</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>|</entry>
+ <entry>"\\x" HexDigit { HexDigit }</entry>
+ </row>
+ <row>
+ <entry>Char</entry>
+ <entry>::=</entry>
+ <entry><XPCS except NL, Space or unescaped reserved symbols></entry>
+ </row>
+ <row>
+ <entry>QuotedChar</entry>
+ <entry>::=</entry>
+ <entry><XPCS except unescaped """></entry>
+ </row>
+ <row>
+ <entry>OctDigit</entry>
+ <entry>::=</entry>
+ <entry><character in the range of "0" - "7"></entry>
+ </row>
+ <row>
+ <entry>DecDigit</entry>
+ <entry>::=</entry>
+ <entry><character in the range of "0" - "9"></entry>
+ </row>
+ <row>
+ <entry>HexDigit</entry>
+ <entry>::=</entry>
+ <entry><character in the range of "0" - "9", "a" - "f", "A" - "F"></entry>
+ </row>
+ <row>
+ <entry>Delimiter</entry>
+ <entry>::=</entry>
+ <entry>Space { Space }</entry>
+ </row>
+ <row>
+ <entry>Space</entry>
+ <entry>::=</entry>
+ <entry><space> | <horizontal tab></entry>
+ </row>
+ <row>
+ <entry>NL</entry>
+ <entry>::=</entry>
+ <entry><newline></entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+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>
+The backslash, which is not the top character of the NumericString, is
+recognized as an escape character, so that the next one character is
+treated as a literal character. For example, the two-character
+sequence, ""\"""(the backslash followed by the quotation mark) is
+recognized and replaced with a quotation mark character.
+Any whitespace character, that is not the Delimiter, unquoted and
+unescaped, is ignored.
+</para>
+
+</sect1>
+<sect1 id='Contents_of_Database'>
+<title>Contents of Database</title>
+<para>
+The available categories and classes depend on implementation, because
+different platform will require different information set.
+For example, some platform have system locale but some platform don't.
+Furthermore, there might be a difference in functionality even if the
+platform has system locale.
+</para>
+
+<para>
+In current sample implementation, categories listed below are available.
+</para>
+
+<informaltable frame="none">
+ <?dbfo keep-together="always" ?>
+ <tgroup cols='1' align='left' colsep='0' rowsep='0'>
+ <colspec colname='c1' colwidth='1.0*'/>
+ <tbody>
+ <row>
+ <entry>XLC_FONTSET:XFontSet relative information</entry>
+ </row>
+ <row>
+ <entry>XLC_XLOCALE:Character classification and conversion information</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+</sect1>
+<sect1 id="XLC_FONTSET_Category">
+<title>XLC_FONTSET Category</title>
+<para>
+The XLC_FONTSET category defines the XFontSet relative information.
+It contains the CHARSET_REGISTRY-CHARSET_ENCODING name and character
+mapping side (GL, GR, etc), and is used in Output Method (OM).
+</para>
+
+<informaltable frame="topbot">
+ <?dbfo keep-together="always" ?>
+ <tgroup cols='3' align='left' colsep='0' rowsep='0'>
+ <thead>
+ <colspec colname='c1' colwidth='3.0*'/>
+ <colspec colname='c2' colwidth='1.0*'/>
+ <colspec colname='c3' colwidth='3.0*'/>
+ <row rowsep='1'>
+ <entry>class</entry>
+ <entry>super class</entry>
+ <entry>description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>fsN</entry>
+ <entry></entry>
+ <entry>Nth fontset (N=0,1,2, ...)</entry>
+ </row>
+ <row>
+ <entry>charset</entry>
+ <entry>fsN</entry>
+ <entry>list of encoding name</entry>
+ </row>
+ <row>
+ <entry>font</entry>
+ <entry>fsN</entry>
+ <entry>list of font encoding name</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<variablelist>
+ <varlistentry>
+ <term>fsN</term>
+ <listitem>
+ <para>
+Includes an encoding information for Nth charset, where N is
+the index number (0,1,2,...). If there are 4 charsets available
+in current locale, 4 fontsets, fs0, fs1, fs2 and fs3, should be
+defined.
+This class has two subclasses, 'charset' and 'font'.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>charset</term>
+ <listitem>
+ <para>
+Specifies an encoding information to be used internally in Xlib
+for this fontset. The format of value is;
+ </para>
+<informaltable frame="none">
+ <?dbfo keep-together="always" ?>
+ <tgroup cols='3' align='left' colsep='0' rowsep='0'>
+ <colspec colname='c1' colwidth='3.0*'/>
+ <colspec colname='c2' colwidth='1.0*'/>
+ <colspec colname='c3' colwidth='4.0*'/>
+ <tbody>
+ <row>
+ <entry>EncodingInfo</entry>
+ <entry>::=</entry>
+ <entry>EncodingName [ ":" EncodingSide ]</entry>
+ </row>
+ <row>
+ <entry>EncodingName</entry>
+ <entry>::=</entry>
+ <entry>CHARSET_REGISTRY-CHARSET_ENCODING</entry>
+ </row>
+ <row>
+ <entry>EncodingSide</entry>
+ <entry>::=</entry>
+ <entry>"GL" | "GR"</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+For detail definition of CHARSET_REGISTRY-CHARSET_ENCODING, refer
+to the <citetitle>X Logical Font Description Conventions</citetitle> document.
+</para>
+<literallayout>
+example:
+ ISO8859-1:GL
+</literallayout>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>font</term>
+ <listitem>
+ <para>
+Specifies a list of encoding information which is used for searching
+appropriate font for this fontset. The left most entry has highest
+priority.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+</sect1>
+<sect1 id="XLC_XLOCALE_Category">
+<title>XLC_XLOCALE Category</title>
+<para>
+The XLC_XLOCALE category defines character classification, conversion
+and other character attributes.
+</para>
+
+<informaltable frame="topbot">
+ <?dbfo keep-together="always" ?>
+ <tgroup cols='3' align='left' colsep='0' rowsep='0'>
+ <colspec colname='c1' colwidth='3.0*'/>
+ <colspec colname='c2' colwidth='1.0*'/>
+ <colspec colname='c3' colwidth='3.0*'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>class</entry>
+ <entry>super class</entry>
+ <entry>description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>encoding_name</entry>
+ <entry></entry>
+ <entry>codeset name</entry>
+ </row>
+ <row>
+ <entry>mb_cur_max</entry>
+ <entry></entry>
+ <entry>MB_CUR_MAX</entry>
+ </row>
+ <row>
+ <entry>state_depend_encoding</entry>
+ <entry></entry>
+ <entry>state dependent or not</entry>
+ </row>
+ <row>
+ <entry>wc_encoding_mask</entry>
+ <entry></entry>
+ <entry>for parsing wc string</entry>
+ </row>
+ <row>
+ <entry>wc_shift_bits</entry>
+ <entry></entry>
+ <entry>for conversion between wc and mb</entry>
+ </row>
+ <row>
+ <entry>csN</entry>
+ <entry></entry>
+ <entry>Nth charset (N=0,1,2,...)</entry>
+ </row>
+ <row>
+ <entry>side</entry>
+ <entry>csN</entry>
+ <entry>mapping side (GL, etc)</entry>
+ </row>
+ <row>
+ <entry>length</entry>
+ <entry>csN</entry>
+ <entry>length of a character</entry>
+ </row>
+ <row>
+ <entry>mb_encoding</entry>
+ <entry>csN</entry>
+ <entry>for parsing mb string</entry>
+ </row>
+ <row>
+ <entry>wc_encoding</entry>
+ <entry>csN</entry>
+ <entry>for parsing wc string</entry>
+ </row>
+ <row>
+ <entry>ct_encoding</entry>
+ <entry>csN</entry>
+ <entry>list of encoding name for ct</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<variablelist>
+ <varlistentry>
+ <term>encoding_name</term>
+ <listitem>
+ <para>
+Specifies a codeset name of current locale.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>mb_cur_max</term>
+ <listitem>
+ <para>
+Specifies a maximum allowable number of bytes in a multi-byte character.
+It is corresponding to MB_CUR_MAX of "ISO/IEC 9899:1990 C Language Standard".
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>state_depend_encoding</term>
+ <listitem>
+ <para>
+Indicates a current locale is state dependent. The value should be
+specified "True" or "False".
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>wc_encoding_mask</term>
+ <listitem>
+ <para>
+Specifies a bit-mask for parsing wide-char string. Each wide character is
+applied bit-and operation with this bit-mask, then is classified into
+the unique charset, by using 'wc_encoding'.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>wc_shift_bits</term>
+ <listitem>
+ <para>
+Specifies a number of bit to be shifted for converting from a multi-byte
+character to a wide character, and vice-versa.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>csN</term>
+ <listitem>
+ <para>
+<!-- .br -->
+Includes a character set information for Nth charset, where N is the
+index number (0,1,2,...). If there are 4 charsets available in current
+locale, cs0, cs1, cs2 and cs3 should be defined. This class has five
+subclasses, 'side', 'length', 'mb_encoding' 'wc_encoding' and 'ct_encoding'.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>side</term>
+ <listitem>
+ <para>
+Specifies a mapping side of this charset. The format of this value is;
+ </para>
+ <literallayout>
+ Side ::= EncodingSide[":Default"]
+ </literallayout>
+ <para>
+The suffix ":Default" can be specified. It indicates that a character
+belongs to the specified side is mapped to this charset in initial state.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>length</term>
+ <listitem>
+ <para>
+<!-- .br -->
+Specifies a number of bytes of a multi-byte character of this charset.
+It should not contain the length of any single-shift sequence.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>mb_encoding</term>
+ <listitem>
+ <para>
+Specifies a list of shift sequence for parsing multi-byte string.
+The format of this value is;
+ </para>
+<informaltable frame="none">
+ <?dbfo keep-together="always" ?>
+ <tgroup cols='3' align='left' colsep='0' rowsep='0'>
+ <colspec colname='c1' colwidth='3.0*'/>
+ <colspec colname='c2' colwidth='1.0*'/>
+ <colspec colname='c3' colwidth='5.0*'/>
+ <tbody>
+ <row>
+ <entry>MBEncoding</entry>
+ <entry>::=</entry>
+ <entry>ShiftType ShiftSequence</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>|</entry>
+ <entry>ShiftType ShiftSequence ";" MBEncoding</entry>
+ </row>
+ <row>
+ <entry>ShiftType</entry>
+ <entry>::=</entry>
+ <entry>"<SS>"|"<LSL>"|"<LSR>"</entry>
+ </row>
+ <row>
+ <entry>ShiftSequence</entry>
+ <entry>::=</entry>
+ <entry>SequenceValue|SequenceValue ShiftSequence</entry>
+ </row>
+ <row>
+ <entry>SequenceValue</entry>
+ <entry>::=</entry>
+ <entry>NumericString</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+ <literallayout>
+example:
+ <LSL> \x1b \x28 \x4a; <LSL> \x1b \x28 \x42
+ </literallayout>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>wc_encoding</term>
+ <listitem>
+ <para>
+Specifies an integer value for parsing wide-char string.
+It is used to determine the charset for each wide character, after
+applying bit-and operation using 'wc_encoding_mask'.
+This value should be unique in all csN classes.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>ct_encoding</term>
+ <listitem>
+ <para>
+Specifies a list of encoding information that can be used for Compound
+Text.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect1>
+
+<sect1 id="Sample_of_X_Locale_Database">
+<title>Sample of X Locale Database</title>
+<para>
+The following is sample X Locale Database file.
+</para>
+
+<literallayout class="monospaced">
+# XLocale Database Sample for ja_JP.euc
+#
+
+#
+# XLC_FONTSET category
+#
+XLC_FONTSET
+# fs0 class (7 bit ASCII)
+fs0 {
+ charset ISO8859-1:GL
+ font ISO8859-1:GL; JISX0201.1976-0:GL
+}
+# fs1 class (Kanji)
+fs1 {
+ charset JISX0208.1983-0:GL
+ font JISX0208.1983-0:GL
+}
+# fs2 class (Half Kana)
+fs2 {
+ charset JISX0201.1976-0:GR
+ font JISX0201.1976-0:GR
+}
+# fs3 class (User Defined Character)
+# fs3 {
+# charset JISX0212.1990-0:GL
+# font JISX0212.1990-0:GL
+# }
+END XLC_FONTSET
+
+#
+# XLC_XLOCALE category
+#
+XLC_XLOCALE
+
+encoding_name ja.euc
+mb_cur_max 3
+state_depend_encoding False
+
+wc_encoding_mask \x00008080
+wc_shift_bits 8
+
+# cs0 class
+cs0 {
+ side GL:Default
+ length 1
+ wc_encoding \x00000000
+ ct_encoding ISO8859-1:GL; JISX0201.1976-0:GL
+}
+# cs1 class
+cs1 {
+ side GR:Default
+ length 2
+
+ wc_encoding \x00008080
+
+ ct_encoding JISX0208.1983-0:GL; JISX0208.1983-0:GR;\
+ JISX0208.1983-1:GL; JISX0208.1983-1:GR
+}
+
+# cs2 class
+cs2 {
+ side GR
+ length 1
+ mb_encoding <SS> \x8e
+
+ wc_encoding \x00000080
+
+ ct_encoding JISX0201.1976-0:GR
+}
+
+# cs3 class
+# cs3 {
+# side GL
+# length 2
+# mb_encoding <SS> \x8f
+# #if HasWChar32
+# wc_encoding \x20000000
+# #else
+# wc_encoding \x00008000
+# #endif
+# ct_encoding JISX0212.1990-0:GL; JISX0212.1990-0:GR
+# }
+
+END XLC_XLOCALE
+</literallayout>
+</sect1>
+
+<sect1 id="Reference">
+<title>Reference</title>
+<para>
+[1] <emphasis remap='I'>ISO/IEC 9899:1990 C Language Standard</emphasis>
+</para>
+<para>
+[2] <citetitle>X Logical Font Description Conventions</citetitle>
+</para>
+
+</sect1>
+</chapter>
+</book>
Index: create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/i18n/localedb
===================================================================
--- create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/i18n/localedb (nonexistent)
+++ create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/i18n/localedb (revision 5)
Property changes on: create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/i18n/localedb
___________________________________________________________________
Added: svn:ignore
## -0,0 +1,73 ##
+
+# install dir
+dist
+
+# Target build dirs
+.a1x-newlib
+.a2x-newlib
+.at91sam7s-newlib
+
+.build-machine
+
+.a1x-glibc
+.a2x-glibc
+.h3-glibc
+.h5-glibc
+.i586-glibc
+.i686-glibc
+.imx6-glibc
+.jz47xx-glibc
+.makefile
+.am335x-glibc
+.omap543x-glibc
+.p5600-glibc
+.power8-glibc
+.power8le-glibc
+.power9-glibc
+.power9le-glibc
+.m1000-glibc
+.riscv64-glibc
+.rk328x-glibc
+.rk33xx-glibc
+.rk339x-glibc
+.s8xx-glibc
+.s9xx-glibc
+.x86_64-glibc
+
+# Hidden files (each file)
+.makefile
+.dist
+.rootfs
+
+# src & hw requires
+.src_requires
+.src_requires_depend
+.requires
+.requires_depend
+
+# Tarballs
+*.gz
+*.bz2
+*.lz
+*.xz
+*.tgz
+*.txz
+
+# Signatures
+*.asc
+*.sig
+*.sign
+*.sha1sum
+
+# Patches
+*.patch
+
+# Descriptions
+*.dsc
+*.txt
+
+# Default linux config files
+*.defconfig
+
+# backup copies
+*~
Index: create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/i18n/trans/trans.xml
===================================================================
--- create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/i18n/trans/trans.xml (nonexistent)
+++ create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/i18n/trans/trans.xml (revision 5)
@@ -0,0 +1,2002 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
+[
+<!ENTITY % defs SYSTEM "defs.ent"> %defs;
+]>
+
+<book id="trans">
+
+<bookinfo>
+ <title>The XIM Transport Specification</title>
+ <subtitle>Revision 0.1</subtitle>
+ <releaseinfo>X Version 11, Release &fullrelvers;</releaseinfo>
+ <authorgroup>
+ <author>
+ <firstname>Takashi</firstname><surname>Fujiwara</surname>
+ <affiliation><orgname>FUJITSU LIMITED</orgname></affiliation>
+ </author>
+ </authorgroup>
+ <copyright><year>1994</year><holder>FUJITSU LIMITED</holder></copyright>
+
+<abstract>
+<title>Abstract</title>
+<para>
+This specification describes the transport layer interfaces between Xlib and IM Server,
+which makes various channels usable such as X protocol or TCP/IP, DECnet and etc.
+</para>
+</abstract>
+
+<legalnotice>
+
+<para>
+Permission to use, copy, modify, and distribute this documentation for any purpose
+and without fee is hereby granted, provided that the above copyright notice and
+this permission notice appear in all copies.
+Fujitsu makes no representations about the suitability for any purpose of the
+information in this document. This documentation is provided as is
+without express or implied warranty.
+</para>
+
+<para role="multiLicensing">Copyright © 1994 X Consortium</para>
+<para>
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files
+(the “Software”), to deal in the Software without restriction,
+including without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to permit
+persons to whom the Software is furnished to do so, subject to the following
+conditions:
+</para>
+
+<para>
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+</para>
+
+<para>
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
+NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+</para>
+
+<para>
+Except as contained in this notice, the name of the X Consortium shall not be
+used in advertising or otherwise to promote the sale, use or other dealings in
+this Software without prior written authorization from the X Consortium.
+</para>
+
+<para>X Window System is a trademark of The Open Group.</para>
+
+</legalnotice>
+</bookinfo>
+
+<chapter id='X_Transport_Specification'>
+<title>X Transport Specification</title>
+
+<sect1 id="Introduction">
+<title>Introduction</title>
+<!-- .XS -->
+<!-- (SN Introduction -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The Xlib XIM implementation is layered into three functions, a protocol
+layer, an interface layer and a transport layer. The purpose of this
+layering is to make the protocol independent of transport implementation.
+Each function of these layers are:
+<!-- .RS 3 -->
+</para>
+<variablelist>
+ <varlistentry>
+ <term><emphasis>The protocol layer</emphasis></term>
+ <listitem>
+ <para>
+implements overall function of XIM and calls the interface layer
+functions when it needs to communicate to IM Server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>The interface layer</emphasis></term>
+ <listitem>
+ <para>
+separates the implementation of the transport layer from the protocol
+layer, in other words, it provides implementation independent hook for
+the transport layer functions.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis>The transport layer</emphasis></term>
+ <listitem>
+ <para>
+handles actual data communication with IM Server. It is done by a set
+of several functions named transporters.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+This specification describes the interface layer and the transport
+layer, which makes various communication channels usable such as
+X protocol or, TCP/IP, DECnet, STREAM, etc., and provides
+the information needed for adding another new transport layer.
+In addition, sample implementations for the transporter using the
+X connection is described in section 4. <!-- xref -->
+</para>
+</sect1>
+
+<sect1 id="Initialization">
+<title>Initialization</title>
+
+<sect2 id="Registering_structure_to_initialize">
+<title>Registering structure to initialize</title>
+
+<para>
+The structure typed as TransportSW contains the list of the transport
+layer the specific implementations supports.
+</para>
+
+<literallayout class="monospaced">
+typedef struct {
+ char *transport_name;
+ Bool (*config);
+} TransportSW;
+</literallayout>
+
+<informaltable frame="none">
+ <?dbfo keep-together="always" ?>
+ <tgroup cols="2" align='left' colsep='0' rowsep='0'>
+ <colspec colname="col1" colwidth='1.0*'/>
+ <colspec colname="col2" colwidth='1.0*'/>
+ <tbody>
+ <row>
+ <entry><emphasis>transport_name</emphasis></entry>
+ <entry>name of transport<footnote><para>Refer to "The Input Method Protocol: Appendix B</para></footnote></entry>
+ </row>
+ <row>
+ <entry><emphasis>config</emphasis></entry>
+ <entry>initial configuration function</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+A sample entry for the Xlib supporting transporters is shown below:
+</para>
+
+<literallayout class="monospaced">
+TransportSW _XimTransportRec[] = {
+/* char <emphasis remap='I'>*</emphasis>:
+ * transport_name, Bool <emphasis remap='I'>(*config)()</emphasis>
+ */
+ "X", _XimXConf,
+ "tcp", _XimTransConf,
+ "local", _XimTransConf,
+ "decnet", _XimTransConf,
+ "streams", _XimTransConf,
+ (char *)NULL, (Bool (*)())NULL,
+};
+</literallayout>
+
+</sect2>
+<sect2 id="Initialization_function">
+<title>Initialization function</title>
+<!-- .XS -->
+<!-- (SN Initialization function -->
+<!-- .XE -->
+<para>
+The following function will be called once when Xlib configures the
+transporter functions.
+</para>
+
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Bool <function>(*config)</function></funcdef>
+ <paramdef>XIM<parameter> im</parameter></paramdef>
+ <paramdef>char<parameter> *transport_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>im</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies XIM structure address.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>transport_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the data specific to the transporter, in IM Server address.<footnote><para>Refer to "The Input Method Protocol: Appendix B</para></footnote>
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+This function must setup the transporter function pointers.
+</para>
+
+<para>
+<!-- .LP -->
+The actual <emphasis remap='I'>config</emphasis> function will be chosen by IM Server at the
+pre-connection time, matching by the <emphasis remap='I'>transport_name</emphasis> specified
+in the <function>_XimTransportRec</function> array; The specific members of XimProto
+structure listed below must be initialized so that point they
+appropriate transporter functions.
+</para>
+
+<para>
+If the specified transporter has been configured successfully, this
+function returns True. There is no Alternative Entry for config
+function itself.
+</para>
+
+<para>
+The structure XimProto contains the following function pointers:
+</para>
+
+<literallayout class="monospaced">
+Bool (*connect)(); /* Open connection */
+Bool (*shutdown)(); /* Close connection */
+Bool (*write)(); /* Write data */
+Bool (*read)(); /* Read data */
+Bool (*flush)(); /* Flush data buffer */
+Bool (*register_dispatcher)(); /* Register asynchronous data handler */
+Bool (*call_dispatcher)(); /* Call dispatcher */
+</literallayout>
+
+<para>
+These functions are called when Xlib needs to communicate the
+IM Server. These functions must process the appropriate procedure
+described below.
+</para>
+
+</sect2>
+</sect1>
+<sect1 id='The_interfacetransport_layer_functions'>
+<title>The interface/transport layer functions</title>
+<para>
+Following functions are used for the transport interface.
+</para>
+
+<table frame="all" id="transport_layer_functions_2">
+ <?dbfo keep-together="always" ?>
+ <title>The Transport Layer Functions</title>
+ <tgroup cols="3" align='left' colsep='1' rowsep='1'>
+ <colspec colname="col1" colwidth="3.0*"/>
+ <colspec colname="col2" colwidth="3.0*"/>
+ <colspec colname="col3" colwidth='1.0*'/>
+ <thead>
+ <row>
+ <entry align='center'>Alternate Entry (Interface Layer)</entry>
+ <entry align='center'>XimProto member (Transport Layer)</entry>
+ <entry align='center'>Section</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>_XimConnect</entry>
+ <entry>connect</entry>
+ <entry>3.1</entry>
+ </row>
+ <row>
+ <entry>_XimShutdown</entry>
+ <entry>shutdown</entry>
+ <entry>3.2</entry>
+ </row>
+ <row>
+ <entry>_XimWrite</entry>
+ <entry>write</entry>
+ <entry>3.3</entry>
+ </row>
+ <row>
+ <entry>_XimRead</entry>
+ <entry>read</entry>
+ <entry>3.4</entry>
+ </row>
+ <row>
+ <entry>_XimFlush</entry>
+ <entry>flush</entry>
+ <entry>3.5</entry>
+ </row>
+ <row>
+ <entry>_XimRegisterDispatcher</entry>
+ <entry>register_dispatcher</entry>
+ <entry>3.6</entry>
+ </row>
+ <row>
+ <entry>_XimCallDispatcher</entry>
+ <entry>call_dispatcher</entry>
+ <entry>3.7</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</table>
+
+<para>
+The Protocol layer calls the above functions using the Alternative
+Entry in the left column. The transport implementation defines
+XimProto member function in the right column. The Alternative Entry is
+provided so as to make easier to implement the Protocol Layer.
+</para>
+
+<sect2 id="Opening_connection">
+<title>Opening connection</title>
+<para>
+<!-- .LP -->
+When <function>XOpenIM</function> is called, the following function is called to connect
+with the IM Server.
+</para>
+
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Bool <function>(*connect)</function></funcdef>
+ <paramdef>XIM<parameter> im</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>im</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies XIM structure address.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+This function must establishes the connection to the IM Server. If the
+connection is established successfully, this function returns True.
+The Alternative Entry for this function is:
+</para>
+
+<funcsynopsis id='_XimConnect'>
+<funcprototype>
+ <funcdef>Bool <function> _XimConnect</function></funcdef>
+ <paramdef>XIM<parameter> im</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>im</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies XIM structure address.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect2>
+
+<sect2 id="Closing_connection">
+<title>Closing connection</title>
+<!-- .XS -->
+<!-- (SN Closing connection -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+When <function>XCloseIM</function> is called, the following function is called to
+disconnect the connection with the IM Server. The Alternative Entry
+for this function is:
+</para>
+
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Bool <function> (*shutdown)</function></funcdef>
+ <paramdef>XIM<parameter> im</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>im</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies XIM structure address.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+This function must close connection with the IM Server. If the
+connection is closed successfully, this function returns True. The
+Alternative Entry for this function is:
+</para>
+
+<funcsynopsis id='_XimShutdown'>
+<funcprototype>
+ <funcdef>Bool <function>_XimShutdown</function></funcdef>
+ <paramdef>XIM<parameter> im</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>im</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies XIM structure address.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+</sect2>
+
+<sect2 id="Writing_data">
+<title>Writing data</title>
+<para>
+The following function is called, when Xlib needs to write data to the
+IM Server.
+</para>
+
+<funcsynopsis id='_XimWrite'>
+<funcprototype>
+ <funcdef>Bool <function> _XimWrite</function></funcdef>
+ <paramdef>XIM<parameter> im</parameter></paramdef>
+ <paramdef>INT16<parameter> len</parameter></paramdef>
+ <paramdef>XPointer<parameter> data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>im</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies XIM structure address.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>len</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the length of writing data.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the writing data.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+This function writes the <emphasis remap='I'>data</emphasis> to the IM Server, regardless
+of the contents. The number of bytes is passed to <emphasis remap='I'>len</emphasis>. The
+writing data is passed to <emphasis remap='I'>data</emphasis>. If data is sent successfully,
+the function returns True. Refer to "The Input Method Protocol" for
+the contents of the writing data. The Alternative Entry for this
+function is:
+</para>
+
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Bool <function>_XimWrite</function></funcdef>
+ <paramdef>XIM<parameter> im</parameter></paramdef>
+ <paramdef>INT16<parameter> len</parameter></paramdef>
+ <paramdef>XPointer<parameter> data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>im</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies XIM structure address.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>len</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the length of writing data.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the writing data.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+</sect2>
+<sect2 id="Reading_data">
+<title>Reading data</title>
+<para>
+The following function is called when Xlib waits for response from IM
+server synchronously.
+</para>
+
+<funcsynopsis id='_XimRead'>
+<funcprototype>
+ <funcdef>Bool <function> _XimRead</function></funcdef>
+ <paramdef>XIM<parameter> im</parameter></paramdef>
+ <paramdef>XPointer<parameter> read_buf</parameter></paramdef>
+ <paramdef>int<parameter> buf_len</parameter></paramdef>
+ <paramdef>int<parameter> *ret_len</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>im</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies XIM structure address.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>read_buf</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the buffer to store data.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>buf_len</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the size of the <emphasis remap='I'>buffer</emphasis>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ret_len</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the length of stored data.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+This function stores the read data in <emphasis remap='I'>read_buf</emphasis>, which size is
+specified as <emphasis remap='I'>buf_len</emphasis>. The size of data is set to <emphasis remap='I'>ret_len</emphasis>.
+This function return True, if the data is read normally or reading
+data is completed.
+</para>
+<para>
+The Alternative Entry for this function is:
+</para>
+
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Bool <function> _XimRead</function></funcdef>
+ <paramdef>XIM<parameter> im</parameter></paramdef>
+ <paramdef>INT16<parameter> *ret_len</parameter></paramdef>
+ <paramdef>XPointer<parameter> buf</parameter></paramdef>
+ <paramdef>int<parameter> buf_len</parameter></paramdef>
+ <paramdef>Bool<parameter> (*predicate)()</parameter></paramdef>
+ <paramdef>XPointer<parameter> predicate_arg</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>im</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies XIM structure address.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ret_len</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the size of the <emphasis remap='I'>data</emphasis> buffer.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>buf</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the buffer to store data.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>buf_len</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the length of <emphasis remap='I'>buffer</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>predicate</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the predicate for the XIM data.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>predicate_arg</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the predicate specific data.
+<!-- .sp 6p -->
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The predicate procedure indicates whether the <emphasis remap='I'>data</emphasis> is for the
+XIM or not. <emphasis remap='I'>len</emphasis>
+This function stores the read data in <emphasis remap='I'>buf</emphasis>, which size
+is specified as <emphasis remap='I'>buf_len</emphasis>. The size of data is set to
+<emphasis remap='I'>ret_len</emphasis>. If <emphasis remap='I'>preedicate()</emphasis>
+returns True, this function returns True. If not, it calls the registered callback function.
+</para>
+
+<para>
+The procedure and its arguments are:
+</para>
+
+
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void <function>(*predicate)</function></funcdef>
+ <paramdef>XIM<parameter> im</parameter></paramdef>
+ <paramdef>INT16<parameter> len</parameter></paramdef>
+ <paramdef>XPointer<parameter> data</parameter></paramdef>
+ <paramdef>XPointer<parameter> predicate_arg</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>im</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies XIM structure address.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>len</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the size of the <emphasis remap='I'>data</emphasis> buffer.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the buffer to store data.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>predicate_arg</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the predicate specific data.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+</sect2>
+<sect2 id="Flushing_buffer">
+<title>Flushing buffer</title>
+<para>
+The following function is called when Xlib needs to flush the data.
+</para>
+
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void <function>(*flush)</function></funcdef>
+ <paramdef>XIM<parameter> im</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>im</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies XIM structure address.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+This function must flush the data stored in internal buffer on the
+transport layer. If data transfer is completed, the function returns
+True. The Alternative Entry for this function is:
+</para>
+
+<funcsynopsis id='_XimFlush'>
+<funcprototype>
+ <funcdef>void <function> _XimFlush</function></funcdef>
+ <paramdef>XIM<parameter> im</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>im</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies XIM structure address.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+</sect2>
+<sect2 id="Registering_asynchronous_data_handler">
+<title>Registering asynchronous data handler</title>
+<para>
+Xlib needs to handle asynchronous response from IM Server. This is
+because some of the XIM data occur asynchronously to X events.
+</para>
+
+<para>
+Those data will be handled in the <emphasis remap='I'>Filter</emphasis>,
+and the <emphasis remap='I'>Filter</emphasis>
+will call asynchronous data handler in the protocol layer. Then it
+calls dispatchers in the transport layer. The dispatchers are
+implemented by the protocol layer. This function must store the
+information and prepare for later call of the dispatchers using
+<xref linkend='_XimCallDispatcher' xrefstyle='select: title'/>.
+</para>
+
+<para>
+When multiple dispatchers are registered, they will be called
+sequentially in order of registration, on arrival of asynchronous
+data. The register_dispatcher is declared as following:
+</para>
+
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Bool <function>(*register_dispatcher)</function></funcdef>
+ <paramdef>XIM<parameter> im</parameter></paramdef>
+ <paramdef>Bool<parameter> (*dispatcher)()</parameter></paramdef>
+ <paramdef>XPointer<parameter> call_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>im</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies XIM structure address.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>dispatcher</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the dispatcher function to register.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>call_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a parameter for the <emphasis remap='I'>dispatcher</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The dispatcher is a function of the following type:
+</para>
+
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Bool <function>(*dispatcher)</function></funcdef>
+ <paramdef>XIM<parameter> im</parameter></paramdef>
+ <paramdef>INT16<parameter> len</parameter></paramdef>
+ <paramdef>XPointer<parameter> data</parameter></paramdef>
+ <paramdef>XPointer<parameter> call_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>im</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies XIM structure address.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>len</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the size of the <emphasis remap='I'>data</emphasis> buffer.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the buffer to store data.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>call_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a parameter passed to the register_dispatcher.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The dispatcher is provided by the protocol layer. They are called once
+for every asynchronous data, in order of registration. If the data is
+used, it must return True. otherwise, it must return False.
+</para>
+
+<para>
+If the dispatcher function returns True, the Transport Layer assume
+that the data has been processed by the upper layer. The Alternative
+Entry for this function is:
+</para>
+
+<funcsynopsis id='_XimRegisterDispatcher'>
+<funcprototype>
+ <funcdef>Bool <function> _XimRegisterDispatcher</function></funcdef>
+ <paramdef>XIM<parameter> im</parameter></paramdef>
+ <paramdef>Bool<parameter> (*dispatcher)()</parameter></paramdef>
+ <paramdef>XPointer<parameter> call_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>im</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies XIM structure address.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>dispatcher</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the dispatcher function to register.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>call_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a parameter for the <emphasis remap='I'>dispatcher</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+</sect2>
+<sect2 id="Calling_dispatcher">
+<title>Calling dispatcher</title>
+<para>
+The following function is used to call the registered dispatcher
+function, when the asynchronous response from IM Server has arrived.
+</para>
+
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Bool <function>(*call_dispatcher)</function></funcdef>
+ <paramdef>XIM<parameter> im</parameter></paramdef>
+ <paramdef>INT16<parameter> len</parameter></paramdef>
+ <paramdef>XPointer<parameter> data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>im</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies XIM structure address.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>len</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the size of <emphasis remap='I'>data</emphasis> buffer.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the buffer to store data.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The call_dispatcher must call the dispatcher function, in order of
+their registration. <emphasis remap='I'>len</emphasis> and <emphasis remap='I'>data</emphasis> are the data passed to
+register_dispatcher.
+</para>
+
+<para>
+The return values are checked at each invocation, and if it finds
+True, it immediately return with true for its return value.
+</para>
+
+<para>
+It is depend on the upper layer whether the read data is XIM
+Protocol packet unit or not.
+The Alternative Entry for this function is:
+</para>
+
+<funcsynopsis id='_XimCallDispatcher'>
+<funcprototype>
+ <funcdef>Bool <function> _XimCallDispatcher</function></funcdef>
+ <paramdef>XIM<parameter> im</parameter></paramdef>
+ <paramdef>INT16<parameter> len</parameter></paramdef>
+ <paramdef>XPointer<parameter> call_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+</sect2>
+</sect1>
+<sect1 id="Sample_implementations_for_the_Transport_Layer">
+<title>Sample implementations for the Transport Layer</title>
+<para>
+Sample implementations for the transporter using the X connection is
+described here.
+</para>
+
+<sect2 id="X_Transport">
+<title>X Transport</title>
+<para>
+At the beginning of the X Transport connection for the XIM transport
+mechanism, two different windows must be created either in an Xlib XIM
+or in an IM Server, with which the Xlib and the IM Server exchange the
+XIM transports by using the ClientMessage events and Window Properties.
+In the following, the window created by the Xlib is referred as the
+"client communication window", and on the other hand, the window created
+by the IM Server is referred as the "IMS communication window".
+</para>
+
+<sect3 id="Connection">
+<title>Connection</title>
+<para>
+In order to establish a connection, a communication window is created.
+A ClientMessage in the following event's format is sent to the owner
+window of XIM_SERVER selection, which the IM Server has created.
+</para>
+
+<para>
+<!-- .LP -->
+Refer to "The Input Method Protocol" for the XIM_SERVER atom.
+</para>
+
+<table frame="topbot" id="transport_layer_functions">
+ <?dbfo keep-together="always" ?>
+ <title>The ClientMessage sent to the IMS window.</title>
+ <tgroup cols="3" align='left' colsep='0' rowsep='0'>
+ <colspec colname="col1" colwidth='1.0*'/>
+ <colspec colname="col2" colwidth='1.0*' colsep='1'/>
+ <colspec colname="col3" colwidth="3.5*"/>
+ <spanspec namest="col1" nameend="col2" spanname="span-horiz"/>
+ <thead>
+ <row rowsep='1'>
+ <entry spanname="span-horiz" colsep='1'>Structure Member</entry>
+ <entry>Contents</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>int</entry>
+ <entry>type</entry>
+ <entry>ClientMessage</entry>
+ </row>
+ <row>
+ <entry>u_long</entry>
+ <entry>serial</entry>
+ <entry>Set by the X Window System</entry>
+ </row>
+ <row>
+ <entry>Bool</entry>
+ <entry>send_event</entry>
+ <entry>Set by the X Window System</entry>
+ </row>
+ <row>
+ <entry>Display</entry>
+ <entry>*display</entry>
+ <entry>The display to which connects</entry>
+ </row>
+ <row>
+ <entry>Window</entry>
+ <entry>window</entry>
+ <entry>IMS Window ID</entry>
+ </row>
+ <row>
+ <entry>Atom</entry>
+ <entry>message_type</entry>
+ <entry>XInternAtom(display, "_XIM_CONNECT", false)</entry>
+ </row>
+ <row>
+ <entry>int</entry>
+ <entry>format</entry>
+ <entry>32</entry>
+ </row>
+ <row>
+ <entry>long</entry>
+ <entry>data.1[0]</entry>
+ <entry>client communication window ID</entry>
+ </row>
+ <row>
+ <entry>long</entry>
+ <entry>data.1[1]</entry>
+ <entry>client-major-transport-version(*1)</entry>
+ </row>
+ <row>
+ <entry>long</entry>
+ <entry>data.1[2]</entry>
+ <entry>client-major-transport-version(*1)</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</table>
+
+<para>
+In order to establish the connection (to notify the IM Server communication
+window), the IM Server sends a ClientMessage in the following event's
+format to the client communication window.
+</para>
+
+<table frame="topbot" id="clientmessage_sent_by_im_server">
+ <?dbfo keep-together="always" ?>
+ <title>The ClientMessage sent by IM Server.</title>
+ <tgroup cols="3" colsep='0' rowsep='0'>
+ <colspec colname="col1" colwidth='1.0*'/>
+ <colspec colname="col2" colwidth='1.0*' colsep="1"/>
+ <colspec colname="col3" colwidth="3.5*"/>
+ <spanspec namest="col1" nameend="col2" spanname="span-horiz"/>
+ <thead>
+ <row rowsep='1'>
+ <entry spanname="span-horiz" colsep='1'>Structure Member</entry>
+ <entry>Contents</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>int</entry>
+ <entry>type</entry>
+ <entry>ClientMessage</entry>
+ </row>
+ <row>
+ <entry>u_long</entry>
+ <entry>serial</entry>
+ <entry>Set by the X Window System</entry>
+ </row>
+ <row>
+ <entry>Bool</entry>
+ <entry>send_event</entry>
+ <entry>Set by the X Window System</entry>
+ </row>
+ <row>
+ <entry>Display</entry>
+ <entry>*display</entry>
+ <entry>The display to which connects</entry>
+ </row>
+ <row>
+ <entry>Window</entry>
+ <entry>window</entry>
+ <entry>IMS Window ID</entry>
+ </row>
+ <row>
+ <entry>Atom</entry>
+ <entry>message_type</entry>
+ <entry>XInternAtom(display, "_XIM_CONNECT", false)</entry>
+ </row>
+ <row>
+ <entry>int</entry>
+ <entry>format</entry>
+ <entry>32</entry>
+ </row>
+ <row>
+ <entry>long</entry>
+ <entry>data.1[0]</entry>
+ <entry>client communication window ID</entry>
+ </row>
+ <row>
+ <entry>long</entry>
+ <entry>data.1[1]</entry>
+ <entry>client-major-transport-version(*1)</entry>
+ </row>
+ <row>
+ <entry>long</entry>
+ <entry>data.1[2]</entry>
+ <entry>client-major-transport-version(*1)</entry>
+ </row>
+ <row>
+ <entry>long</entry>
+ <entry>data.1[3]</entry>
+ <entry>dividing size between ClientMessage and Property(*2)</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</table>
+
+<para>
+(*1) major/minor-transport-version
+</para>
+
+<para>
+The read/write method is decided by the combination of
+major/minor-transport-version, as follows:
+</para>
+
+<table frame="all" id="readwrite_method_and_the_majorminor_transport_version">
+ <?dbfo keep-together="always" ?>
+ <title>The read/write method and the major/minor-transport-version</title>
+ <tgroup cols="3" colsep='1' rowsep='1'>
+ <colspec colname="col1" colwidth='1.0*'/>
+ <colspec colname="col2" colwidth='1.0*'/>
+ <colspec colname="col3" colwidth="3.0*"/>
+ <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="center"/>
+ <thead>
+ <row>
+ <entry spanname="span-horiz">Transport-version</entry>
+ <entry>read/write</entry>
+ </row>
+ <row>
+ <entry>major</entry>
+ <entry>minor</entry>
+ <entry></entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry morerows="2">0</entry>
+ <entry>0</entry>
+ <entry>only-CM & Property-with-CM</entry>
+ </row>
+ <row>
+ <entry>1</entry>
+ <entry>only-CM & multi-CM</entry>
+ </row>
+ <row>
+ <entry>2</entry>
+ <entry>only-CM & multi-CM & Property-with-CM</entry>
+ </row>
+ <row>
+ <entry>1</entry>
+ <entry>0</entry>
+ <entry>PropertyNotify</entry>
+ </row>
+ <row>
+ <entry morerows="1">2</entry>
+ <entry>0</entry>
+ <entry>only-CM & PropertyNotify</entry>
+ </row>
+ <row>
+ <entry>1</entry>
+ <entry>only-CM & multi-CM & PropertyNotify</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</table>
+
+<literallayout class="monospaced">
+only-CM : data is sent via a ClientMessage
+multi-CM : data is sent via multiple ClientMessages
+Property-with-CM : data is written in Property, and its Atom
+ is send via ClientMessage
+PropertyNotify : data is written in Property, and its Atom
+ is send via PropertyNotify
+
+</literallayout>
+
+
+<para>
+The method to decide major/minor-transport-version is as follows:
+</para>
+
+<itemizedlist>
+ <listitem>
+ <para>
+The client sends 0 as major/minor-transport-version to the IM Server.
+The client must support all methods in Table 4-3. <!-- xref -->
+The client may send another number as major/minor-transport-version to
+use other method than the above in the future.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The IM Server sends its major/minor-transport-version number to
+the client. The client sends data using the method specified by the
+IM Server.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If major/minor-transport-version number is not available, it is regarded
+as 0.
+ </para>
+ </listitem>
+</itemizedlist>
+
+<para>
+(*2) dividing size between ClientMessage and Property
+</para>
+
+<para>
+If data is sent via both of multi-CM and Property, specify the dividing
+size between ClientMessage and Property. The data, which is smaller than
+this size, is sent via multi-CM (or only-CM), and the data, which is
+lager than this size, is sent via Property.
+</para>
+
+</sect3>
+
+<sect3 id='readwrite'>
+<title>read/write</title>
+<para>
+The data is transferred via either ClientMessage or Window Property in
+the X Window System.
+</para>
+
+<sect4 id="Format_for_the_data_from_the_Client_to_the_IM_Server">
+<title>Format for the data from the Client to the IM Server</title>
+<para>
+<emphasis role="bold">ClientMessage</emphasis>
+</para>
+
+<para>
+If data is sent via ClientMessage event, the format is as follows:
+</para>
+
+<table frame="topbot" id="clientmessage_events_format_first_or_middle">
+ <?dbfo keep-together="always" ?>
+ <title>The ClientMessage event's format (first or middle)</title>
+ <tgroup cols="3" align='left' colsep='0' rowsep='0'>
+ <colspec colname="col1" colwidth='1.0*'/>
+ <colspec colname="col2" colwidth='1.0*' colsep="1"/>
+ <colspec colname="col3" colwidth="3.5*"/>
+ <spanspec namest="col1" nameend="col2" spanname="span-horiz"/>
+ <thead>
+ <row rowsep='1'>
+ <entry spanname="span-horiz" colsep='1'>Structure Member</entry>
+ <entry>Contents</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>int</entry>
+ <entry>type</entry>
+ <entry>ClientMessage</entry>
+ </row>
+ <row>
+ <entry>u_long</entry>
+ <entry>serial</entry>
+ <entry>Set by the X Window System</entry>
+ </row>
+ <row>
+ <entry>Bool</entry>
+ <entry>send_event</entry>
+ <entry>Set by the X Window System</entry>
+ </row>
+ <row>
+ <entry>Display</entry>
+ <entry>*display</entry>
+ <entry>The display to which connects</entry>
+ </row>
+ <row>
+ <entry>Window</entry>
+ <entry>window</entry>
+ <entry>IMS Window ID</entry>
+ </row>
+ <row>
+ <entry>Atom</entry>
+ <entry>message_type</entry>
+ <entry>XInternAtom(display, "_XIM_MOREDATA", False)</entry>
+ </row>
+ <row>
+ <entry>int</entry>
+ <entry>format</entry>
+ <entry>8</entry>
+ </row>
+ <row>
+ <entry>char</entry>
+ <entry>data.b[20]</entry>
+ <entry>(read/write DATA : 20 byte)</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</table>
+
+
+
+<table frame="topbot" id="clientmessage_events_format_only_or_last">
+ <?dbfo keep-together="always" ?>
+ <title>The ClientMessage event's format (only or last)</title>
+ <tgroup cols="3" align='left' colsep='0' rowsep='0'>
+ <colspec colname="col1" colwidth='1.0*'/>
+ <colspec colname="col2" colwidth='1.0*' colsep="1"/>
+ <colspec colname="col3" colwidth="3.5*"/>
+ <spanspec namest="col1" nameend="col2" spanname="span-horiz"/>
+ <thead>
+ <row rowsep='1'>
+ <entry spanname="span-horiz" colsep='1'>Structure Member</entry>
+ <entry>Contents</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>int</entry>
+ <entry>type</entry>
+ <entry>ClientMessage</entry>
+ </row>
+ <row>
+ <entry>u_long</entry>
+ <entry>serial</entry>
+ <entry>Set by the X Window System</entry>
+ </row>
+ <row>
+ <entry>Bool</entry>
+ <entry>send_event</entry>
+ <entry>Set by the X Window System</entry>
+ </row>
+ <row>
+ <entry>Display</entry>
+ <entry>*display</entry>
+ <entry>The display to which connects</entry>
+ </row>
+ <row>
+ <entry>Window</entry>
+ <entry>window</entry>
+ <entry>IMS Window ID</entry>
+ </row>
+ <row>
+ <entry>Atom</entry>
+ <entry>message_type</entry>
+ <entry>XInternAtom(display, "_XIM_PROTOCOL", False)</entry>
+ </row>
+ <row>
+ <entry>int</entry>
+ <entry>format</entry>
+ <entry>8</entry>
+ </row>
+ <row>
+ <entry>char</entry>
+ <entry>data.b[20]</entry>
+ <entry>(read/write DATA : MAX 20 byte)
+<footnote><para>If the data is smaller
+than 20 bytes, all data other than available data must be 0.
+</para></footnote>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+</table>
+
+<para>
+<emphasis role="bold">Property</emphasis>
+</para>
+
+<para>
+In the case of large data, data will be sent via the Window Property
+for the efficiency. There are the following two methods to notify
+Property, and transport-version is decided which method is used.
+</para>
+
+<itemizedlist>
+ <listitem>
+ <para>
+The XChangeProperty function is used to store data in the client
+communication window, and Atom of the stored data is notified to the
+IM Server via ClientMessage event.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The XChangeProperty function is used to store data in the client
+communication window, and Atom of the stored data is notified to the
+IM Server via PropertyNotify event.
+ </para>
+ </listitem>
+</itemizedlist>
+
+<para>
+The arguments of the XChangeProperty are as follows:
+</para>
+
+
+<table frame="topbot" id="xchangeproperty_events_format">
+ <?dbfo keep-together="always" ?>
+ <title>The XChangeProperty event's format</title>
+ <tgroup cols="3" align='left' colsep='0' rowsep='0'>
+ <colspec colname="col1" colwidth='1.0*'/>
+ <colspec colname="col2" colwidth='1.0*' colsep="1"/>
+ <colspec colname="col3" colwidth="3.5*"/>
+ <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="left"/>
+ <thead>
+ <row rowsep='1'>
+ <entry spanname="span-horiz" colsep='1'>Argument</entry>
+ <entry>Contents</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>Display</entry>
+ <entry>*display</entry>
+ <entry>The display to which connects</entry>
+ </row>
+ <row>
+ <entry>Window</entry>
+ <entry>window</entry>
+ <entry>IMS communication window ID</entry>
+ </row>
+ <row>
+ <entry>Atom</entry>
+ <entry>property</entry>
+ <entry>read/write property Atom (*1)</entry>
+ </row>
+ <row>
+ <entry>int</entry>
+ <entry>format</entry>
+ <entry>8</entry>
+ </row>
+ <row>
+ <entry>int</entry>
+ <entry>mode</entry>
+ <entry>PropModeAppend</entry>
+ </row>
+ <row>
+ <entry>u_char</entry>
+ <entry>*data</entry>
+ <entry>read/write DATA</entry>
+ </row>
+ <row>
+ <entry>int</entry>
+ <entry>nelements</entry>
+ <entry>length of DATA</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</table>
+
+<para>
+(*1) The read/write property ATOM allocates the following strings by
+<function>XInternAtom</function>.
+"_clientXXX"
+</para>
+
+<para>
+The client changes the property with the mode of PropModeAppend and
+the IM Server will read it with the delete mode i.e. (delete = True).
+</para>
+
+<para>
+If Atom is notified via ClientMessage event, the format of the ClientMessage
+is as follows:
+</para>
+
+<table frame="topbot" id="clientmessage_events_format_to_send_atom_of_property">
+ <?dbfo keep-together="always" ?>
+ <title>The ClientMessage event's format to send Atom of property</title>
+ <tgroup cols="3" align='left' colsep='0' rowsep='0'>
+ <colspec colname="col1" colwidth='1.0*'/>
+ <colspec colname="col2" colwidth='1.0*' colsep="1"/>
+ <colspec colname="col3" colwidth="3.5*"/>
+ <spanspec namest="col1" nameend="col2" spanname="span-horiz"/>
+ <thead>
+ <row rowsep='1'>
+ <entry spanname="span-horiz" colsep='1'>Structure Member</entry>
+ <entry>Contents</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>int</entry>
+ <entry>type</entry>
+ <entry>ClientMessage</entry>
+ </row>
+ <row>
+ <entry>u_long</entry>
+ <entry>serial</entry>
+ <entry>Set by the X Window System</entry>
+ </row>
+ <row>
+ <entry>Bool</entry>
+ <entry>send_event</entry>
+ <entry>Set by the X Window System</entry>
+ </row>
+ <row>
+ <entry>Display</entry>
+ <entry>*display</entry>
+ <entry>The display to which connects</entry>
+ </row>
+ <row>
+ <entry>Window</entry>
+ <entry>window</entry>
+ <entry>IMS Window ID</entry>
+ </row>
+ <row>
+ <entry>Atom</entry>
+ <entry>message_type</entry>
+ <entry>XInternAtom(display, "_XIM_PROTOCOL", False)</entry>
+ </row>
+ <row>
+ <entry>int</entry>
+ <entry>format</entry>
+ <entry>8</entry>
+ </row>
+ <row>
+ <entry>long</entry>
+ <entry>data.1[0]</entry>
+ <entry>length of read/write property Atom</entry>
+ </row>
+ <row>
+ <entry>long</entry>
+ <entry>data.1[1]</entry>
+ <entry>read/write property Atom</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</table>
+</sect4>
+
+<sect4 id="Format_for_the_data_from_the_IM_Server_to_the_Client">
+<title>Format for the data from the IM Server to the Client</title>
+<para>
+<emphasis role="bold">ClientMessage</emphasis>
+</para>
+
+<para>
+The format of the ClientMessage is as follows:
+</para>
+
+<table frame="topbot" id="clientmessage_events_format_first_or_middle_2">
+ <?dbfo keep-together="always" ?>
+ <title>The ClientMessage event's format (first or middle)</title>
+ <tgroup cols="3" align='left' colsep='0' rowsep='0'>
+ <colspec colname="col1" colwidth='1.0*'/>
+ <colspec colname="col2" colwidth='1.0*' colsep="1"/>
+ <colspec colname="col3" colwidth="3.5*"/>
+ <spanspec namest="col1" nameend="col2" spanname="span-horiz"/>
+ <thead>
+ <row rowsep='1'>
+ <entry spanname="span-horiz" colsep='1'>Structure Member</entry>
+ <entry>Contents</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>int</entry>
+ <entry>type</entry>
+ <entry>ClientMessage</entry>
+ </row>
+ <row>
+ <entry>u_long</entry>
+ <entry>serial</entry>
+ <entry>Set by the X Window System</entry>
+ </row>
+ <row>
+ <entry>Bool</entry>
+ <entry>send_event</entry>
+ <entry>Set by the X Window System</entry>
+ </row>
+ <row>
+ <entry>Display</entry>
+ <entry>*display</entry>
+ <entry>The display to which connects</entry>
+ </row>
+ <row>
+ <entry>Window</entry>
+ <entry>window</entry>
+ <entry>IMS Window ID</entry>
+ </row>
+ <row>
+ <entry>Atom</entry>
+ <entry>message_type</entry>
+ <entry>XInternAtom(display, "_XIM_MOREDATA", False)</entry>
+ </row>
+ <row>
+ <entry>int</entry>
+ <entry>format</entry>
+ <entry>8</entry>
+ </row>
+ <row>
+ <entry>char</entry>
+ <entry>data.b[20]</entry>
+ <entry>(read/write DATA : 20 byte)</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</table>
+
+
+
+
+
+<table frame="topbot" id="clientmessage_events_format_only_or_last_2">
+ <?dbfo keep-together="always" ?>
+ <title>The ClientMessage event's format (only or last)</title>
+ <tgroup cols="3" align='left' colsep='0' rowsep='0'>
+ <colspec colname="col1" colwidth='1.0*'/>
+ <colspec colname="col2" colwidth='1.0*' colsep="1"/>
+ <colspec colname="col3" colwidth="3.5*"/>
+ <spanspec namest="col1" nameend="col2" spanname="span-horiz"/>
+ <thead>
+ <row rowsep='1'>
+ <entry spanname="span-horiz" colsep='1'>Structure Member</entry>
+ <entry>Contents</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>int</entry>
+ <entry>type</entry>
+ <entry>ClientMessage</entry>
+ </row>
+ <row>
+ <entry>u_long</entry>
+ <entry>serial</entry>
+ <entry>Set by the X Window System</entry>
+ </row>
+ <row>
+ <entry>Bool</entry>
+ <entry>send_event</entry>
+ <entry>Set by the X Window System</entry>
+ </row>
+ <row>
+ <entry>Display</entry>
+ <entry>*display</entry>
+ <entry>The display to which connects</entry>
+ </row>
+ <row>
+ <entry>Window</entry>
+ <entry>window</entry>
+ <entry>IMS Window ID</entry>
+ </row>
+ <row>
+ <entry>Atom</entry>
+ <entry>message_type</entry>
+ <entry>XInternAtom(display, "_XIM_PROTOCOL", False)</entry>
+ </row>
+ <row>
+ <entry>int</entry>
+ <entry>format</entry>
+ <entry>8</entry>
+ </row>
+ <row>
+ <entry>char</entry>
+ <entry>data.b[20]</entry>
+ <entry>(read/write DATA : MAX 20 byte) (*1)</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</table>
+
+<para>
+(*1) If the data size is smaller than 20 bytes, all data other than available
+data must be 0.
+</para>
+
+<para>
+<emphasis role="bold">Property</emphasis>
+</para>
+
+<para>
+In the case of large data, data will be sent via the Window Property
+for the efficiency. There are the following two methods to notify
+Property, and transport-version is decided which method is used.
+</para>
+
+<itemizedlist>
+ <listitem>
+ <para>
+The XChangeProperty function is used to store data in the IMS
+communication window, and Atom of the property is sent via the
+ClientMessage event.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The XChangeProperty function is used to store data in the IMS
+communication window, and Atom of the property is sent via
+PropertyNotify event.
+ </para>
+ </listitem>
+</itemizedlist>
+
+<para>
+The arguments of the XChangeProperty are as follows:
+</para>
+
+<table frame="topbot" id="xchangeproperty_events_format_b">
+ <?dbfo keep-together="always" ?>
+ <title>The XChangeProperty event's format</title>
+ <tgroup cols="3" align='left' colsep='0' rowsep='0'>
+ <colspec colname="col1" colwidth='1.0*'/>
+ <colspec colname="col2" colwidth='1.0*' colsep="1"/>
+ <colspec colname="col3" colwidth="3.5*"/>
+ <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="left"/>
+ <thead>
+ <row rowsep='1'>
+ <entry spanname="span-horiz" colsep='1'>Argument</entry>
+ <entry>Contents</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>Display</entry>
+ <entry>*display</entry>
+ <entry>The display to which connects</entry>
+ </row>
+ <row>
+ <entry>Window</entry>
+ <entry>window</entry>
+ <entry>IMS communication window ID</entry>
+ </row>
+ <row>
+ <entry>Atom</entry>
+ <entry>property</entry>
+ <entry>read/write property Atom (*1)</entry>
+ </row>
+ <row>
+ <entry>int</entry>
+ <entry>format</entry>
+ <entry>8</entry>
+ </row>
+ <row>
+ <entry>int</entry>
+ <entry>mode</entry>
+ <entry>PropModeAppend</entry>
+ </row>
+ <row>
+ <entry>u_char</entry>
+ <entry>*data</entry>
+ <entry>read/write DATA</entry>
+ </row>
+ <row>
+ <entry>int</entry>
+ <entry>nelements</entry>
+ <entry>length of DATA</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</table>
+
+<para>
+(*1) The read/write property ATOM allocates some strings, which are not
+allocated by the client, by <function>XInternAtom</function>.
+</para>
+
+<para>
+The IM Server changes the property with the mode of PropModeAppend and
+the client reads it with the delete mode, i.e. (delete = True).
+</para>
+
+<para>
+If Atom is notified via ClientMessage event, the format of the ClientMessage
+is as follows:
+</para>
+
+<table frame="topbot" id="clientmessage_events_format_to_send_atom_of_property_2">
+ <?dbfo keep-together="always" ?>
+ <title>The ClientMessage event's format to send Atom of property</title>
+ <tgroup cols="3" align='left' colsep='0' rowsep='0'>
+ <colspec colname="col1" colwidth='1.0*'/>
+ <colspec colname="col2" colwidth='1.0*' colsep="1"/>
+ <colspec colname="col3" colwidth="3.5*"/>
+ <spanspec namest="col1" nameend="col2" spanname="span-horiz"/>
+ <thead>
+ <row rowsep='1'>
+ <entry spanname="span-horiz" colsep='1'>Structure Member</entry>
+ <entry>Contents</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>int</entry>
+ <entry>type</entry>
+ <entry>ClientMessage</entry>
+ </row>
+ <row>
+ <entry>u_long</entry>
+ <entry>serial</entry>
+ <entry>Set by the X Window System</entry>
+ </row>
+ <row>
+ <entry>Bool</entry>
+ <entry>send_event</entry>
+ <entry>Set by the X Window System</entry>
+ </row>
+ <row>
+ <entry>Display</entry>
+ <entry>*display</entry>
+ <entry>The display to which connects</entry>
+ </row>
+ <row>
+ <entry>Window</entry>
+ <entry>window</entry>
+ <entry>IMS Window ID</entry>
+ </row>
+ <row>
+ <entry>Atom</entry>
+ <entry>message_type</entry>
+ <entry>XInternAtom(display, "_XIM_PROTOCOL", False)</entry>
+ </row>
+ <row>
+ <entry>int</entry>
+ <entry>format</entry>
+ <entry>8</entry>
+ </row>
+ <row>
+ <entry>long</entry>
+ <entry>data.1[0]</entry>
+ <entry>length of read/write property Atom</entry>
+ </row>
+ <row>
+ <entry>long</entry>
+ <entry>data.1[1]</entry>
+ <entry>read/write property Atom</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</table>
+
+</sect4>
+</sect3>
+<sect3 id="Closing_Connection">
+<title>Closing Connection</title>
+
+<para>
+If the client disconnect with the IM Server, shutdown function should
+free the communication window properties and etc..
+</para>
+
+</sect3>
+</sect2>
+</sect1>
+
+<sect1 id="References">
+<title>References</title>
+<para>
+[1] Masahiko Narita and Hideki Hiura, <emphasis remap='I'>"The Input Method Protocol"</emphasis>
+</para>
+</sect1>
+
+</chapter>
+</book>
Index: create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/i18n/trans
===================================================================
--- create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/i18n/trans (nonexistent)
+++ create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/i18n/trans (revision 5)
Property changes on: create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/i18n/trans
___________________________________________________________________
Added: svn:ignore
## -0,0 +1,73 ##
+
+# install dir
+dist
+
+# Target build dirs
+.a1x-newlib
+.a2x-newlib
+.at91sam7s-newlib
+
+.build-machine
+
+.a1x-glibc
+.a2x-glibc
+.h3-glibc
+.h5-glibc
+.i586-glibc
+.i686-glibc
+.imx6-glibc
+.jz47xx-glibc
+.makefile
+.am335x-glibc
+.omap543x-glibc
+.p5600-glibc
+.power8-glibc
+.power8le-glibc
+.power9-glibc
+.power9le-glibc
+.m1000-glibc
+.riscv64-glibc
+.rk328x-glibc
+.rk33xx-glibc
+.rk339x-glibc
+.s8xx-glibc
+.s9xx-glibc
+.x86_64-glibc
+
+# Hidden files (each file)
+.makefile
+.dist
+.rootfs
+
+# src & hw requires
+.src_requires
+.src_requires_depend
+.requires
+.requires_depend
+
+# Tarballs
+*.gz
+*.bz2
+*.lz
+*.xz
+*.tgz
+*.txz
+
+# Signatures
+*.asc
+*.sig
+*.sign
+*.sha1sum
+
+# Patches
+*.patch
+
+# Descriptions
+*.dsc
+*.txt
+
+# Default linux config files
+*.defconfig
+
+# backup copies
+*~
Index: create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/i18n
===================================================================
--- create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/i18n (nonexistent)
+++ create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/i18n (revision 5)
Property changes on: create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/i18n
___________________________________________________________________
Added: svn:ignore
## -0,0 +1,73 ##
+
+# install dir
+dist
+
+# Target build dirs
+.a1x-newlib
+.a2x-newlib
+.at91sam7s-newlib
+
+.build-machine
+
+.a1x-glibc
+.a2x-glibc
+.h3-glibc
+.h5-glibc
+.i586-glibc
+.i686-glibc
+.imx6-glibc
+.jz47xx-glibc
+.makefile
+.am335x-glibc
+.omap543x-glibc
+.p5600-glibc
+.power8-glibc
+.power8le-glibc
+.power9-glibc
+.power9le-glibc
+.m1000-glibc
+.riscv64-glibc
+.rk328x-glibc
+.rk33xx-glibc
+.rk339x-glibc
+.s8xx-glibc
+.s9xx-glibc
+.x86_64-glibc
+
+# Hidden files (each file)
+.makefile
+.dist
+.rootfs
+
+# src & hw requires
+.src_requires
+.src_requires_depend
+.requires
+.requires_depend
+
+# Tarballs
+*.gz
+*.bz2
+*.lz
+*.xz
+*.tgz
+*.txz
+
+# Signatures
+*.asc
+*.sig
+*.sign
+*.sha1sum
+
+# Patches
+*.patch
+
+# Descriptions
+*.dsc
+*.txt
+
+# Default linux config files
+*.defconfig
+
+# backup copies
+*~
Index: create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/libX11/AppC.xml
===================================================================
--- create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/libX11/AppC.xml (nonexistent)
+++ create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/libX11/AppC.xml (revision 5)
@@ -0,0 +1,3340 @@
+<?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
+<filename class="headerfile"><X11/Xlibint.h></filename>.
+</para>
+<sect1 id="Basic_Protocol_Support_Routines">
+<title>Basic Protocol Support Routines</title>
+<para>
+The basic protocol requests for extensions are
+<xref linkend='XQueryExtension' xrefstyle='select: title'/>
+and
+<xref linkend='XListExtensions' xrefstyle='select: title'/>.
+</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
+<xref linkend='XQueryExtension' xrefstyle='select: title'/>
+function determines if the named extension is present.
+If the extension is not present,
+<xref linkend='XQueryExtension' xrefstyle='select: title'/>
+returns
+<symbol>False</symbol>;
+otherwise, it returns
+<symbol>True</symbol>.
+If the extension is present,
+<xref linkend='XQueryExtension' xrefstyle='select: title'/>
+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,
+<xref linkend='XQueryExtension' xrefstyle='select: title'/>
+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,
+<xref linkend='XQueryExtension' xrefstyle='select: title'/>
+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.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XListExtensions' xrefstyle='select: title'/>
+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.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XFreeExtensionList' xrefstyle='select: title'/>
+function frees the memory allocated by
+<xref linkend='XListExtensions' xrefstyle='select: title'/>.
+</para>
+</sect1>
+<sect1 id="Hooking_into_Xlib">
+<title>Hooking into Xlib</title>
+<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
+<xref linkend='XInitExtension' xrefstyle='select: title'/>
+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
+<xref linkend='XInitExtension' xrefstyle='select: title'/>
+and is defined in
+<filename class="headerfile"><X11/Xlib.h></filename>:
+</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>
+<!-- .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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XInitExtension' xrefstyle='select: title'/>
+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,
+<xref linkend='XInitExtension' xrefstyle='select: title'/>
+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>
+<!-- .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>
+<!-- .LP -->
+<!-- .eM -->
+For local Xlib extensions, the
+<xref linkend='XAddExtension' xrefstyle='select: title'/>
+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.)
+</para>
+<sect2 id="Hooks_into_the_Library">
+<title>Hooks into the Library</title>
+<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.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XESetCloseDisplay' xrefstyle='select: title'/>
+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>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XESetCreateGC' xrefstyle='select: title'/>
+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
+<xref linkend='XESetCopyGC' xrefstyle='select: title'/>
+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
+<xref linkend='XESetFreeGC' xrefstyle='select: title'/>
+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>
+<!-- .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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XESetCreateFont' xrefstyle='select: title'/>
+function defines a procedure to be called whenever
+<xref linkend='XLoadQueryFont' xrefstyle='select: title'/>
+and
+<xref linkend='XQueryFont' xrefstyle='select: title'/>
+are called.
+It returns any previously defined procedure, usually NULL.
+</para>
+<para>
+<!-- .LP -->
+When
+<xref linkend='XLoadQueryFont' xrefstyle='select: title'/>
+or
+<xref linkend='XQueryFont' xrefstyle='select: title'/>
+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>
+<!-- .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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XESetFreeFont' xrefstyle='select: title'/>
+function defines a procedure to be called whenever
+<xref linkend='XFreeFont' xrefstyle='select: title'/>
+is called.
+It returns any previously defined procedure, usually NULL.
+</para>
+<para>
+<!-- .LP -->
+When
+<xref linkend='XFreeFont' xrefstyle='select: title'/>
+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
+<xref linkend='XESetWireToEvent' xrefstyle='select: title'/>
+and
+<xref linkend='XESetEventToWire' xrefstyle='select: title'/>
+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.
+</para>
+<!-- .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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XESetWireToEvent' xrefstyle='select: title'/>
+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.
+<xref linkend='XESetWireToEvent' xrefstyle='select: title'/>
+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
+<xref linkend='_XSetLastRequestRead' xrefstyle='select: title'/>
+with the event and use the return value.
+</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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='_XSetLastRequestRead' xrefstyle='select: title'/>
+function computes and returns a complete serial number from the partial
+serial number in the event.
+<!-- .sp -->
+</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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XESetEventToWire' xrefstyle='select: title'/>
+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.
+<xref linkend='XESetEventToWire' xrefstyle='select: title'/>
+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.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XESetWireToError' xrefstyle='select: title'/>
+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.
+<xref linkend='XESetWireToError' xrefstyle='select: title'/>
+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>.
+</para>
+<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>
+<!-- .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
+<xref linkend='_XReply' xrefstyle='select: title'/>,
+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
+<xref linkend='_XReply' xrefstyle='select: title'/>
+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 <link linkend="Using_the_Default_Error_Handlers">section 11.8.2</link>.)
+If your procedure returns nonzero,
+the error is suppressed, and
+<xref linkend='_XReply' xrefstyle='select: title'/>
+returns the value of ret_code.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XGetErrorText' xrefstyle='select: title'/>
+function returns a string to the user for an error.
+<xref linkend='XESetErrorString' xrefstyle='select: title'/>
+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.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XESetPrintErrorValues' xrefstyle='select: title'/>
+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
+<xref linkend='XESetWireToError' xrefstyle='select: title'/>.
+The underlying type of the fp argument is system dependent;
+on a <acronym>POSIX</acronym>-compliant system, fp should be cast to type FILE*.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The procedure set by the
+<xref linkend='XESetFlushGC' xrefstyle='select: title'/>
+function has the same interface as the procedure set by the
+<xref linkend='XESetCopyGC' xrefstyle='select: title'/>
+function, but is called when a GC cache needs to be updated in the server.
+</para>
+<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>
+<!-- .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.
+</para>
+</sect2>
+<sect2 id="Hooks_onto_Xlib_Data_Structures">
+<title>Hooks onto Xlib Data Structures</title>
+<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
+<filename class="headerfile"><X11/Xlib.h></filename>
+</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>
+<!-- .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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XEHeadOfExtensionList' xrefstyle='select: title'/>
+function returns a pointer to the list of extension structures attached
+to the specified object.
+In concert with
+<xref linkend='XAddToExtensionList' xrefstyle='select: title'/>,
+<xref linkend='XEHeadOfExtensionList' xrefstyle='select: title'/>
+allows an extension to attach arbitrary data to any of the structures
+of types contained in
+<structname>XEDataObject</structname>.
+</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>
+<!-- .LP -->
+<!-- .eM -->
+The structure argument is a pointer to one of the data structures
+enumerated above.
+You must initialize ext_data->number with the extension number
+before calling this function.
+</para>
+<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
+<xref linkend='XInitExtension' xrefstyle='select: title'/>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XFindOnExtensionList' xrefstyle='select: title'/>
+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
+<xref linkend='XAllocID' xrefstyle='select: title'/>
+macro, which allocates and returns a resource ID, is defined in
+<filename class="headerfile"><X11/Xlib.h></filename>.
+</para>
+<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>
+<!-- .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
+<xref linkend='XAllocIDs' xrefstyle='select: title'/>
+macro allocates and returns an array of resource ID.
+</para>
+<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>
+<!-- .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
+<xref linkend='XAllocIDs' xrefstyle='select: title'/>
+when requesting multiple resource IDs. This call might generate
+protocol requests.
+</para>
+</sect2>
+</sect1>
+<sect1 id="GC_Caching">
+<title>GC Caching</title>
+<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
+<xref linkend='FlushGC' xrefstyle='select: title'/>
+macro checks the dirty bits in the library's GC structure and calls
+<xref linkend='_XFlushGCCache' xrefstyle='select: title'/>
+if any elements have changed.
+The
+<xref linkend='FlushGC' xrefstyle='select: title'/>
+macro is defined as follows:
+</para>
+<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>
+<!-- .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
+<xref linkend='_XFlushGCCache' xrefstyle='select: title'/>
+procedure
+to force the cache to be flushed.
+The
+<xref linkend='_XFlushGCCache' xrefstyle='select: title'/>
+procedure
+is defined as follows:
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+</sect1>
+<sect1 id="Graphics_Batching">
+<title>Graphics Batching</title>
+<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
+<xref linkend='XDrawPoint' xrefstyle='select: title'/>
+stub.
+(Writing extension stubs is discussed in the next section.)
+</para>
+<!-- .sM -->
+<!-- .nf -->
+<programlisting>
+#include <X11/Xlibint.h>
+
+/* 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->last_req;
+ /* if same as previous request, with same drawable, batch requests */
+ if (
+ (req->reqType == X_PolyPoint)
+ && (req->drawable == d)
+ && (req->gc == gc->gid)
+ && (req->coordMode == CoordModeOrigin)
+ && ((dpy->bufptr + sizeof (xPoint)) <= dpy->bufmax)
+ && (((char *)dpy->bufptr - (char *)req) < size) ) {
+ point = (xPoint *) dpy->bufptr;
+ req->length += sizeof (xPoint) >> 2;
+ dpy->bufptr += sizeof (xPoint);
+ }
+
+ else {
+ GetReqExtra(PolyPoint, 4, req); /* 1 point = 4 bytes */
+ req->drawable = d;
+ req->gc = gc->gid;
+ req->coordMode = CoordModeOrigin;
+ point = (xPoint *) (req + 1);
+ }
+ point->x = x;
+ point->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
+<filename class="headerfile"><X11/Xlibint.h></filename>
+of EPERBATCH on the number of requests batched.
+Most of the performance benefit occurs in the first few merged requests.
+Note that
+<xref linkend='FlushGC' xrefstyle='select: title'/>
+is called <emphasis remap='I'>before</emphasis> picking up the value of last_req,
+because it may modify this field.
+</para>
+</sect1>
+<sect1 id="Writing_Extension_Stubs">
+<title>Writing Extension Stubs</title>
+<para>
+<!-- .LP -->
+All X requests always contain the length of the request,
+expressed as a 16-bit quantity of 32 bit words.
+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->max_request_size contains the maximum length as
+defined by the server implementation.
+For further information,
+see <citetitle>X Window System Protocol</citetitle>.
+</para>
+<sect2 id="Requests_Replies_and_Xproto.h">
+<title>Requests, Replies, and Xproto.h</title>
+<para>
+<!-- .LP -->
+The
+<filename class="headerfile"><X11/Xproto.h></filename>
+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
+<filename class="headerfile"><X11/Xproto.h></filename>
+for your extension and need to include it in your stub procedure.
+Each stub procedure also must include
+<filename class="headerfile"><X11/Xlibint.h></filename>.
+</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
+<filename class="headerfile"><X11/Xlibint.h></filename>,
+takes advantage of this naming scheme.
+</para>
+<para>
+<!-- .LP -->
+For each X request,
+there is a definition in
+<filename class="headerfile"><X11/Xproto.h></filename>
+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.
+</para>
+</sect2>
+<sect2 id="Request_Format">
+<title>Request Format</title>
+<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 -->
+Most protocol requests have a corresponding structure typedef in
+<filename class="headerfile"><X11/Xproto.h></filename>,
+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; /* 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
+<filename class="headerfile"><X11/Xproto.h></filename>.
+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; /* 2 (= total # of bytes in request, divided by 4) */
+ CARD32 id; /* 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
+<filename class="headerfile"><X11/Xproto.h></filename>,
+which contains only a reqType and a length (and a pad byte).
+</para>
+<para>
+<!-- .LP -->
+If the protocol request requires a reply,
+then
+<filename class="headerfile"><X11/Xproto.h></filename>
+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; /* # of requests sent so far */
+ CARD32 length; /* # 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.
+<filename class="headerfile"><X11/Xproto.h></filename>
+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).
+</para>
+</sect2>
+<sect2 id="Starting_to_Write_a_Stub_Procedure">
+<title>Starting to Write a Stub Procedure</title>
+<para>
+<!-- .LP -->
+An Xlib stub procedure should start like this:
+</para>
+<para>
+<!-- .LP -->
+<!-- .R -->
+<programlisting>
+#include "<X11/Xlibint.h>
+
+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>
+</para>
+</sect2>
+<sect2 id="Locking_Data_Structures">
+<title>Locking Data Structures</title>
+<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>
+<!-- .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>
+<!-- .LP -->
+<!-- .eM -->
+</sect2>
+<sect2 id="Sending_the_Protocol_Request_and_Arguments">
+<title>Sending the Protocol Request and Arguments</title>
+<para>
+<!-- .LP -->
+After the variable declarations,
+a stub procedure should call one of four macros defined in
+<filename class="headerfile"><X11/Xlibint.h></filename>:
+<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
+<filename class="headerfile"><X11/Xproto.h></filename>
+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->arg1 = arg1;
+req->arg2 = arg2;
+...
+</programlisting>
+A few stub procedures (such as
+<xref linkend='XCreateGC' xrefstyle='select: title'/>
+and
+<xref linkend='XCreatePixmap' xrefstyle='select: title'/>)
+return a resource ID to the caller but pass a resource ID as an argument
+to the protocol request.
+Such procedures use the macro
+<xref linkend='XAllocID' xrefstyle='select: title'/>
+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->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
+<xref linkend='XMoveWindow' xrefstyle='select: title'/>
+and
+<xref linkend='XSetBackground' xrefstyle='select: title'/>)
+are special cases of more general functions like
+<xref linkend='XMoveResizeWindow' xrefstyle='select: title'/>
+and
+<xref linkend='XChangeGC' xrefstyle='select: title'/>.
+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. Note that it is possible
+for req to be set to NULL as a defensive measure if the requested length
+exceeds the Xlib's buffer size (normally 16K).
+</para>
+</sect2>
+<sect2 id="Variable_Length_Arguments">
+<title>Variable Length Arguments</title>
+<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->length += (nbytes+3)>>2;
+</programlisting>
+To transmit variable-length data, use the
+<xref linkend='Data' xrefstyle='select: title'/>
+macros.
+If the data fits into the output buffer,
+then this macro copies it to the buffer.
+If it does not fit, however,
+the
+<xref linkend='Data' xrefstyle='select: title'/>
+macro calls
+<function>_XSend</function>,
+which transmits first the contents of the buffer and then your data.
+The
+<xref linkend='Data' xrefstyle='select: title'/>
+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 role='macro'>
+ <funcdef><function>Data</function></funcdef>
+ <paramdef><parameter>display</parameter></paramdef>
+ <paramdef>(char *) <parameter>data</parameter></paramdef>
+ <paramdef><parameter>nbytes</parameter></paramdef>
+</funcprototype>
+<funcprototype role='macro'>
+ <funcdef><function>Data16</function></funcdef>
+ <paramdef><parameter>display</parameter></paramdef>
+ <paramdef>(short *) <parameter>data</parameter></paramdef>
+ <paramdef><parameter>nbytes</parameter></paramdef>
+</funcprototype>
+<funcprototype role='macro'>
+ <funcdef><function>Data32</function></funcdef>
+ <paramdef><parameter>display</parameter></paramdef>
+ <paramdef>(long *) <parameter>data</parameter></paramdef>
+ <paramdef><parameter>nbytes</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
+<xref linkend='Data' xrefstyle='select: title'/>
+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
+<xref linkend='_XReply' xrefstyle='select: title'/>),
+it is faster.
+</para>
+</sect2>
+<sect2 id="Replies">
+<title>Replies</title>
+<para>
+<!-- .LP -->
+If the protocol request has a reply,
+then call
+<xref linkend='_XReply' xrefstyle='select: title'/>
+after you have finished dealing with
+all the fixed-length and variable-length arguments.
+<xref linkend='_XReply' xrefstyle='select: title'/>
+flushes the output buffer and waits for an
+<structname>xReply</structname>
+packet to arrive.
+If any events arrive in the meantime,
+<xref linkend='_XReply' xrefstyle='select: title'/>
+places them in the queue for later use.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='_XReply' xrefstyle='select: title'/>
+function waits for a reply packet and copies its contents into the
+specified rep.
+<xref linkend='_XReply' xrefstyle='select: title'/>
+handles error and event packets that occur before the reply is received.
+<xref linkend='_XReply' xrefstyle='select: title'/>
+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
+<xref linkend='_XReply' xrefstyle='select: title'/>
+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 -->
+<xref linkend='_XReply' xrefstyle='select: title'/>
+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 *)&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
+<xref linkend='_XRead' xrefstyle='select: title'/>
+function to read the variable-length data.
+</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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='_XRead' xrefstyle='select: title'/>
+function reads the specified number of bytes into data_return.
+</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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='_XRead16' xrefstyle='select: title'/>
+function reads the specified number of bytes,
+unpacking them as 16-bit quantities,
+into the specified array as shorts.
+</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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='_XRead32' xrefstyle='select: title'/>
+function reads the specified number of bytes,
+unpacking them as 32-bit quantities,
+into the specified array as longs.
+</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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='_XRead16Pad' xrefstyle='select: title'/>
+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,
+<xref linkend='_XRead16Pad' xrefstyle='select: title'/>
+reads and discards up to two additional pad bytes.
+</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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='_XReadPad' xrefstyle='select: title'/>
+function reads the specified number of bytes into data_return.
+If the number of bytes is not a multiple of four,
+<xref linkend='_XReadPad' xrefstyle='select: title'/>
+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.
+</para>
+</sect2>
+<sect2 id="Synchronous_Calling">
+<title>Synchronous Calling</title>
+<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.
+</para>
+</sect2>
+<sect2 id="Allocating_and_Deallocating_Memory">
+<title>Allocating and Deallocating Memory</title>
+<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:
+</para>
+<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>unsigned 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'>nbytes</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of bytes required.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<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
+<xref linkend='Data' xrefstyle='select: title'/>
+families of macros,
+after any use of
+<xref linkend='_XReply' xrefstyle='select: title'/>,
+or after any use of the
+<function>_XSend</function>
+or
+<xref linkend='_XRead' xrefstyle='select: title'/>
+families of functions.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+The following function returns a scratch buffer for use across
+critical sections:
+</para>
+<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>unsigned 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'>nbytes</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of bytes required.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<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:
+</para>
+<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>unsigned 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'>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>
+<!-- .LP -->
+<!-- .eM -->
+You must pass back the same pointer and size that were returned by
+<xref linkend='_XAllocTemp' xrefstyle='select: title'/>.
+</para>
+</sect2>
+<sect2 id="Portability_Considerations">
+<title>Portability Considerations</title>
+<para>
+<!-- .LP -->
+Many machine architectures
+do not correctly or efficiently 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,
+but it is recommended to zero it to avoid inadvertent data leakage
+and improve compressability.
+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 has always assumed 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.
+Unfortunately, this assumption remains on machines where a <type>long</type>
+can hold 64-bits, and many functions and structures require unnecessarily
+large fields to avoid breaking compatibility with existing code. Special
+care must be taken with arrays of values that are transmitted in the
+protocol as CARD32 or INT32 but have to be converted to arrays of 64-bit
+<type>long</type> when passed to or from client applications.
+</para>
+<para>
+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.
+</para>
+</sect2>
+<sect2 id="Deriving_the_Correct_Extension_Opcode">
+<title>Deriving the Correct Extension Opcode</title>
+<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
+<filename class="headerfile"><stdio.h></filename>
+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
+<xref linkend='XInitExtension' xrefstyle='select: title'/>;
+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>
+</sect2>
+</sect1>
+</appendix>
Index: create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/libX11/CH01.xml
===================================================================
--- create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/libX11/CH01.xml (nonexistent)
+++ create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/libX11/CH01.xml (revision 5)
@@ -0,0 +1,846 @@
+<?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="Introduction_to_Xlib"><title>Introduction to Xlib</title>
+
+ <para>
+The X Window System is a network-transparent window system that was
+designed at MIT. X display servers run on computers with either
+monochrome or color bitmap display hardware. The server distributes
+user input to and accepts output requests from various client programs
+located either on the same machine or elsewhere in the network. Xlib
+is a C subroutine library that application programs (clients) use to
+interface with the window system by means of a stream connection.
+Although a client usually runs on the same machine as the X server
+it is talking to, this need not be the case.
+ </para>
+ <para>
+<citetitle>Xlib − C Language X Interface</citetitle> is a reference
+guide to the low-level C language interface to the X Window System
+protocol. It is neither a tutorial nor a user’s guide to programming
+the X Window System. Rather, it provides a detailed description of
+each function in the library as well as a discussion of the related
+background information. <citetitle>Xlib − C Language X Interface</citetitle>
+assumes a basic understanding of a graphics window system and of the C
+programming language. Other higher-level abstractions (for example,
+those provided by the toolkits for X) are built on top of the Xlib
+library. For further information about these higher-level libraries,
+see the appropriate toolkit documentation.
+The <citetitle>X Window System Protocol</citetitle> provides the
+definitive word on the behavior of X.
+Although additional information appears here, the protocol document is
+the ruling document.
+ </para>
+ <para>
+To provide an introduction to X programming, this chapter discusses:
+
+ <itemizedlist>
+ <listitem><para><link linkend="Overview_of_the_X_Window_System">Overview of the X Window System</link></para></listitem>
+ <listitem><para><link linkend="Errors">Errors</link></para></listitem>
+ <listitem><para><link linkend="Standard_Header_Files">Standard header files</link></para></listitem>
+ <listitem><para><link linkend="Generic_Values_and_Types">Generic values and types</link></para></listitem>
+ <listitem><para><link linkend="Naming_and_Argument_Conventions_within_Xlib">Naming and argument conventions within Xlib</link></para></listitem>
+ <listitem><para><link linkend="Programming_Considerations">Programming considerations</link></para></listitem>
+ <listitem><para><link linkend="Character_Sets_and_Encodings">Character sets and encodings</link></para></listitem>
+ <listitem><para><link linkend="Formatting_Conventions">Formatting conventions</link></para></listitem>
+ </itemizedlist>
+ </para>
+
+ <sect1 id="Overview_of_the_X_Window_System">
+ <title>Overview of the X Window System</title>
+ <para>
+Some of the terms used in this book are unique to X,
+and other terms that are common to other window systems
+have different meanings in X. You may find it helpful to refer to
+<link linkend="glossary">the glossary</link>,
+which is located at the end of the book.
+ </para>
+ <para>
+The X Window System supports one or more screens containing
+overlapping windows or subwindows.
+<indexterm><primary>Screen</primary></indexterm>
+A <firstterm>screen</firstterm> is a physical monitor and hardware
+that can be color, grayscale, or monochrome.
+There can be multiple screens for each display or workstation.
+A single X server can provide display services for any number of screens.
+A set of screens for a single user with one keyboard and one pointer
+(usually a mouse) is called a <firstterm>display</firstterm>.
+ </para>
+ <para>
+All the windows in an X server are arranged in strict hierarchies.
+At the top of each hierarchy is a <firstterm>root window</firstterm>,
+which covers each of the display screens.
+Each root window is partially or completely covered by child windows.
+All windows, except for root windows, have parents.
+There is usually at least one window for each application program.
+<indexterm><primary>Child window</primary></indexterm>
+<indexterm><primary>Parent Window</primary></indexterm>
+Child windows may in turn have their own children.
+In this way,
+an application program can create an arbitrarily deep tree
+on each screen.
+X provides graphics, text, and raster operations for windows.
+ </para>
+ <para>
+A child window can be larger than its parent.
+That is, part or all of
+the child window can extend beyond the boundaries of the parent,
+but all output to a window is clipped by its parent.
+<indexterm><primary>Stacking order</primary></indexterm>
+If several children of a window have overlapping locations,
+one of the children is considered to be on top of or raised over the
+others, thus obscuring them.
+Output to areas covered by other windows is suppressed by the window
+system unless the window has backing store.
+If a window is obscured by a second window,
+the second window obscures only those ancestors of the second window
+that are also ancestors of the first window.
+ </para>
+ <para>
+<indexterm significance="preferred"><primary>Window</primary></indexterm>
+A window has a border zero or more pixels in width, which can
+be any pattern (pixmap) or solid color you like.
+A window usually but not always has a background pattern,
+which will be repainted by the window system when uncovered.
+Child windows obscure their parents,
+and graphic operations in the parent window usually
+are clipped by the children.
+ </para>
+ <para>
+Each window and pixmap has its own coordinate system.
+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.
+For a window,
+the origin is inside the border at the inside, upper-left corner.
+ </para>
+ <para>
+X does not guarantee to preserve the contents of windows.
+When part or all of a window is hidden and then brought back onto the screen,
+its contents may be lost.
+The server then sends the client program an
+<systemitem class="event">Expose</systemitem>
+event to notify it that part or all of the window needs to be repainted.
+Programs must be prepared to regenerate the contents of windows on demand.
+ </para>
+ <para>
+<indexterm><primary>Pixmap</primary></indexterm>
+<indexterm><primary>Drawable</primary></indexterm>
+<indexterm><primary>Tile</primary></indexterm>
+<indexterm><primary>Bitmap</primary></indexterm>
+X also provides off-screen storage of graphics objects,
+called <firstterm linkend="glossary:Pixmap">pixmaps</firstterm>.
+Single plane (depth 1) pixmaps are sometimes referred to as
+<firstterm>bitmaps</firstterm>.
+Pixmaps can be used in most graphics functions interchangeably with
+windows and are used in various graphics operations to define patterns or tiles.
+Windows and pixmaps together are referred to as drawables.
+ </para>
+ <para>
+Most of the functions in Xlib just add requests to an output buffer.
+These requests later execute asynchronously on the X server.
+Functions that return values of information stored in
+the server do not return (that is, they block)
+until an explicit reply is received or an error occurs.
+You can provide an error handler,
+which will be called when the error is reported.
+ </para>
+ <para>
+<indexterm><primary>XSync</primary></indexterm>
+If a client does not want a request to execute asynchronously,
+it can follow the request with a call to
+<xref linkend='XSync' xrefstyle='select: title'/>,
+which blocks until all previously buffered
+asynchronous events have been sent and acted on.
+As an important side effect,
+the output buffer in Xlib is always flushed by a call to any function
+that returns a value from the server or waits for input.
+ </para>
+ <para>
+<indexterm><primary>Resource IDs</primary></indexterm>
+<indexterm><primary>Resource IDs</primary><secondary>Window</secondary></indexterm>
+<indexterm><primary>Resource IDs</primary><secondary>Font</secondary></indexterm>
+<indexterm><primary>Resource IDs</primary><secondary>Pixmap</secondary></indexterm>
+<indexterm><primary>Resource IDs</primary><secondary>Colormap</secondary></indexterm>
+<indexterm><primary>Resource IDs</primary><secondary>Cursor</secondary></indexterm>
+<indexterm><primary>Resource IDs</primary><secondary>GContext</secondary></indexterm>
+Many Xlib functions will return an integer resource ID,
+which allows you to refer to objects stored on the X server.
+These can be of type
+<type>Window</type>,
+<type>Font</type>,
+<type>Pixmap</type>,
+<type>Colormap</type>,
+<type>Cursor</type>,
+and
+<type>GContext</type>,
+as defined in the file
+<filename class="headerfile"><X11/X.h></filename>.
+<indexterm type="file"><primary><filename class="headerfile">X11/X.h</filename></primary></indexterm>
+<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/X.h></filename></secondary></indexterm>
+<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/X.h></filename></secondary></indexterm>
+These resources are created by requests and are destroyed
+(or freed) by requests or when connections are closed.
+Most of these resources are potentially shareable between
+applications, and in fact, windows are manipulated explicitly by
+window manager programs.
+Fonts and cursors are shared automatically across multiple screens.
+Fonts are loaded and unloaded as needed and are shared by multiple clients.
+Fonts are often cached in the server.
+Xlib provides no support for sharing graphics contexts between applications.
+ </para>
+ <para>
+<indexterm><primary>Event</primary></indexterm>
+Client programs are informed of events.
+Events may either be side effects of a request (for example, restacking windows
+generates
+<systemitem class="event">Expose</systemitem>
+events) or completely asynchronous (for example, from the keyboard).
+A client program asks to be informed of events.
+Because other applications can send events to your application,
+programs must be prepared to handle (or ignore) events of all types.
+ </para>
+ <para>
+Input events (for example, a key pressed or the pointer moved)
+arrive asynchronously from the server and are queued until they are
+requested by an explicit call (for example,
+<xref linkend='XNextEvent' xrefstyle='select: title'/>
+or
+<xref linkend='XWindowEvent' xrefstyle='select: title'/>).
+In addition, some library
+functions (for example,
+<xref linkend='XRaiseWindow' xrefstyle='select: title'/>)
+generate
+<symbol>Expose</symbol>
+and
+<symbol>ConfigureRequest</symbol>
+events.
+These events also arrive asynchronously, but the client may
+<indexterm><primary>XSync</primary></indexterm>
+wish to explicitly wait for them by calling
+<xref linkend='XSync' xrefstyle='select: title'/>
+after calling a function that can cause the server to generate events.
+ </para>
+ </sect1>
+
+ <sect1 id="Errors">
+ <title>Errors</title>
+
+ <para>
+Some functions return
+<type>Status</type>,
+an integer error indication.
+If the function fails, it returns a zero.
+If the function returns a status of zero,
+it has not updated the return arguments.
+<indexterm><primary>Status</primary></indexterm>
+Because C does not provide multiple return values,
+many functions must return their results by writing into client-passed storage.
+<indexterm><primary>Error</primary><secondary>handling</secondary></indexterm>
+By default, errors are handled either by a standard library function
+or by one that you provide.
+Functions that return pointers to strings return NULL pointers if
+the string does not exist.
+ </para>
+ <para>
+The X server reports protocol errors at the time that it detects them.
+If more than one error could be generated for a given request,
+the server can report any of them.
+ </para>
+ <para>
+Because Xlib usually does not transmit requests to the server immediately
+(that is, it buffers them), errors can be reported much later than they
+actually occur.
+For debugging purposes, however,
+Xlib provides a mechanism for forcing synchronous behavior
+(see <link linkend="Enabling_or_Disabling_Synchronization">section 11.8.1</link>).
+When synchronization is enabled,
+errors are reported as they are generated.
+ </para>
+ <para>
+When Xlib detects an error,
+it calls an error handler,
+which your program can provide.
+If you do not provide an error handler,
+the error is printed, and your program terminates.
+ </para>
+ </sect1>
+
+ <sect1 id="Standard_Header_Files">
+ <title>Standard Header Files</title>
+
+ <para>
+The following include files are part of the Xlib standard:
+<indexterm><primary>Headers</primary></indexterm>
+
+<variablelist>
+ <varlistentry id="Standard_Header_Files:Xlib.h">
+ <term><filename class="headerfile"><X11/Xlib.h></filename></term>
+ <listitem>
+ <indexterm type="file"><primary><filename class="headerfile">X11/Xlib.h</filename></primary></indexterm>
+ <indexterm><primary>Files</primary><secondary><X11/Xlib.h></secondary></indexterm>
+ <indexterm><primary>Headers</primary><secondary><X11/Xlib.h></secondary></indexterm>
+ <para>
+This is the main header file for Xlib.
+The majority of all Xlib symbols are declared by including this file.
+This file also contains the preprocessor symbol
+<symbol>XlibSpecificationRelease</symbol>.
+<indexterm significance="preferred"><primary>XlibSpecificationRelease</primary></indexterm>
+This symbol is defined to have the 6 in this release of the standard.
+(Release 5 of Xlib was the first release to have this symbol.)
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="Standard_Header_Files:X.h">
+ <term><filename class="headerfile"><X11/X.h></filename></term>
+ <listitem>
+ <indexterm type="file"><primary><filename class="headerfile">X11/X.h</filename></primary></indexterm>
+ <indexterm><primary>Files</primary><secondary><X11/X.h></secondary></indexterm>
+ <indexterm><primary>Headers</primary><secondary><X11/X.h></secondary></indexterm>
+ <para>
+This file declares types and constants for the X protocol that are
+to be used by applications. It is included automatically from
+<filename class="headerfile"><X11/Xlib.h></filename>
+so application code should never need to
+reference this file directly.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="Standard_Header_Files:Xcms.h">
+ <term><filename class="headerfile"><X11/Xcms.h></filename></term>
+ <listitem>
+ <indexterm type="file"><primary><filename class="headerfile">X11/Xcms.h</filename></primary></indexterm>
+ <indexterm><primary>Files</primary><secondary><X11/Xcms.h></secondary></indexterm>
+ <indexterm><primary>Headers</primary><secondary><X11/Xcms.h></secondary></indexterm>
+ <para>
+This file contains symbols for much of the color management facilities
+described in <link linkend='Color_Management_Functions'>chapter 6</link>.
+All functions, types, and symbols with the prefix "Xcms",
+plus the Color Conversion Contexts macros, are declared in this file.
+<filename class="headerfile"><X11/Xlib.h></filename>
+must be included before including this file.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="Standard_Header_Files:Xutil.h">
+ <term><filename class="headerfile"><X11/Xutil.h></filename></term>
+ <listitem>
+ <indexterm type="file"><primary><filename class="headerfile">X11/Xutil.h</filename></primary></indexterm>
+ <indexterm><primary>Files</primary><secondary><X11/Xutil.h></secondary></indexterm>
+ <indexterm><primary>Headers</primary><secondary><X11/Xutil.h></secondary></indexterm>
+ <para>
+This file declares various functions, types, and symbols used for
+inter-client communication and application utility functions,
+which are described in chapters
+<link linkend='Inter_Client_Communication_Functions'>14</link> and
+<link linkend='Application_Utility_Functions'>16</link>.
+<filename class="headerfile"><X11/Xlib.h></filename> must be included before including this file.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="Standard_Header_Files:Xresource.h">
+ <term><filename class="headerfile"><X11/Xresource.h></filename></term>
+ <listitem>
+ <indexterm type="file"><primary><filename class="headerfile">X11/Xresource.h</filename></primary></indexterm>
+ <indexterm><primary>Files</primary><secondary><X11/Xresource.h></secondary></indexterm>
+ <indexterm><primary>Headers</primary><secondary><X11/Xresource.h></secondary></indexterm>
+ <para>
+This file declares all functions, types, and symbols for the
+resource manager facilities, which are described in
+<link linkend='Resource_Manager_Functions'>chapter 15</link>.
+<filename class="headerfile"><X11/Xlib.h></filename> <!-- xref -->
+must be included before including this file.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="Standard_Header_Files:Xatom.h">
+ <term><filename class="headerfile"><X11/Xatom.h></filename></term>
+ <listitem>
+ <indexterm type="file"><primary><filename class="headerfile">X11/Xatom.h</filename></primary></indexterm>
+ <indexterm><primary>Files</primary><secondary><X11/Xatom.h></secondary></indexterm>
+ <indexterm><primary>Headers</primary><secondary><X11/Xatom.h></secondary></indexterm>
+ <para>
+This file declares all predefined atoms,
+which are symbols with the prefix "XA_".
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="Standard_Header_Files:cursorfont.h">
+ <term><filename class="headerfile"><X11/cursorfont.h></filename></term>
+ <listitem>
+ <indexterm type="file"><primary><filename class="headerfile">X11/cursorfont.h</filename></primary></indexterm>
+ <indexterm><primary>Files</primary><secondary><X11/cursorfont.h></secondary></indexterm>
+ <indexterm><primary>Headers</primary><secondary><X11/cursorfont.h></secondary></indexterm>
+ <para>
+This file declares the cursor symbols for the standard cursor font,
+which are listed in <link linkend="x_font_cursors">Appendix B</link>.
+All cursor symbols have the prefix "XC_".
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="Standard_Header_Files:keysymdef.h">
+ <term><filename class="headerfile"><X11/keysymdef.h></filename></term>
+ <listitem>
+ <indexterm type="file"><primary><filename class="headerfile">X11/keysymdef.h</filename></primary></indexterm>
+ <indexterm><primary>Files</primary><secondary><X11/keysymdef.h></secondary></indexterm>
+ <indexterm><primary>Headers</primary><secondary><X11/keysymdef.h></secondary></indexterm>
+ <para>
+This file declares all standard KeySym values,
+which are symbols with the prefix "XK_".
+The KeySyms are arranged in groups, and a preprocessor symbol controls
+inclusion of each group. The preprocessor symbol must be defined
+prior to inclusion of the file to obtain the associated values.
+The preprocessor symbols are
+<symbol>XK_MISCELLANY</symbol>,
+<symbol>XK_XKB_KEYS</symbol>,
+<symbol>XK_3270</symbol>,
+<symbol>XK_LATIN1</symbol>,
+<symbol>XK_LATIN2</symbol>,
+<symbol>XK_LATIN3</symbol>,
+<symbol>XK_LATIN4</symbol>,
+<symbol>XK_KATAKANA</symbol>,
+<symbol>XK_ARABIC</symbol>,
+<symbol>XK_CYRILLIC</symbol>,
+<symbol>XK_GREEK</symbol>,
+<symbol>XK_TECHNICAL</symbol>,
+<symbol>XK_SPECIAL</symbol>,
+<symbol>XK_PUBLISHING</symbol>,
+<symbol>XK_APL</symbol>,
+<symbol>XK_HEBREW</symbol>,
+<symbol>XK_THAI</symbol>, and
+<symbol>XK_KOREAN</symbol>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="Standard_Header_Files:keysym.h">
+ <term><filename class="headerfile"><X11/keysym.h></filename></term>
+ <listitem>
+ <indexterm type="file"><primary><filename class="headerfile">X11/keysym.h</filename></primary></indexterm>
+ <indexterm><primary>Files</primary><secondary><X11/keysym.h></secondary></indexterm>
+ <indexterm><primary>Headers</primary><secondary><X11/keysym.h></secondary></indexterm>
+ <para>
+This file defines the preprocessor symbols
+<symbol>XK_MISCELLANY</symbol>,
+<symbol>XK_XKB_KEYS</symbol>,
+<symbol>XK_LATIN1</symbol>,
+<symbol>XK_LATIN2</symbol>,
+<symbol>XK_LATIN3</symbol>,
+<symbol>XK_LATIN4</symbol>, and
+<symbol>XK_GREEK</symbol>
+and then includes <filename class="headerfile"><X11/keysymdef.h></filename>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="Standard_Header_Files:Xlibint.h">
+ <term><filename class="headerfile"><X11/Xlibint.h></filename></term>
+ <listitem>
+ <indexterm type="file"><primary><filename class="headerfile">X11/Xlibint.h</filename></primary></indexterm>
+ <indexterm><primary>Files</primary><secondary><X11/Xlibint.h></secondary></indexterm>
+ <indexterm><primary>Headers</primary><secondary><X11/Xlibint.h></secondary></indexterm>
+ <para>
+This file declares all the functions, types, and symbols used for
+extensions, which are described in <link linkend="extensions">Appendix C</link>.
+This file automatically includes
+<filename class="headerfile"><X11/Xlib.h></filename>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="Standard_Header_Files:Xproto.h">
+ <term><filename class="headerfile"><X11/Xproto.h></filename></term>
+ <listitem>
+ <indexterm type="file"><primary><filename class="headerfile">X11/Xproto.h</filename></primary></indexterm>
+ <indexterm><primary>Files</primary><secondary><X11/Xproto.h></secondary></indexterm>
+ <indexterm><primary>Headers</primary><secondary><X11/Xproto.h></secondary></indexterm>
+ <para>
+This file declares types and symbols for the basic X protocol,
+for use in implementing extensions.
+It is included automatically from
+<filename class="headerfile"><X11/Xlibint.h></filename>,
+so application and extension code should never need to
+reference this file directly.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="Standard_Header_Files:Xprotostr.h">
+ <term><filename class="headerfile"><X11/Xprotostr.h></filename></term>
+ <listitem>
+ <indexterm type="file"><primary><filename class="headerfile">X11/Xprotostr.h</filename></primary></indexterm>
+ <indexterm><primary>Files</primary><secondary><X11/Xprotostr.h></secondary></indexterm>
+ <indexterm><primary>Headers</primary><secondary><X11/Xprotostr.h></secondary></indexterm>
+ <para>
+This file declares types and symbols for the basic X protocol,
+for use in implementing extensions.
+It is included automatically from
+<filename class="headerfile"><X11/Xproto.h></filename>,
+so application and extension code should never need to
+reference this file directly.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="Standard_Header_Files:X10.h">
+ <term><filename class="headerfile"><X11/X10.h></filename></term>
+ <listitem>
+ <indexterm type="file"><primary><filename class="headerfile">X11/X10.h</filename></primary></indexterm>
+ <indexterm><primary>Files</primary><secondary><X11/X10.h></secondary></indexterm>
+ <indexterm><primary>Headers</primary><secondary><X11/X10.h></secondary></indexterm>
+ <para>
+This file declares all the functions, types, and symbols used for the
+X10 compatibility functions, which are described in
+<link linkend="X_Version_10_Compatibility_Functions">Appendix D</link>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+ </para>
+ </sect1>
+
+ <sect1 id="Generic_Values_and_Types">
+ <title>Generic Values and Types</title>
+
+ <para>
+The following symbols are defined by Xlib and used throughout the manual:
+<itemizedlist>
+ <listitem>
+ <para>
+<indexterm significance="preferred"><primary>Bool</primary></indexterm>
+<indexterm significance="preferred"><primary>True</primary></indexterm>
+<indexterm significance="preferred"><primary>False</primary></indexterm>
+Xlib defines the type
+<type>Bool</type>
+and the Boolean values
+<symbol>True</symbol>
+and
+<symbol>False</symbol>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<indexterm significance="preferred"><primary>None</primary></indexterm>
+<symbol>None</symbol>
+is the universal null resource ID or atom.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<indexterm significance="preferred"><primary>XID</primary></indexterm>
+The type
+<type>XID</type>
+is used for generic resource IDs.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<indexterm significance="preferred"><primary>XPointer</primary></indexterm>
+The type <type>XPointer</type> is defined to be <type>char *</type>
+and is used as a generic opaque pointer to data.
+ </para>
+ </listitem>
+</itemizedlist>
+ </para>
+ </sect1>
+
+ <sect1 id="Naming_and_Argument_Conventions_within_Xlib">
+ <title>Naming and Argument Conventions within Xlib</title>
+
+ <para>
+Xlib follows a number of conventions for the naming and syntax of the functions.
+Given that you remember what information the function requires,
+these conventions are intended to make the syntax of the functions more
+predictable.
+ </para>
+ <para>
+The major naming conventions are:
+<itemizedlist>
+ <listitem>
+ <para>
+To differentiate the X symbols from the other symbols,
+the library uses mixed case for external symbols.
+It leaves lowercase for variables and all uppercase for user macros,
+as per existing convention.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+All Xlib functions begin with a capital X.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The beginnings of all function names and symbols are capitalized.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+All user-visible data structures begin with a capital X.
+More generally,
+anything that a user might dereference begins with a capital X.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Macros and other symbols do not begin with a capital X.
+To distinguish them from all user symbols,
+each word in the macro is capitalized.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+All elements of or variables in a data structure are in lowercase.
+Compound words, where needed, are constructed with underscores (_).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The display argument, where used, is always first in the argument list.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+All resource objects, where used, occur at the beginning of the argument list
+immediately after the display argument.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+When a graphics context is present together with
+another type of resource (most commonly, a drawable), the
+graphics context occurs in the argument list after the other
+resource.
+Drawables outrank all other resources.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Source arguments always precede the destination arguments in the argument list.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The x argument always precedes the y argument in the argument list.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The width argument always precedes the height argument in the argument list.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Where the x, y, width, and height arguments are used together,
+the x and y arguments always precede the width and height arguments.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Where a mask is accompanied with a structure,
+the mask always precedes the pointer to the structure in the argument list.
+ </para>
+ </listitem>
+</itemizedlist>
+ </para>
+ </sect1>
+
+ <sect1 id="Programming_Considerations">
+ <title>Programming Considerations</title>
+
+ <para>
+The major programming considerations are:
+<itemizedlist>
+ <listitem>
+ <para>
+Coordinates and sizes in X are actually 16-bit quantities.
+This decision was made to minimize the bandwidth required for a
+given level of performance.
+Coordinates usually are declared as an
+<type>int</type>
+in the interface.
+Values larger than 16 bits are truncated silently.
+Sizes (width and height) are declared as unsigned quantities.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Keyboards are the greatest variable between different
+manufacturers' workstations.
+If you want your program to be portable,
+you should be particularly conservative here.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Many display systems have limited amounts of off-screen memory.
+If you can, you should minimize use of pixmaps and backing
+store.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The user should have control of their screen real estate.
+Therefore, you should write your applications to react to window management
+rather than presume control of the entire screen.
+What you do inside of your top-level window, however,
+is up to your application.
+For further information,
+see <link linkend='Inter_Client_Communication_Functions'>chapter 14</link>
+and the <citetitle>Inter-Client Communication Conventions Manual</citetitle>.
+ </para>
+ </listitem>
+</itemizedlist>
+ </para>
+ </sect1>
+
+ <sect1 id="Character_Sets_and_Encodings">
+ <title>Character Sets and Encodings</title>
+
+ <para>
+Some of the Xlib functions make reference to specific character sets
+and character encodings.
+The following are the most common:
+
+<variablelist>
+ <varlistentry>
+ <term><firstterm>X Portable Character Set</firstterm></term>
+ <listitem><para>
+A basic set of 97 characters,
+which are assumed to exist in all locales supported by Xlib.
+This set contains the following characters:
+<literallayout>
+a..z A..Z 0..9 !"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~ <space>, <tab>, and <newline>
+</literallayout>
+ </para>
+ <para>
+This set is the left/lower half
+of the graphic character set of ISO8859-1 plus space, tab, and newline.
+It is also the set of graphic characters in 7-bit ASCII plus the same
+three control characters.
+The actual encoding of these characters on the host is system dependent.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><firstterm>Host Portable Character Encoding</firstterm></term>
+ <listitem>
+ <para>
+The encoding of the X Portable Character Set on the host.
+The encoding itself is not defined by this standard,
+but the encoding must be the same in all locales supported by Xlib on the host.
+If a string is said to be in the Host Portable Character Encoding,
+then it only contains characters from the X Portable Character Set,
+in the host encoding.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><firstterm>Latin-1</firstterm></term>
+ <listitem>
+ <para>
+The coded character set defined by the ISO8859-1 standard.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><firstterm>Latin Portable Character Encoding</firstterm></term>
+ <listitem>
+ <para>
+The encoding of the X Portable Character Set using the Latin-1 codepoints
+plus ASCII control characters.
+If a string is said to be in the Latin Portable Character Encoding,
+then it only contains characters from the X Portable Character Set,
+not all of Latin-1.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><firstterm>STRING Encoding</firstterm></term>
+ <listitem>
+ <para>
+Latin-1, plus tab and newline.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><firstterm><acronym>POSIX</acronym> Portable Filename Character Set</firstterm></term>
+ <listitem>
+ <para>
+The set of 65 characters,
+which can be used in naming files on a <acronym>POSIX</acronym>-compliant host,
+that are correctly processed in all locales.
+The set is:
+<literallayout>
+a..z A..Z 0..9 ._-
+</literallayout>
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+ </para>
+ </sect1>
+
+ <sect1 id="Formatting_Conventions">
+ <title>Formatting Conventions</title>
+
+ <para>
+ <citetitle>Xlib − C Language X Interface</citetitle> uses the
+ following conventions:
+
+ <itemizedlist>
+ <listitem>
+ <para>
+Global symbols are printed in
+<function>this</function>
+<function>special</function>
+<function>font</function>.
+These can be either function names,
+symbols defined in include files, or structure names.
+When declared and defined,
+function arguments are printed in <emphasis remap='I'>italics</emphasis>.
+In the explanatory text that follows,
+they usually are printed in regular type.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Each function is introduced by a general discussion that
+distinguishes it from other functions.
+The function declaration itself follows,
+and each argument is specifically explained.
+Although ANSI C function prototype syntax is not used,
+Xlib header files normally declare functions using function prototypes
+in ANSI C environments.
+General discussion of the function, if any is required,
+follows the arguments.
+Where applicable,
+the last paragraph of the explanation lists the possible
+Xlib error codes that the function can generate.
+For a complete discussion of the Xlib error codes,
+see <link linkend="Using_the_Default_Error_Handlers">section 11.8.2</link>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+To eliminate any ambiguity between those arguments that you pass and those that
+a function returns to you,
+the explanations for all arguments that you pass start with the word
+<emphasis remap='I'>specifies</emphasis> or, in the case of multiple arguments, the word <emphasis remap='I'>specify</emphasis>.
+The explanations for all arguments that are returned to you start with the
+word <emphasis remap='I'>returns</emphasis> or, in the case of multiple arguments, the word <emphasis remap='I'>return</emphasis>.
+The explanations for all arguments that you can pass and are returned start
+with the words <emphasis remap='I'>specifies and returns</emphasis>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Any pointer to a structure that is used to return a value is designated as
+such by the <emphasis remap='I'>_return</emphasis> suffix as part of its name.
+All other pointers passed to these functions are
+used for reading only.
+A few arguments use pointers to structures that are used for
+both input and output and are indicated by using the <emphasis remap='I'>_in_out</emphasis> suffix.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </sect1>
+</chapter>
Index: create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/libX11/CH02.xml
===================================================================
--- create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/libX11/CH02.xml (nonexistent)
+++ create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/libX11/CH02.xml (revision 5)
@@ -0,0 +1,3652 @@
+<?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='Display_Functions'>
+<title>Display Functions</title>
+<para>
+Before your program can use a display, you must establish a connection
+to the X server.
+Once you have established a connection,
+you then can use the Xlib macros and functions discussed in this chapter
+to return information about the display.
+This chapter discusses how to:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Open (connect to) the display
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Obtain information about the display, image formats, or screens
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Generate a
+<systemitem>NoOperation</systemitem>
+protocol request
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Free client-created data
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Close (disconnect from) a display
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Use X Server connection close operations
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Use Xlib with threads
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Use internal connections
+ </para>
+ </listitem>
+</itemizedlist>
+<sect1 id="Opening_the_Display">
+<title>Opening the Display</title>
+<!-- .XS -->
+<!-- (SN Opening the Display -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To open a connection to the X server that controls a display, use
+<xref linkend='XOpenDisplay' xrefstyle='select: title'/>.
+<indexterm significance="preferred"><primary>XOpenDisplay</primary></indexterm>
+</para>
+<funcsynopsis id='XOpenDisplay'>
+<funcprototype>
+ <funcdef>Display *<function>XOpenDisplay</function></funcdef>
+ <paramdef>char *<parameter>display_name</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display_name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the hardware display name, which determines the display
+and communications domain to be used.
+On a <acronym>POSIX</acronym>-conformant system, if the display_name is NULL,
+it defaults to the value of the DISPLAY environment variable.
+<indexterm><primary>Environment</primary><secondary>DISPLAY</secondary></indexterm>
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The encoding and interpretation of the display name are
+implementation-dependent.
+Strings in the Host Portable Character Encoding are supported;
+support for other characters is implementation-dependent.
+On <acronym>POSIX</acronym>-conformant systems,
+the display name or DISPLAY environment variable can be a string in the format:
+</para>
+<!-- .LP -->
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA 1i -->
+<!-- .ta 1i -->
+ <emphasis remap='I'>protocol</emphasis>/<emphasis remap='I'>hostname</emphasis>:<emphasis remap='I'>number</emphasis>.<emphasis remap='I'>screen_number</emphasis>
+</literallayout>
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>protocol</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a protocol family or an alias for a protocol family. Supported
+protocol families are implementation dependent. The protocol entry is
+optional. If protocol is not specified, the / separating protocol and
+hostname must also not be specified.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>hostname</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the name of the host machine on which the display is physically
+attached.
+You follow the hostname with either a single colon (:) or a double colon (::).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>number</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of the display server on that host machine.
+You may optionally follow this display number with a period (.).
+A single <acronym>CPU</acronym> can have more than one display.
+Multiple displays are usually numbered starting with zero.
+<indexterm><primary>Screen</primary></indexterm>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen_number</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the screen to be used on that server.
+Multiple screens can be controlled by a single X server.
+The screen_number sets an internal variable that can be accessed by
+using the
+<function>DefaultScreen</function>
+macro or the
+<xref linkend='XDefaultScreen' xrefstyle='select: title'/>
+function if you are using languages other than C
+(see <link linkend='Display_Macros'>section 2.2.1</link>).
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+For example, the following would specify screen 1 of display 0 on the
+machine named ``dual-headed'':
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+dual-headed:0.1
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+The
+<xref linkend='XOpenDisplay' xrefstyle='select: title'/>
+function returns a
+<type>Display</type>
+structure that serves as the
+connection to the X server and that contains all the information
+about that X server.
+<xref linkend='XOpenDisplay' xrefstyle='select: title'/>
+connects your application to the X server through <acronym>TCP</acronym>
+or DECnet communications protocols,
+or through some local inter-process communication protocol.
+<indexterm><primary>Protocol</primary><secondary><acronym>TCP</acronym></secondary></indexterm>
+<indexterm><primary>Protocol</primary><secondary>DECnet</secondary></indexterm>
+If the protocol is specified as "tcp", "inet", or "inet6", or
+if no protocol is specified and the hostname is a host machine name and a single colon (:)
+separates the hostname and display number,
+<xref linkend='XOpenDisplay' xrefstyle='select: title'/>
+connects using <acronym>TCP</acronym> streams. (If the protocol is specified as "inet", <acronym>TCP</acronym> over
+IPv4 is used. If the protocol is specified as "inet6", <acronym>TCP</acronym> over IPv6 is used.
+Otherwise, the implementation determines which <acronym>IP</acronym> version is used.)
+If the hostname and protocol are both not specified,
+Xlib uses whatever it believes is the fastest transport.
+If the hostname is a host machine name and a double colon (::)
+separates the hostname and display number,
+<xref linkend='XOpenDisplay' xrefstyle='select: title'/>
+connects using DECnet.
+A single X server can support any or all of these transport mechanisms
+simultaneously.
+A particular Xlib implementation can support many more of these transport
+mechanisms.
+</para>
+<para>
+<!-- .LP -->
+<indexterm><primary>Display</primary></indexterm>
+If successful,
+<xref linkend='XOpenDisplay' xrefstyle='select: title'/>
+returns a pointer to a
+<type>Display</type>
+structure,
+which is defined in
+<filename class="headerfile"><X11/Xlib.h></filename>.
+<indexterm type="file"><primary><filename class="headerfile">X11/Xlib.h</filename></primary></indexterm>
+<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/Xlib.h></filename></secondary></indexterm>
+<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/Xlib.h></filename></secondary></indexterm>
+If
+<xref linkend='XOpenDisplay' xrefstyle='select: title'/>
+does not succeed, it returns NULL.
+After a successful call to
+<xref linkend='XOpenDisplay' xrefstyle='select: title'/>,
+all of the screens in the display can be used by the client.
+The screen number specified in the display_name argument is returned
+by the
+<function>DefaultScreen</function>
+macro (or the
+<xref linkend='XDefaultScreen' xrefstyle='select: title'/>
+function).
+You can access elements of the
+<type>Display</type>
+and
+<type>Screen</type>
+structures only by using the information macros or functions.
+For information about using macros and functions to obtain information from
+the
+<type>Display</type>
+structure,
+see <link linkend='Display_Macros'>section 2.2.1</link>.
+</para>
+<para>
+<!-- .LP -->
+X servers may implement various types of access control mechanisms
+(see <link linkend="Controlling_Host_Access">section 9.8</link>).
+</para>
+</sect1>
+<sect1 id="Obtaining_Information_about_the_Display_Image_Formats_or_Screens">
+<title>Obtaining Information about the Display, Image Formats, or Screens</title>
+<!-- .XS -->
+<!-- (SN Obtaining Information about the Display, Image Formats, or Screens -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The Xlib library provides a number of useful macros
+and corresponding functions that return data from the
+<type>Display</type>
+structure.
+The macros are used for C programming,
+and their corresponding function equivalents are for other language bindings.
+This section discusses the:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Display macros
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Image format functions and macros
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Screen information macros
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+<indexterm ><primary>Display</primary><secondary>data structure</secondary></indexterm>
+All other members of the
+<type>Display</type>
+structure (that is, those for which no macros are defined) are private to Xlib
+and must not be used.
+Applications must never directly modify or inspect these private members of the
+<type>Display</type>
+structure.
+<!-- .NT Note -->
+The
+<xref linkend='XDisplayWidth' xrefstyle='select: title'/>,
+<xref linkend='XDisplayHeight' xrefstyle='select: title'/>,
+<xref linkend='XDisplayCells' xrefstyle='select: title'/>,
+<xref linkend='XDisplayPlanes' xrefstyle='select: title'/>,
+<xref linkend='XDisplayWidthMM' xrefstyle='select: title'/>,
+and
+<xref linkend='XDisplayHeightMM' xrefstyle='select: title'/>
+functions in the next sections are misnamed.
+These functions really should be named Screen<emphasis remap='I'>whatever</emphasis>
+and XScreen<emphasis remap='I'>whatever</emphasis>, not Display<emphasis remap='I'>whatever</emphasis> or XDisplay<emphasis remap='I'>whatever</emphasis>.
+Our apologies for the resulting confusion.
+<!-- .NE -->
+</para>
+<sect2 id='Display_Macros'>
+<title>Display Macros</title>
+<!-- .XS -->
+<!-- (SN Display Macros -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Applications should not directly modify any part of the
+<type>Display</type>
+and
+<type>Screen</type>
+structures.
+The members should be considered read-only,
+although they may change as the result of other operations on the display.
+</para>
+<para>
+<!-- .LP -->
+The following lists the C language macros,
+their corresponding function equivalents that are for other language bindings,
+and what data both can return.
+</para>
+<synopsis id='AllPlanes' role='macro'><constant>AllPlanes</constant></synopsis>
+<funcsynopsis id='XAllPlanes'>
+<funcprototype>
+ <funcdef>unsigned long <function>XAllPlanes</function></funcdef>
+ <void />
+</funcprototype>
+</funcsynopsis>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>AllPlanes</primary></indexterm>
+<indexterm significance="preferred"><primary>XAllPlanes</primary></indexterm>
+Both return a value with all bits set to 1 suitable for use in a plane argument to
+a procedure.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<indexterm significance="preferred"><primary>BlackPixel</primary></indexterm>
+<indexterm significance="preferred"><primary>XBlackPixel</primary></indexterm>
+<indexterm significance="preferred"><primary>WhitePixel</primary></indexterm>
+<indexterm significance="preferred"><primary>XWhitePixel</primary></indexterm>
+Both
+<function>BlackPixel</function>
+and
+<function>WhitePixel</function>
+can be used in implementing a monochrome application.
+These pixel values are for permanently allocated entries in the default
+colormap.
+The actual <acronym>RGB</acronym> (red, green, and blue) values are settable on some screens
+and, in any case, may not actually be black or white.
+The names are intended to convey the expected relative intensity of the colors.
+<!-- .sM -->
+</para>
+<funcsynopsis id='BlackPixel'>
+<funcprototype role='macro'>
+ <funcdef><function>BlackPixel</function></funcdef>
+ <paramdef><parameter>display</parameter></paramdef>
+ <paramdef><parameter>screen_number</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<funcsynopsis id='XBlackPixel'>
+<funcprototype>
+ <funcdef>unsigned long <function>XBlackPixel</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 -->
+Both return the black pixel value for the specified screen.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<funcsynopsis id='WhitePixel'>
+<funcprototype role='macro'>
+ <funcdef><function>WhitePixel</function></funcdef>
+ <paramdef><parameter>display</parameter></paramdef>
+ <paramdef><parameter>screen_number</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<funcsynopsis id='XWhitePixel'>
+<funcprototype>
+ <funcdef>unsigned long <function>XWhitePixel</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 -->
+Both return the white pixel value for the specified screen.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<funcsynopsis id='ConnectionNumber'>
+<funcprototype role='macro'>
+ <funcdef><function>ConnectionNumber</function></funcdef>
+ <paramdef><parameter>display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<funcsynopsis id='XConnectionNumber'>
+<funcprototype>
+ <funcdef>int <function>XConnectionNumber</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>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>ConnectionNumber</primary></indexterm>
+<indexterm significance="preferred"><primary>XConnectionNumber</primary></indexterm>
+Both return a connection number for the specified display.
+On a <acronym>POSIX</acronym>-conformant system,
+this is the file descriptor of the connection.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<funcsynopsis id='DefaultColormap'>
+<funcprototype role='macro'>
+ <funcdef><function>DefaultColormap</function></funcdef>
+ <paramdef><parameter>display</parameter></paramdef>
+ <paramdef><parameter>screen_number</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<funcsynopsis id='XDefaultColormap'>
+<funcprototype>
+ <funcdef>Colormap <function>XDefaultColormap</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 -->
+<indexterm significance="preferred"><primary>DefaultColormap</primary></indexterm>
+<indexterm significance="preferred"><primary>XDefaultColormap</primary></indexterm>
+Both return the default colormap ID for allocation on the specified screen.
+Most routine allocations of color should be made out of this colormap.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<funcsynopsis id='DefaultDepth'>
+<funcprototype role='macro'>
+ <funcdef><function>DefaultDepth</function></funcdef>
+ <paramdef><parameter>display</parameter></paramdef>
+ <paramdef><parameter>screen_number</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<funcsynopsis id='XDefaultDepth'>
+<funcprototype>
+ <funcdef>int <function>XDefaultDepth</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 -->
+<indexterm significance="preferred"><primary>DefaultDepth</primary></indexterm>
+<indexterm significance="preferred"><primary>XDefaultDepth</primary></indexterm>
+Both return the depth (number of planes) of the default root window for the
+specified screen.
+Other depths may also be supported on this screen (see
+<xref linkend='XMatchVisualInfo' xrefstyle='select: title'/>).
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<indexterm significance="preferred"><primary>XListDepths</primary></indexterm>
+To determine the number of depths that are available on a given screen, use
+<function>XListDepths</function>.
+<!-- .sM -->
+</para>
+<funcsynopsis id='XListDepths'>
+<funcprototype>
+ <funcdef>int *<function>XListDepths</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>int <parameter>screen_number</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'>screen_number</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate screen number on the host server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>count_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the number of depths.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XListDepths</function>
+function returns the array of depths
+that are available on the specified screen.
+If the specified screen_number is valid and sufficient memory for the array
+can be allocated,
+<function>XListDepths</function>
+sets count_return to the number of available depths.
+Otherwise, it does not set count_return and returns NULL.
+To release the memory allocated for the array of depths, use
+<xref linkend='XFree' xrefstyle='select: title'/>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<funcsynopsis id='DefaultGC'>
+<funcprototype role='macro'>
+ <funcdef><function>DefaultGC</function></funcdef>
+ <paramdef><parameter>display</parameter></paramdef>
+ <paramdef><parameter>screen_number</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<funcsynopsis id='XDefaultGC'>
+<funcprototype>
+ <funcdef>GC <function>XDefaultGC</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 -->
+<indexterm significance="preferred"><primary>DefaultGC</primary></indexterm>
+<indexterm significance="preferred"><primary>XDefaultGC</primary></indexterm>
+Both return the default graphics context for the root window of the
+specified screen.
+This GC is created for the convenience of simple applications
+and contains the default GC components with the foreground and
+background pixel values initialized to the black and white
+pixels for the screen, respectively.
+You can modify its contents freely because it is not used in any Xlib
+function.
+This GC should never be freed.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<funcsynopsis id='DefaultRootWindow'>
+<funcprototype role='macro'>
+ <funcdef><function>DefaultRootWindow</function></funcdef>
+ <paramdef><parameter>display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<funcsynopsis id='XDefaultRootWindow'>
+<funcprototype>
+ <funcdef>Window <function>XDefaultRootWindow</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>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>DefaultRootWindow</primary></indexterm>
+<indexterm significance="preferred"><primary>XDefaultRootWindow</primary></indexterm>
+Both return the root window for the default screen.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<funcsynopsis id='DefaultScreenOfDisplay'>
+<funcprototype role='macro'>
+ <funcdef><function>DefaultScreenOfDisplay</function></funcdef>
+ <paramdef><parameter>display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<funcsynopsis id='XDefaultScreenOfDisplay'>
+<funcprototype>
+ <funcdef>Screen *<function>XDefaultScreenOfDisplay</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>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>DefaultScreenOfDisplay</primary></indexterm>
+<indexterm significance="preferred"><primary>XDefaultScreenOfDisplay</primary></indexterm>
+Both return a pointer to the default screen.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<funcsynopsis id='ScreenOfDisplay'>
+<funcprototype role='macro'>
+ <funcdef><function>ScreenOfDisplay</function></funcdef>
+ <paramdef><parameter>display</parameter></paramdef>
+ <paramdef><parameter>screen_number</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<funcsynopsis id='XScreenOfDisplay'>
+<funcprototype>
+ <funcdef>Screen *<function>XScreenOfDisplay</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 -->
+<indexterm significance="preferred"><primary>ScreenOfDisplay</primary></indexterm>
+<indexterm significance="preferred"><primary>XScreenOfDisplay</primary></indexterm>
+Both return a pointer to the indicated screen.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<funcsynopsis id='DefaultScreen'>
+<funcprototype role='macro'>
+ <funcdef><function>DefaultScreen</function></funcdef>
+ <paramdef><parameter>display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<funcsynopsis id='XDefaultScreen'>
+<funcprototype>
+ <funcdef>int <function>XDefaultScreen</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>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>DefaultScreen</primary></indexterm>
+<indexterm significance="preferred"><primary>XDefaultScreen</primary></indexterm>
+Both return the default screen number referenced by the
+<xref linkend='XOpenDisplay' xrefstyle='select: title'/>
+function.
+This macro or function should be used to retrieve the screen number
+in applications that will use only a single screen.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<funcsynopsis id='DefaultVisual'>
+<funcprototype role='macro'>
+ <funcdef><function>DefaultVisual</function></funcdef>
+ <paramdef><parameter>display</parameter></paramdef>
+ <paramdef><parameter>screen_number</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<funcsynopsis id='XDefaultVisual'>
+<funcprototype>
+ <funcdef>Visual *<function>XDefaultVisual</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 -->
+<indexterm significance="preferred"><primary>DefaultVisual</primary></indexterm>
+<indexterm significance="preferred"><primary>XDefaultVisual</primary></indexterm>
+Both return the default visual type for the specified screen.
+For further information about visual types,
+see <link linkend="Visual_Types">section 3.1</link>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<funcsynopsis id='DisplayCells'>
+<funcprototype role='macro'>
+ <funcdef><function>DisplayCells</function></funcdef>
+ <paramdef><parameter>display</parameter></paramdef>
+ <paramdef><parameter>screen_number</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<funcsynopsis id='XDisplayCells'>
+<funcprototype>
+ <funcdef>int <function>XDisplayCells</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 -->
+<indexterm significance="preferred"><primary>DisplayCells</primary></indexterm>
+<indexterm significance="preferred"><primary>XDisplayCells</primary></indexterm>
+Both return the number of entries in the default colormap.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<funcsynopsis id='DisplayPlanes'>
+<funcprototype role='macro'>
+ <funcdef><function>DisplayPlanes</function></funcdef>
+ <paramdef><parameter>display</parameter></paramdef>
+ <paramdef><parameter>screen_number</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<funcsynopsis id='XDisplayPlanes'>
+<funcprototype>
+ <funcdef>int <function>XDisplayPlanes</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 -->
+<indexterm significance="preferred"><primary>DisplayPlanes</primary></indexterm>
+<indexterm significance="preferred"><primary>XDisplayPlanes</primary></indexterm>
+Both return the depth of the root window of the specified screen.
+For an explanation of depth,
+see the glossary.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<funcsynopsis id='DisplayString'>
+<funcprototype role='macro'>
+ <funcdef><function>DisplayString</function></funcdef>
+ <paramdef><parameter>display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<funcsynopsis id='XDisplayString'>
+<funcprototype>
+ <funcdef>char *<function>XDisplayString</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>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>DisplayString</primary></indexterm>
+<indexterm significance="preferred"><primary>XDisplayString</primary></indexterm>
+Both return the string that was passed to
+<xref linkend='XOpenDisplay' xrefstyle='select: title'/>
+when the current display was opened.
+On <acronym>POSIX</acronym>-conformant systems,
+if the passed string was NULL, these return the value of
+the DISPLAY environment variable when the current display was opened.
+<indexterm><primary><acronym>POSIX</acronym> System Call</primary><secondary>fork</secondary></indexterm>
+These are useful to applications that invoke the
+<function>fork</function>
+system call and want to open a new connection to the same display from the
+child process as well as for printing error messages.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<funcsynopsis id='XExtendedMaxRequestSize'>
+<funcprototype>
+ <funcdef>long <function>XExtendedMaxRequestSize</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>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>XExtendedMaxRequestSize</primary></indexterm>
+The
+<function>XExtendedMaxRequestSize</function>
+function returns zero if the specified display does not support an
+extended-length protocol encoding; otherwise,
+it returns the maximum request size (in 4-byte units) supported
+by the server using the extended-length encoding.
+The Xlib functions
+<xref linkend='XDrawLines' xrefstyle='select: title'/>,
+<xref linkend='XDrawArcs' xrefstyle='select: title'/>,
+<xref linkend='XFillPolygon' xrefstyle='select: title'/>,
+<xref linkend='XChangeProperty' xrefstyle='select: title'/>,
+<xref linkend='XSetClipRectangles' xrefstyle='select: title'/>,
+and
+<xref linkend='XSetRegion' xrefstyle='select: title'/>
+will use the extended-length encoding as necessary, if supported
+by the server. Use of the extended-length encoding in other Xlib
+functions (for example,
+<xref linkend='XDrawPoints' xrefstyle='select: title'/>,
+<xref linkend='XDrawRectangles' xrefstyle='select: title'/>,
+<xref linkend='XDrawSegments' xrefstyle='select: title'/>,
+<xref linkend='XFillArcs' xrefstyle='select: title'/>,
+<xref linkend='XFillRectangles' xrefstyle='select: title'/>,
+<xref linkend='XPutImage' xrefstyle='select: title'/>)
+is permitted but not required; an Xlib implementation may choose to
+split the data across multiple smaller requests instead.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>long <function>XMaxRequestSize</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>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>XMaxRequestSize</primary></indexterm>
+The
+<function>XMaxRequestSize</function>
+function returns the maximum request size (in 4-byte units) supported
+by the server without using an extended-length protocol encoding.
+Single protocol requests to the server can be no larger than this size
+unless an extended-length protocol encoding is supported by the server.
+The protocol guarantees the size to be no smaller than 4096 units
+(16384 bytes).
+Xlib automatically breaks data up into multiple protocol requests
+as necessary for the following functions:
+<xref linkend='XDrawPoints' xrefstyle='select: title'/>,
+<xref linkend='XDrawRectangles' xrefstyle='select: title'/>,
+<xref linkend='XDrawSegments' xrefstyle='select: title'/>,
+<xref linkend='XFillArcs' xrefstyle='select: title'/>,
+<xref linkend='XFillRectangles' xrefstyle='select: title'/>,
+and
+<xref linkend='XPutImage' xrefstyle='select: title'/>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<funcsynopsis id='LastKnownRequestProcessed'>
+<funcprototype role='macro'>
+ <funcdef><function>LastKnownRequestProcessed</function></funcdef>
+ <paramdef><parameter>display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<funcsynopsis id='XLastKnownRequestProcessed'>
+<funcprototype>
+ <funcdef>unsigned long <function>XLastKnownRequestProcessed</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>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>LastKnownRequestProcessed</primary></indexterm>
+<indexterm significance="preferred"><primary>XLastKnownRequestProcessed</primary></indexterm>
+Both extract the full serial number of the last request known by Xlib
+to have been processed by the X server.
+Xlib automatically sets this number when replies, events, and errors
+are received.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<funcsynopsis id='NextRequest'>
+<funcprototype role='macro'>
+ <funcdef><function>NextRequest</function></funcdef>
+ <paramdef><parameter>display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<funcsynopsis id='XNextRequest'>
+<funcprototype>
+ <funcdef>unsigned long <function>XNextRequest</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>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>NextRequest</primary></indexterm>
+<indexterm significance="preferred"><primary>XNextRequest</primary></indexterm>
+Both extract the full serial number that is to be used for the next
+request.
+Serial numbers are maintained separately for each display connection.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<funcsynopsis id='ProtocolVersion'>
+<funcprototype role='macro'>
+ <funcdef><function>ProtocolVersion</function></funcdef>
+ <paramdef><parameter>display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<funcsynopsis id='XProtocolVersion'>
+<funcprototype>
+ <funcdef>int <function>XProtocolVersion</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>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>ProtocolVersion</primary></indexterm>
+<indexterm significance="preferred"><primary>XProtocolVersion</primary></indexterm>
+Both return the major version number (11) of the X protocol associated with
+the connected display.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<funcsynopsis id='ProtocolRevision'>
+<funcprototype role='macro'>
+ <funcdef><function>ProtocolRevision</function></funcdef>
+ <paramdef><parameter>display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<funcsynopsis id='XProtocolRevision'>
+<funcprototype>
+ <funcdef>int <function>XProtocolRevision</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>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>ProtocolRevision</primary></indexterm>
+<indexterm significance="preferred"><primary>XProtocolRevision</primary></indexterm>
+Both return the minor protocol revision number of the X server.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<funcsynopsis id='QLength'>
+<funcprototype role='macro'>
+ <funcdef><function>QLength</function></funcdef>
+ <paramdef><parameter>display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<funcsynopsis id='XQLength'>
+<funcprototype>
+ <funcdef>int <function>XQLength</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>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>QLength</primary></indexterm>
+<indexterm significance="preferred"><primary>XQLength</primary></indexterm>
+Both return the length of the event queue for the connected display.
+Note that there may be more events that have not been read into
+the queue yet (see
+<xref linkend='XEventsQueued' xrefstyle='select: title'/>).
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<funcsynopsis id='RootWindow'>
+<funcprototype role='macro'>
+ <funcdef><function>RootWindow</function></funcdef>
+ <paramdef><parameter>display</parameter></paramdef>
+ <paramdef><parameter>screen_number</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<funcsynopsis id='XRootWindow'>
+<funcprototype>
+ <funcdef>Window <function>XRootWindow</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 -->
+<indexterm><primary>Window</primary><secondary>RootWindow</secondary></indexterm>
+<indexterm significance="preferred"><primary>RootWindow</primary></indexterm>
+<indexterm><primary>Window</primary><secondary>XRootWindow</secondary></indexterm>
+<indexterm significance="preferred"><primary>XRootWindow</primary></indexterm>
+Both return the root window.
+These are useful with functions that need a drawable of a particular screen
+and for creating top-level windows.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<funcsynopsis id='ScreenCount'>
+<funcprototype role='macro'>
+ <funcdef><function>ScreenCount</function></funcdef>
+ <paramdef><parameter>display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<funcsynopsis id='XScreenCount'>
+<funcprototype>
+ <funcdef>int <function>XScreenCount</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>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>ScreenCount</primary></indexterm>
+<indexterm significance="preferred"><primary>XScreenCount</primary></indexterm>
+Both return the number of available screens.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<funcsynopsis id='ServerVendor'>
+<funcprototype role='macro'>
+ <funcdef><function>ServerVendor</function></funcdef>
+ <paramdef><parameter>display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<funcsynopsis id='XServerVendor'>
+<funcprototype>
+ <funcdef>char *<function>XServerVendor</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>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>ServerVendor</primary></indexterm>
+<indexterm significance="preferred"><primary>XServerVendor</primary></indexterm>
+Both return a pointer to a null-terminated string that provides
+some identification of the owner of the X server implementation.
+If the data returned by the server is in the Latin Portable Character Encoding,
+then the string is in the Host Portable Character Encoding.
+Otherwise, the contents of the string are implementation-dependent.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<funcsynopsis id='VendorRelease'>
+<funcprototype role='macro'>
+ <funcdef><function>VendorRelease</function></funcdef>
+ <paramdef><parameter>display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<funcsynopsis id='XVendorRelease'>
+<funcprototype>
+ <funcdef>int <function>XVendorRelease</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>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>VendorRelease</primary></indexterm>
+<indexterm significance="preferred"><primary>XVendorRelease</primary></indexterm>
+Both return a number related to a vendor's release of the X server.
+</para>
+</sect2>
+<sect2 id="Image_Format_Functions_and_Macros">
+<title>Image Format Functions and Macros</title>
+<!-- .XS -->
+<!-- (SN Image Format Functions and Macros -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Applications are required to present data to the X server
+in a format that the server demands.
+To help simplify applications,
+most of the work required to convert the data is provided by Xlib
+(see sections
+<link linkend="Transferring_Images_between_Client_and_Server">8.7</link> and
+<link linkend="Manipulating_Images">16.8</link>).
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XPixmapFormatValues</primary></indexterm>
+The
+<structname>XPixmapFormatValues</structname>
+structure provides an interface to the pixmap format information
+that is returned at the time of a connection setup.
+It contains:
+<synopsis id='XPixmapFormatValues'>
+typedef struct {
+ <type>int</type> <structfield>depth</structfield>;
+ <type>int</type> <structfield>bits_per_pixel</structfield>;
+ <type>int</type> <structfield>scanline_pad</structfield>;
+} <structname>XPixmapFormatValues</structname>;
+</synopsis>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To obtain the pixmap format information for a given display, use
+<function>XListPixmapFormats</function>.
+<indexterm significance="preferred"><primary>XListPixmapFormats</primary></indexterm>
+<!-- .sM -->
+</para>
+<funcsynopsis id='XListPixmapFormats'>
+<funcprototype>
+ <funcdef>XPixmapFormatValues *<function>XListPixmapFormats</function></funcdef>
+ <paramdef>Display *<parameter>display</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'>count_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the number of pixmap formats that are supported by the display.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XListPixmapFormats</function>
+function returns an array of
+<structname>XPixmapFormatValues</structname>
+structures that describe the types of Z format images supported
+by the specified display.
+If insufficient memory is available,
+<function>XListPixmapFormats</function>
+returns NULL.
+To free the allocated storage for the
+<structname>XPixmapFormatValues</structname>
+structures, use
+<xref linkend='XFree' xrefstyle='select: title'/>.
+</para>
+<para>
+<!-- .LP -->
+The following lists the C language macros,
+their corresponding function equivalents that are for other language bindings,
+and what data they both return for the specified server and screen.
+These are often used by toolkits as well as by simple applications.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<funcsynopsis id='ImageByteOrder'>
+<funcprototype role='macro'>
+ <funcdef><function>ImageByteOrder</function></funcdef>
+ <paramdef><parameter>display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<funcsynopsis id='XImageByteOrder'>
+<funcprototype>
+ <funcdef>int <function>XImageByteOrder</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>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>ImageByteOrder</primary></indexterm>
+<indexterm significance="preferred"><primary>XImageByteOrder</primary></indexterm>
+Both specify the required byte order for images for each scanline unit in
+XY format (bitmap) or for each pixel value in
+Z format.
+The macro or function can return either
+<symbol>LSBFirst</symbol>
+or
+<symbol>MSBFirst</symbol>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<funcsynopsis id='BitmapUnit'>
+<funcprototype role='macro'>
+ <funcdef><function>XBitmapUnit</function></funcdef>
+ <paramdef><parameter>display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<funcsynopsis id='XBitmapUnit'>
+<funcprototype>
+ <funcdef>int <function>XBitmapUnit</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>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>BitmapUnit</primary></indexterm>
+<indexterm significance="preferred"><primary>XBitmapUnit</primary></indexterm>
+Both return the size of a bitmap's scanline unit in bits.
+The scanline is calculated in multiples of this value.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<funcsynopsis id='BitmapBitOrder'>
+<funcprototype role='macro'>
+ <funcdef><function>BitmapBitOrder</function></funcdef>
+ <paramdef><parameter>display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<funcsynopsis id='XBitmapBitOrder'>
+<funcprototype>
+ <funcdef>int <function>XBitmapBitOrder</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>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>BitmapBitOrder</primary></indexterm>
+<indexterm significance="preferred"><primary>XBitmapBitOrder</primary></indexterm>
+Within each bitmap unit, the left-most bit in the bitmap as displayed
+on the screen is either the least significant or most significant bit in the
+unit.
+This macro or function can return
+<symbol>LSBFirst</symbol>
+or
+<symbol>MSBFirst</symbol>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<funcsynopsis id='BitmapPad'>
+<funcprototype role='macro'>
+ <funcdef><function>BitmapPad</function></funcdef>
+ <paramdef><parameter>display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<funcsynopsis id='XBitmapPad'>
+<funcprototype>
+ <funcdef>int <function>XBitmapPad</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>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>BitmapPad</primary></indexterm>
+<indexterm significance="preferred"><primary>XBitmapPad</primary></indexterm>
+Each scanline must be padded to a multiple of bits returned
+by this macro or function.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<funcsynopsis id='DisplayHeight'>
+<funcprototype role='macro'>
+ <funcdef><function>DisplayHeight</function></funcdef>
+ <paramdef><parameter>display</parameter></paramdef>
+ <paramdef><parameter>screen_number</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<funcsynopsis id='XDisplayHeight'>
+<funcprototype>
+ <funcdef>int <function>XDisplayHeight</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 -->
+<indexterm significance="preferred"><primary>DisplayHeight</primary></indexterm>
+<indexterm significance="preferred"><primary>XDisplayHeight</primary></indexterm>
+Both return an integer that describes the height of the screen
+in pixels.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<funcsynopsis id='DisplayHeightMM'>
+<funcprototype role='macro'>
+ <funcdef><function>DisplayHeightMM</function></funcdef>
+ <paramdef><parameter>display</parameter></paramdef>
+ <paramdef><parameter>screen_number</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<funcsynopsis id='XDisplayHeightMM'>
+<funcprototype>
+ <funcdef>int <function>XDisplayHeightMM</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 -->
+<indexterm significance="preferred"><primary>DisplayHeightMM</primary></indexterm>
+<indexterm significance="preferred"><primary>XDisplayHeightMM</primary></indexterm>
+Both return the height of the specified screen in millimeters.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<funcsynopsis id='DisplayWidth'>
+<funcprototype role='macro'>
+ <funcdef><function>DisplayWidth</function></funcdef>
+ <paramdef><parameter>display</parameter></paramdef>
+ <paramdef><parameter>screen_number</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<funcsynopsis id='XDisplayWidth'>
+<funcprototype>
+ <funcdef>int <function>XDisplayWidth</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 -->
+<indexterm significance="preferred"><primary>DisplayWidth</primary></indexterm>
+<indexterm significance="preferred"><primary>XDisplayWidth</primary></indexterm>
+Both return the width of the screen in pixels.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<funcsynopsis id='DisplayWidthMM'>
+<funcprototype role='macro'>
+ <funcdef><function>DisplayWidthMM</function></funcdef>
+ <paramdef><parameter>display</parameter></paramdef>
+ <paramdef><parameter>screen_number</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<funcsynopsis id='XDisplayWidthMM'>
+<funcprototype>
+ <funcdef>int <function>XDisplayWidthMM</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 -->
+<indexterm significance="preferred"><primary>DisplayWidthMM</primary></indexterm>
+<indexterm significance="preferred"><primary>XDisplayWidthMM</primary></indexterm>
+Both return the width of the specified screen in millimeters.
+</para>
+</sect2>
+<sect2 id="Screen_Information_Macros">
+<title>Screen Information Macros</title>
+<!-- .XS -->
+<!-- (SN Screen Information Macros -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The following lists the C language macros,
+their corresponding function equivalents that are for other language bindings,
+and what data they both can return.
+These macros or functions all take a pointer to the appropriate screen
+structure.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<funcsynopsis id='BlackPixelOfScreen'>
+<funcprototype role='macro'>
+ <funcdef><function>BlackPixelOfScreen</function></funcdef>
+ <paramdef><parameter>screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<funcsynopsis id='XBlackPixelOfScreen'>
+<funcprototype>
+ <funcdef>unsigned long <function>XBlackPixelOfScreen</function></funcdef>
+ <paramdef>Screen *<parameter>screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate
+<type>Screen</type>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>BlackPixelOfScreen</primary></indexterm>
+<indexterm significance="preferred"><primary>XBlackPixelOfScreen</primary></indexterm>
+Both return the black pixel value of the specified screen.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<funcsynopsis id='WhitePixelOfScreen'>
+<funcprototype role='macro'>
+ <funcdef><function>XWhitePixelOfScreen</function></funcdef>
+ <paramdef><parameter>screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<funcsynopsis id='XWhitePixelOfScreen'>
+<funcprototype>
+ <funcdef>unsigned long <function>XWhitePixelOfScreen</function></funcdef>
+ <paramdef>Screen *<parameter>screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate
+<type>Screen</type>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>WhitePixelOfScreen</primary></indexterm>
+<indexterm significance="preferred"><primary>XWhitePixelOfScreen</primary></indexterm>
+Both return the white pixel value of the specified screen.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<funcsynopsis id='CellsOfScreen'>
+ <funcprototype role='macro'>
+ <funcdef><function>CellsOfScreen</function></funcdef>
+ <paramdef><parameter>screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<funcsynopsis id='XCellsOfScreen'>
+<funcprototype>
+ <funcdef>int <function>XCellsOfScreen</function></funcdef>
+ <paramdef>Screen *<parameter>screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate
+<type>Screen</type>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>CellsOfScreen</primary></indexterm>
+<indexterm significance="preferred"><primary>XCellsOfScreen</primary></indexterm>
+Both return the number of colormap cells in the default colormap
+of the specified screen.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<funcsynopsis id='DefaultColormapOfScreen'>
+<funcprototype role='macro'>
+ <funcdef><function>DefaultColormapOfScreen</function></funcdef>
+ <paramdef><parameter>screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<funcsynopsis id='XDefaultColormapOfScreen'>
+<funcprototype>
+ <funcdef>Colormap <function>XDefaultColormapOfScreen</function></funcdef>
+ <paramdef>Screen *<parameter>screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate
+<type>Screen</type>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>DefaultColormapOfScreen</primary></indexterm>
+<indexterm significance="preferred"><primary>XDefaultColormapOfScreen</primary></indexterm>
+Both return the default colormap of the specified screen.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<funcsynopsis id='DefaultDepthOfScreen'>
+<funcprototype role='macro'>
+ <funcdef><function>DefaultDepthOfScreen</function></funcdef>
+ <paramdef><parameter>screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<funcsynopsis id='XDefaultDepthOfScreen'>
+<funcprototype>
+ <funcdef>int <function>XDefaultDepthOfScreen</function></funcdef>
+ <paramdef>Screen *<parameter>screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate
+<type>Screen</type>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>DefaultDepthOfScreen</primary></indexterm>
+<indexterm significance="preferred"><primary>XDefaultDepthOfScreen</primary></indexterm>
+Both return the depth of the root window.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<funcsynopsis id='DefaultGCOfScreen'>
+<funcprototype role='macro'>
+ <funcdef><function>DefaultGCOfScreen</function></funcdef>
+ <paramdef><parameter>screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<funcsynopsis id='XDefaultGCOfScreen'>
+<funcprototype>
+ <funcdef>GC <function>XDefaultGCOfScreen</function></funcdef>
+ <paramdef>Screen *<parameter>screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate
+<type>Screen</type>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>DefaultGCOfScreen</primary></indexterm>
+<indexterm significance="preferred"><primary>XDefaultGCOfScreen</primary></indexterm>
+Both return a default graphics context (GC) of the specified screen,
+which has the same depth as the root window of the screen.
+The GC must never be freed.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<funcsynopsis id='DefaultVisualOfScreen'>
+<funcprototype role='macro'>
+ <funcdef><function>XDefaultVisualOfScreen</function></funcdef>
+ <paramdef><parameter>screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<funcsynopsis id='XDefaultVisualOfScreen'>
+<funcprototype>
+ <funcdef>Visual *<function>XDefaultVisualOfScreen</function></funcdef>
+ <paramdef>Screen *<parameter>screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate
+<type>Screen</type>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>DefaultVisualOfScreen</primary></indexterm>
+<indexterm significance="preferred"><primary>XDefaultVisualOfScreen</primary></indexterm>
+Both return the default visual of the specified screen.
+For information on visual types,
+see <link linkend="Visual_Types">section 3.1</link>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<funcsynopsis id='DoesBackingStore'>
+<funcprototype role='macro'>
+ <funcdef><function>DoesBackingStore</function></funcdef>
+ <paramdef><parameter>screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<funcsynopsis id='XDoesBackingStore'>
+<funcprototype>
+ <funcdef>int <function>XDoesBackingStore</function></funcdef>
+ <paramdef>Screen *<parameter>screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate
+<type>Screen</type>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>DoesBackingStore</primary></indexterm>
+<indexterm significance="preferred"><primary>XDoesBackingStore</primary></indexterm>
+Both return a value indicating whether the screen supports backing
+stores.
+The value returned can be one of
+<symbol>WhenMapped</symbol>,
+<symbol>NotUseful</symbol>,
+or
+<symbol>Always</symbol>
+(see <link linkend="Backing_Store_Attribute">section 3.2.4</link>).
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<funcsynopsis id='DoesSaveUnders'>
+<funcprototype role='macro'>
+ <funcdef><function>DoesSaveUnders</function></funcdef>
+ <paramdef><parameter>screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<funcsynopsis id='XDoesSaveUnders'>
+<funcprototype>
+ <funcdef>Bool <function>XDoesSaveUnders</function></funcdef>
+ <paramdef>Screen *<parameter>screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate
+<type>Screen</type>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>DoesSaveUnders</primary></indexterm>
+<indexterm significance="preferred"><primary>XDoesSaveUnders</primary></indexterm>
+Both return a Boolean value indicating whether the
+screen supports save unders.
+If
+<symbol>True</symbol>,
+the screen supports save unders.
+If
+<symbol>False</symbol>,
+the screen does not support save unders
+(see <link linkend="Save_Under_Flag">section 3.2.5</link>).
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<funcsynopsis id='DisplayOfScreen'>
+<funcprototype role='macro'>
+ <funcdef><function>DisplayOfScreen</function></funcdef>
+ <paramdef><parameter>screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<funcsynopsis id='XDisplayOfScreen'>
+<funcprototype>
+ <funcdef>Display *<function>XDisplayOfScreen</function></funcdef>
+ <paramdef>Screen *<parameter>screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate
+<type>Screen</type>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>DisplayOfScreen</primary></indexterm>
+<indexterm significance="preferred"><primary>XDisplayOfScreen</primary></indexterm>
+Both return the display of the specified screen.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+<indexterm significance="preferred"><primary>XScreenNumberOfScreen</primary></indexterm>
+</para>
+<funcsynopsis id='ScreenNumberOfScreen'>
+<funcprototype role='macro'>
+ <funcdef><function>ScreenNumberOfScreen</function></funcdef>
+ <paramdef><parameter>screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<funcsynopsis id='XScreenNumberOfScreen'>
+<funcprototype>
+ <funcdef>long <function>XScreenNumberOfScreen</function></funcdef>
+ <paramdef>Screen *<parameter>screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate
+<type>Screen</type>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XScreenNumberOfScreen</function>
+function returns the screen index number of the specified screen.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<funcsynopsis id='EventMaskOfScreen'>
+<funcprototype role='macro'>
+ <funcdef><function>EventMaskOfScreen</function></funcdef>
+ <paramdef><parameter>screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<funcsynopsis id='XEventMaskOfScreen'>
+<funcprototype>
+ <funcdef>long <function>XEventMaskOfScreen</function></funcdef>
+ <paramdef>Screen *<parameter>screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate
+<type>Screen</type>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>EventMaskOfScreen</primary></indexterm>
+<indexterm significance="preferred"><primary>XEventMaskOfScreen</primary></indexterm>
+Both return the event mask of the root window for the specified screen
+at connection setup time.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<funcsynopsis id='WidthOfScreen'>
+<funcprototype role='macro'>
+ <funcdef><function>WidthOfScreen</function></funcdef>
+ <paramdef><parameter>screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<funcsynopsis id='XWidthOfScreen'>
+<funcprototype>
+ <funcdef>int <function>XWidthOfScreen</function></funcdef>
+ <paramdef>Screen *<parameter>screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate
+<type>Screen</type>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>WidthOfScreen</primary></indexterm>
+<indexterm significance="preferred"><primary>XWidthOfScreen</primary></indexterm>
+Both return the width of the specified screen in pixels.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<funcsynopsis id='HeightOfScreen'>
+<funcprototype role='macro'>
+ <funcdef><function>HeightOfScreen</function></funcdef>
+ <paramdef><parameter>screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<funcsynopsis id='XHeightOfScreen'>
+<funcprototype>
+ <funcdef>int <function>XHeightOfScreen</function></funcdef>
+ <paramdef>Screen *<parameter>screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate
+<type>Screen</type>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>HeightOfScreen</primary></indexterm>
+<indexterm significance="preferred"><primary>XHeightOfScreen</primary></indexterm>
+Both return the height of the specified screen in pixels.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<funcsynopsis id='WidthMMOfScreen'>
+<funcprototype role='macro'>
+ <funcdef><function>WidthMMOfScreen</function></funcdef>
+ <paramdef><parameter>screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<funcsynopsis id='XWidthMMOfScreen'>
+<funcprototype>
+ <funcdef>int <function>XWidthMMOfScreen</function></funcdef>
+ <paramdef>Screen *<parameter>screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate
+<type>Screen</type>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>WidthMMOfScreen</primary></indexterm>
+<indexterm significance="preferred"><primary>XWidthMMOfScreen</primary></indexterm>
+Both return the width of the specified screen in millimeters.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<funcsynopsis id='HeightMMOfScreen'>
+<funcprototype role='macro'>
+ <funcdef><function>HeightMMOfScreen</function></funcdef>
+ <paramdef><parameter>screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<funcsynopsis id='XHeightMMOfScreen'>
+<funcprototype>
+ <funcdef>int <function>XHeightMMOfScreen</function></funcdef>
+ <paramdef>Screen *<parameter>screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate
+<type>Screen</type>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>HeightMMOfScreen</primary></indexterm>
+<indexterm significance="preferred"><primary>XHeightMMOfScreen</primary></indexterm>
+Both return the height of the specified screen in millimeters.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<funcsynopsis id='MaxCmapsOfScreen'>
+<funcprototype role='macro'>
+ <funcdef><function>MaxCmapsOfScreen</function></funcdef>
+ <paramdef><parameter>screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<funcsynopsis id='XMaxCmapsOfScreen'>
+<funcprototype>
+ <funcdef>int <function>XMaxCmapsOfScreen</function></funcdef>
+ <paramdef>Screen *<parameter>screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate
+<type>Screen</type>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>MaxCmapsOfScreen</primary></indexterm>
+<indexterm significance="preferred"><primary>XMaxCmapsOfScreen</primary></indexterm>
+Both return the maximum number of installed colormaps supported
+by the specified screen
+(see <link linkend="Managing_Installed_Colormaps">section 9.3</link>).
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<funcsynopsis id='MinCmapsOfScreen'>
+<funcprototype role='macro'>
+ <funcdef><function>MinCmapsOfScreen</function></funcdef>
+ <paramdef><parameter>screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<funcsynopsis id='XMinCmapsOfScreen'>
+<funcprototype>
+ <funcdef>int <function>XMinCmapsOfScreen</function></funcdef>
+ <paramdef>Screen *<parameter>screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate
+<type>Screen</type>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>MinCmapsOfScreen</primary></indexterm>
+<indexterm significance="preferred"><primary>XMinCmapsOfScreen</primary></indexterm>
+Both return the minimum number of installed colormaps supported
+by the specified screen
+(see <link linkend="Managing_Installed_Colormaps">section 9.3</link>).
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<funcsynopsis id='PlanesOfScreen'>
+<funcprototype role='macro'>
+ <funcdef><function>PlanesOfScreen</function></funcdef>
+ <paramdef><parameter>screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<funcsynopsis id='XPlanesOfScreen'>
+<funcprototype>
+ <funcdef>int <function>XPlanesOfScreen</function></funcdef>
+ <paramdef>Screen *<parameter>screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate
+<type>Screen</type>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>PlanesOfScreen</primary></indexterm>
+<indexterm significance="preferred"><primary>XPlanesOfScreen</primary></indexterm>
+Both return the depth of the root window.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<funcsynopsis id='RootWindowOfScreen'>
+<funcprototype role='macro'>
+ <funcdef><function>RootWindowOfScreen</function></funcdef>
+ <paramdef><parameter>screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<funcsynopsis id='XRootWindowOfScreen'>
+<funcprototype>
+ <funcdef>Window <function>XRootWindowOfScreen</function></funcdef>
+ <paramdef>Screen *<parameter>screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate
+<type>Screen</type>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>RootWindowOfScreen</primary></indexterm>
+<indexterm significance="preferred"><primary>XRootWindowOfScreen</primary></indexterm>
+Both return the root window of the specified screen.
+</para>
+</sect2>
+</sect1>
+<sect1 id="Generating_a_NoOperation_Protocol_Request">
+<title>Generating a NoOperation Protocol Request</title>
+<!-- .XS -->
+<!-- (SN Generating a NoOperation Protocol Request -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To execute a
+<systemitem>NoOperation</systemitem>
+protocol request, use
+<xref linkend='XNoOp' xrefstyle='select: title'/>.
+<indexterm significance="preferred"><primary>XNoOp</primary></indexterm>
+<!-- .sM -->
+</para>
+<funcsynopsis id='XNoOp'>
+<funcprototype>
+ <funcdef><function>XNoOp</function></funcdef>
+ <paramdef>Display *<parameter>display</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>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XNoOp' xrefstyle='select: title'/>
+function sends a
+<systemitem>NoOperation</systemitem>
+protocol request to the X server,
+thereby exercising the connection.
+</para>
+</sect1>
+<sect1 id="Freeing_Client_Created_Data">
+<title>Freeing Client-Created Data</title>
+<!-- .XS -->
+<!-- (SN Freeing Client-Created Data -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To free in-memory data that was created by an Xlib function, use
+<xref linkend='XFree' xrefstyle='select: title'/>.
+<indexterm significance="preferred"><primary>XFree</primary></indexterm>
+<!-- .sM -->
+</para>
+<funcsynopsis id='XFree'>
+<funcprototype>
+ <funcdef><function>XFree</function></funcdef>
+ <paramdef>void *<parameter>data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the data that is to be freed.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XFree' xrefstyle='select: title'/>
+function is a general-purpose Xlib routine that frees the specified data.
+You must use it to free any objects that were allocated by Xlib,
+unless an alternate function is explicitly specified for the object.
+A NULL pointer cannot be passed to this function.
+</para>
+</sect1>
+<sect1 id="Closing_the_Display">
+<title>Closing the Display</title>
+<!-- .XS -->
+<!-- (SN Closing the Display -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To close a display or disconnect from the X server, use
+<function>XCloseDisplay</function>.
+<indexterm significance="preferred"><primary>XCloseDisplay</primary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+<!-- .sM -->
+</para>
+<funcsynopsis id='xclosedisplay'>
+<funcprototype>
+ <funcdef><function>XCloseDisplay</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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XCloseDisplay</function>
+function closes the connection to the X server for the display specified in the
+<type>Display</type>
+structure and destroys all windows, resource IDs
+(<type>Window</type>,
+<type>Font</type>,
+<type>Pixmap</type>,
+<type>Colormap</type>,
+<type>Cursor</type>,
+and
+<type>GContext</type>),
+or other resources that the client has created
+on this display, unless the close-down mode of the client has been changed
+(see
+<xref linkend='XSetCloseDownMode' xrefstyle='select: title'/>).
+Therefore, these windows, resource IDs, and other resources should never be
+referenced again or an error will be generated.
+Before exiting, you should call
+<function>XCloseDisplay</function>
+explicitly so that any pending errors are reported as
+<function>XCloseDisplay</function>
+performs a final
+<xref linkend='XSync' xrefstyle='select: title'/>
+operation.
+<indexterm><primary>Resource IDs</primary></indexterm>
+<indexterm><primary>XCloseDisplay</primary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+<function>XCloseDisplay</function>
+can generate a
+<errorname>BadGC</errorname>
+error.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+Xlib provides a function to permit the resources owned by a client
+to survive after the client's connection is closed.
+To change a client's close-down mode, use
+<xref linkend='XSetCloseDownMode' xrefstyle='select: title'/>.
+<indexterm significance="preferred"><primary>XSetCloseDownMode</primary></indexterm>
+<!-- .sM -->
+</para>
+<funcsynopsis id='XSetCloseDownMode'>
+<funcprototype>
+ <funcdef><function>XSetCloseDownMode</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>int <parameter>close_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'>close_mode</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the client close-down mode.
+You can pass
+<symbol>DestroyAll</symbol>,
+<symbol>RetainPermanent</symbol>,
+or
+<symbol>RetainTemporary</symbol>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XSetCloseDownMode' xrefstyle='select: title'/> function
+defines what will happen to the client's resources at connection close.
+A connection starts in
+<symbol>DestroyAll</symbol>
+mode.
+For information on what happens to the client's resources when the
+close_mode argument is
+<symbol>RetainPermanent</symbol>
+or
+<symbol>RetainTemporary</symbol>,
+see <link linkend='Using_X_Server_Connection_Close_Operations'>section 2.6</link>.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XSetCloseDownMode' xrefstyle='select: title'/>
+can generate a
+<errorname>BadValue</errorname>
+error.
+</para>
+</sect1>
+<sect1 id='Using_X_Server_Connection_Close_Operations'>
+<title>Using X Server Connection Close Operations</title>
+<!-- .XS -->
+<!-- (SN Using X Server Connection Close Operations -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+When the X server's connection to a client is closed
+either by an explicit call to
+<function>XCloseDisplay</function>
+or by a process that exits, the X server performs the following
+automatic operations:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+It disowns all selections owned by the client
+(see
+<xref linkend='XSetSelectionOwner' xrefstyle='select: title'/>).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It performs an
+<xref linkend='XUngrabPointer' xrefstyle='select: title'/>
+and
+<xref linkend='XUngrabKeyboard' xrefstyle='select: title'/>
+if the client has actively grabbed the pointer
+or the keyboard.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It performs an
+<xref linkend='XUngrabServer' xrefstyle='select: title'/>
+if the client has grabbed the server.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It releases all passive grabs made by the client.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It marks all resources (including colormap entries) allocated
+by the client either as permanent or temporary,
+depending on whether the close-down mode is
+<symbol>RetainPermanent</symbol>
+or
+<symbol>RetainTemporary</symbol>.
+However, this does not prevent other client applications from explicitly
+destroying the resources (see
+<xref linkend='XSetCloseDownMode' xrefstyle='select: title'/>).
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+When the close-down mode is
+<symbol>DestroyAll</symbol>,
+the X server destroys all of a client's resources as follows:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+It examines each window in the client's save-set to determine if it is an inferior
+(subwindow) of a window created by the client.
+(The save-set is a list of other clients' windows
+that are referred to as save-set windows.)
+If so, the X server reparents the save-set window to the closest ancestor so
+that the save-set window is not an inferior of a window created by the client.
+The reparenting leaves unchanged the absolute coordinates (with respect to
+the root window) of the upper-left outer corner of the save-set
+window.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It performs a
+<systemitem>MapWindow</systemitem>
+request on the save-set window if the save-set window is unmapped.
+The X server does this even if the save-set window was not an inferior of
+a window created by the client.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It destroys all windows created by the client.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It performs the appropriate free request on each nonwindow resource created by
+the client in the server (for example,
+<type>Font</type>,
+<type>Pixmap</type>,
+<type>Cursor</type>,
+<type>Colormap</type>,
+and
+<type>GContext</type>).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It frees all colors and colormap entries allocated by a client application.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+Additional processing occurs when the last connection to the X server closes.
+An X server goes through a cycle of having no connections and having some
+connections.
+When the last connection to the X server closes as a result of a connection
+closing with the close_mode of
+<symbol>DestroyAll</symbol>,
+the X server does the following:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+It resets its state as if it had just been
+started.
+The X server begins by destroying all lingering resources from
+clients that have terminated in
+<symbol>RetainPermanent</symbol>
+or
+<symbol>RetainTemporary</symbol>
+mode.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It deletes all but the predefined atom identifiers.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It deletes all properties on all root windows
+(see <link linkend="Properties_and_Atoms">section 4.3</link>).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It resets all device maps and attributes
+(for example, key click, bell volume, and acceleration)
+as well as the access control list.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It restores the standard root tiles and cursors.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It restores the default font path.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It restores the input focus to state
+<symbol>PointerRoot</symbol>.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+However, the X server does not reset if you close a connection with a close-down
+mode set to
+<symbol>RetainPermanent</symbol>
+or
+<symbol>RetainTemporary</symbol>.
+</para>
+</sect1>
+<sect1 id="Using_Xlib_with_Threads">
+<title>Using Xlib with Threads</title>
+<!-- .XS -->
+<!-- (SN Using Xlib with Threads -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+On systems that have threads, support may be provided to permit
+multiple threads to use Xlib concurrently.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To initialize support for concurrent threads, use
+<function>XInitThreads</function>.
+<indexterm significance="preferred"><primary>XInitThreads</primary></indexterm>
+<!-- .sM -->
+</para>
+<funcsynopsis id='XInitThreads'>
+<funcprototype>
+ <funcdef>Status <function>XInitThreads</function></funcdef>
+ <void />
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XInitThreads</function>
+function initializes Xlib support for concurrent threads.
+This function must be the first Xlib function a
+multi-threaded program calls, and it must complete
+before any other Xlib call is made.
+This function returns a nonzero status if initialization was
+successful; otherwise, it returns zero.
+On systems that do not support threads, this function always returns zero.
+</para>
+<para>
+<!-- .LP -->
+It is only necessary to call this function if multiple threads
+might use Xlib concurrently. If all calls to Xlib functions
+are protected by some other access mechanism (for example,
+a mutual exclusion lock in a toolkit or through explicit client
+programming), Xlib thread initialization is not required.
+It is recommended that single-threaded programs not call this function.
+
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To lock a display across several Xlib calls, use
+<function>XLockDisplay</function>.
+<indexterm significance="preferred"><primary>XLockDisplay</primary></indexterm>
+<!-- .sM -->
+</para>
+<funcsynopsis id='xlockdisplay'>
+<funcprototype>
+ <funcdef><function>XLockDisplay</function></funcdef>
+ <paramdef>Display *<parameter>display</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>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XLockDisplay</function>
+function locks out all other threads from using the specified display.
+Other threads attempting to use the display will block until
+the display is unlocked by this thread.
+Nested calls to
+<function>XLockDisplay</function>
+work correctly; the display will not actually be unlocked until
+<xref linkend='XUnlockDisplay' xrefstyle='select: title'/>
+has been called the same number of times as
+<function>XLockDisplay</function>.
+This function has no effect unless Xlib was successfully initialized
+for threads using
+<function>XInitThreads</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To unlock a display, use
+<xref linkend='XUnlockDisplay' xrefstyle='select: title'/>.
+<indexterm significance="preferred"><primary>XUnlockDisplay</primary></indexterm>
+<!-- .sM -->
+</para>
+<funcsynopsis id='XUnlockDisplay'>
+<funcprototype>
+ <funcdef><function>XUnlockDisplay</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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XUnlockDisplay' xrefstyle='select: title'/>
+function allows other threads to use the specified display again.
+Any threads that have blocked on the display are allowed to continue.
+Nested locking works correctly; if
+<function>XLockDisplay</function>
+has been called multiple times by a thread, then
+<xref linkend='XUnlockDisplay' xrefstyle='select: title'/>
+must be called an equal number of times before the display is
+actually unlocked.
+This function has no effect unless Xlib was successfully initialized
+for threads using
+<function>XInitThreads</function>.
+</para>
+</sect1>
+<sect1 id="Using_Internal_Connections">
+<title>Using Internal Connections</title>
+<!-- .XS -->
+<!-- (SN Using Internal Connections -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+In addition to the connection to the X server, an Xlib implementation
+may require connections to other kinds of servers (for example, to
+input method servers as described in
+<link linkend='Locales_and_Internationalized_Text_Functions'>chapter 13</link>).
+Toolkits and clients
+that use multiple displays, or that use displays in combination with
+other inputs, need to obtain these additional connections to correctly
+block until input is available and need to process that input
+when it is available. Simple clients that use a single display and
+block for input in an Xlib event function do not need to use these
+facilities.
+</para>
+<para>
+<!-- .LP -->
+To track internal connections for a display, use
+<xref linkend='XAddConnectionWatch' xrefstyle='select: title'/>.
+</para>
+<funcsynopsis id='xconnectionwatch'>
+<funcprototype>
+ <funcdef>typedef void (*XConnectionWatchProc)</funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>XPointer <parameter>client_data</parameter></paramdef>
+ <paramdef>int <parameter>fd</parameter></paramdef>
+ <paramdef>Bool <parameter>opening</parameter></paramdef>
+ <paramdef>XPointer *<parameter>watch_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<funcsynopsis id='XAddConnectionWatch'>
+<funcprototype>
+ <funcdef>Status <function>XAddConnectionWatch</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>XConnectionWatchProc <parameter>procedure</parameter></paramdef>
+ <paramdef>XPointer <parameter>client_data</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'>procedure</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure to be called.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the additional client data.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XAddConnectionWatch' xrefstyle='select: title'/>
+function registers a procedure to be called each time Xlib opens or closes an
+internal connection for the specified display. The procedure is passed the
+display, the specified client_data, the file descriptor for the connection,
+a Boolean indicating whether the connection is being opened or closed, and a
+pointer to a location for private watch data. If opening is
+<symbol>True</symbol>,
+the procedure can store a pointer to private data in the location pointed
+to by watch_data;
+when the procedure is later called for this same connection and opening is
+<symbol>False</symbol>,
+the location pointed to by watch_data will hold this same private data pointer.
+</para>
+<para>
+<!-- .LP -->
+This function can be called at any time after a display is opened.
+If internal connections already exist, the registered procedure will
+immediately be called for each of them, before
+<xref linkend='XAddConnectionWatch' xrefstyle='select: title'/>
+returns.
+<xref linkend='XAddConnectionWatch' xrefstyle='select: title'/>
+returns a nonzero status if the procedure is successfully registered;
+otherwise, it returns zero.
+</para>
+<para>
+<!-- .LP -->
+The registered procedure should not call any Xlib functions.
+If the procedure directly or indirectly causes the state of internal
+connections or watch procedures to change, the result is not defined.
+If Xlib has been initialized for threads, the procedure is called with
+the display locked and the result of a call by the procedure to any
+Xlib function that locks the display is not defined unless the executing
+thread has externally locked the display using
+<function>XLockDisplay</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To stop tracking internal connections for a display, use
+<function>XRemoveConnectionWatch</function>.
+<indexterm significance="preferred"><primary>XRemoveConnectionWatch</primary></indexterm>
+<!-- .sM -->
+</para>
+<para>
+</para>
+<funcsynopsis id='xremoveconnectionwatch'>
+<funcprototype>
+ <funcdef>Status <function>XRemoveConnectionWatch</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>XConnectionWatchProc <parameter>procedure</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'>procedure</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure to be called.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the additional client data.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XRemoveConnectionWatch</function>
+function removes a previously registered connection watch procedure.
+The client_data must match the client_data used when the procedure
+was initially registered.
+
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To process input on an internal connection, use
+<xref linkend='XProcessInternalConnection' xrefstyle='select: title'/>.
+<indexterm significance="preferred"><primary>XProcessInternalConnection</primary></indexterm>
+<!-- .sM -->
+</para>
+<para>
+</para>
+<funcsynopsis id='XProcessInternalConnection'>
+<funcprototype>
+ <funcdef>void <function>XProcessInternalConnection</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>int <parameter>fd</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>fd</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the file descriptor.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XProcessInternalConnection' xrefstyle='select: title'/>
+function processes input available on an internal connection.
+This function should be called for an internal connection only
+after an operating system facility (for example,
+<function>select</function>
+or
+<function>poll</function>)
+has indicated that input is available; otherwise,
+the effect is not defined.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain all of the current internal connections for a display, use
+<xref linkend='XInternalConnectionNumbers' xrefstyle='select: title'/>.
+<indexterm significance="preferred"><primary>XInternalConnectionNumbers</primary></indexterm>
+<!-- .sM -->
+</para>
+<para>
+</para>
+<funcsynopsis id='XInternalConnectionNumbers'>
+<funcprototype>
+ <funcdef>Status <function>XInternalConnectionNumbers</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>int ** <parameter>fd</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'>fd_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the file descriptors.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>count_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the number of file descriptors.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XInternalConnectionNumbers' xrefstyle='select: title'/>
+function returns a list of the file descriptors for all internal
+connections currently open for the specified display.
+When the allocated list is no longer needed,
+free it by using
+<xref linkend='XFree' xrefstyle='select: title'/>.
+This functions returns a nonzero status if the list is successfully allocated;
+otherwise, it returns zero.
+</para>
+</sect1>
+</chapter>
Index: create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/libX11/CH03.xml
===================================================================
--- create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/libX11/CH03.xml (nonexistent)
+++ create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/libX11/CH03.xml (revision 5)
@@ -0,0 +1,4179 @@
+<?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 <link linkend='Display_Macros'>2.2.1</link>
+and <link linkend="Determining_the_Appropriate_Visual_Type">16.7</link>).
+</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 <link linkend="Determining_the_Appropriate_Visual_Type">section 16.7</link>)
+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
+<xref linkend='XVisualIDFromVisual' xrefstyle='select: title'/>.
+<indexterm significance="preferred"><primary>XVisualIDFromVisual</primary></indexterm>
+</para>
+<!-- .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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XVisualIDFromVisual' xrefstyle='select: title'/>
+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 <link linkend="Properties_and_Atoms">section 4.3</link>).
+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 <link linkend="Properties_and_Atoms">section 4.3</link>).
+</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
+<xref linkend='XMapWindow' xrefstyle='select: title'/>),
+<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
+<xref linkend='XCreateWindow' xrefstyle='select: title'/>
+and
+<xref linkend='XChangeWindowAttributes' xrefstyle='select: title'/>,
+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<<0)
+#define CWBackPixel (1L<<1)
+#define CWBorderPixmap (1L<<2)
+#define CWBorderPixel (1L<<3)
+#define CWBitGravity (1L<<4)
+#define CWWinGravity (1L<<5)
+#define CWBackingStore (1L<<6)
+#define CWBackingPlanes (1L<<7)
+#define CWBackingPixel (1L<<8)
+#define CWOverrideRedirect (1L<<9)
+#define CWSaveUnder (1L<<10)
+#define CWEventMask (1L<<11)
+#define CWDontPropagate (1L<<12)
+#define CWColormap (1L<<13)
+#define CWCursor (1L<<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 frame='topbot'>
+ <?dbfo keep-together="auto" ?>
+ <tgroup cols='4' align='left' colsep='0' rowsep='0'>
+ <colspec colname='c1' colwidth='1.0*'/>
+ <colspec colname='c2' colwidth='1.0*'/>
+ <colspec colname='c3' colwidth='1.0*'/>
+ <colspec colname='c4' colwidth='1.0*'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Attribute</entry>
+ <entry>Default</entry>
+ <entry>InputOutput</entry>
+ <entry>InputOnly</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 <link linkend="Exposure_Events">section 10.9</link>).
+</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 frame='topbot'>
+ <?dbfo keep-together="always" ?>
+ <tgroup cols='2' align='left' colsep='0' rowsep='0'>
+ <colspec colname='c1' colwidth='1.0*'/>
+ <colspec colname='c2' colwidth='2.0*'/>
+ <thead>
+ <row rowsep='1'>
+ <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 <link linkend="GravityNotify_Events">section 10.10.5</link>).
+</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 (−x, −y), and for
+win-gravity the change in position of a child when its parent is so resized is
+(−x, −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 <link linkend='Inter_Client_Communication_Functions'>chapter 14</link>).
+</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
+<xref linkend='XInstallColormap' xrefstyle='select: title'/>.
+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
+<xref linkend='XFreeCursor' xrefstyle='select: title'/>,
+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 <link linkend='Inter_Client_Communication_Functions'>chapter 14</link>).
+</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 <link linkend='Inter_Client_Communication_Functions'>chapter 14</link> and
+the <citetitle>Inter-Client Communication Conventions Manual</citetitle>.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XCreateWindow' xrefstyle='select: title'/>
+is the more general function that allows you to set specific window attributes
+when you create a window.
+<xref linkend='XCreateSimpleWindow' xrefstyle='select: title'/>
+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
+<xref linkend='XCreateWindow' xrefstyle='select: title'/>.
+</para>
+<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>int <parameter>x</parameter></paramdef>
+ <paramdef>int <parameter>y</parameter></paramdef>
+ <paramdef>unsigned int <parameter>width</parameter></paramdef>
+ <paramdef>unsigned int <parameter>height</parameter></paramdef>
+ <paramdef>unsigned int <parameter>border_width</parameter></paramdef>
+ <paramdef>int <parameter>depth</parameter></paramdef>
+ <paramdef>unsigned int <parameter>class</parameter></paramdef>
+ <paramdef>Visual *<parameter>visual</parameter></paramdef>
+ <paramdef>unsigned long <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.
+ </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, 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'>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, which are the created window's inside
+dimensions and do not include the created window's borders.
+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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XCreateWindow' xrefstyle='select: title'/>
+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
+<xref linkend='XMapWindow' xrefstyle='select: title'/>.
+The new window initially uses the same cursor as
+its parent.
+A new cursor can be defined for the new window by calling
+<xref linkend='XDefineCursor' xrefstyle='select: title'/>.
+<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 -->
+<xref linkend='XCreateWindow' xrefstyle='select: title'/>
+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
+<xref linkend='XCreateSimpleWindow' xrefstyle='select: title'/>.
+</para>
+<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>int <parameter>x</parameter></paramdef>
+ <paramdef>int <parameter>y</parameter></paramdef>
+ <paramdef>unsigned int <parameter>width</parameter></paramdef>
+ <paramdef>unsigned int <parameter>height</parameter></paramdef>
+ <paramdef>unsigned int <parameter>border_width</parameter></paramdef>
+ <paramdef>unsigned long <parameter>border</parameter></paramdef>
+ <paramdef>unsigned long <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.
+ </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, 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'>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, which are the created window's inside
+dimensions and do not include the created window's borders.
+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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XCreateSimpleWindow' xrefstyle='select: title'/>
+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.
+<xref linkend='XCreateSimpleWindow' xrefstyle='select: title'/>
+inherits its depth, class, and visual from its parent.
+All other window attributes, except background and border,
+have their default values.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XCreateSimpleWindow' xrefstyle='select: title'/>
+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
+<xref linkend='XDestroyWindow' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XDestroyWindow' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XDestroyWindow' xrefstyle='select: title'/>
+can generate a
+<errorname>BadWindow</errorname>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To destroy all subwindows of a specified window, use
+<xref linkend='XDestroySubwindows' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XDestroySubwindows' xrefstyle='select: title'/>
+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,
+<xref linkend='XDestroySubwindows' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XDestroySubwindows' xrefstyle='select: title'/>
+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
+<xref linkend='XMapWindow' xrefstyle='select: title'/>
+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 <link linkend="Override_Redirect_Flag">sections 3.2.8</link>
+and <link linkend='Window_State_Change_Events'>10.10</link>.
+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
+<xref linkend='XMapWindow' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XMapWindow' xrefstyle='select: title'/>
+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
+<xref linkend='XMapWindow' xrefstyle='select: title'/>
+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,
+<xref linkend='XMapWindow' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XMapWindow' xrefstyle='select: title'/>
+can generate a
+<errorname>BadWindow</errorname>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To map and raise a window, use
+<xref linkend='XMapRaised' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XMapRaised' xrefstyle='select: title'/>
+function
+essentially is similar to
+<xref linkend='XMapWindow' xrefstyle='select: title'/>
+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
+<xref linkend='XMapWindow' xrefstyle='select: title'/>.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XMapRaised' xrefstyle='select: title'/>
+can generate multiple
+<errorname>BadWindow</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To map all subwindows for a specified window, use
+<xref linkend='XMapSubwindows' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XMapSubwindows' xrefstyle='select: title'/>
+<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 -->
+<xref linkend='XMapSubwindows' xrefstyle='select: title'/>
+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
+<xref linkend='XUnmapWindow' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XUnmapWindow' xrefstyle='select: title'/>
+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,
+<xref linkend='XUnmapWindow' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XUnmapWindow' xrefstyle='select: title'/>
+can generate a
+<errorname>BadWindow</errorname>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To unmap all subwindows for a specified window, use
+<xref linkend='XUnmapSubwindows' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XUnmapSubwindows' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XUnmapSubwindows' xrefstyle='select: title'/>
+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
+<xref linkend='XConfigureWindow' xrefstyle='select: title'/>.
+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<<0)
+#define CWY (1<<1)
+#define CWWidth (1<<2)
+#define CWHeight (1<<3)
+#define CWBorderWidth (1<<4)
+#define CWSibling (1<<5)
+#define CWStackMode (1<<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 <link linkend="Gravity_Attributes">section 3.2.3</link>).
+</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 frame="none">
+ <?dbfo keep-together="always" ?>
+ <tgroup cols='2' align='left' colsep='0' rowsep='0'>
+ <colspec colname='c1' colwidth='1.0*'/>
+ <colspec colname='c2' colwidth='3.0*'/>
+ <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 frame="none">
+ <?dbfo keep-together="always" ?>
+ <tgroup cols='2' align='left' colsep='0' rowsep='0'>
+ <colspec colname='c1' colwidth='1.0*'/>
+ <colspec colname='c2' colwidth='3.0*'/>
+ <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><symbol>BottomIf</symbol></entry>
+ <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
+<xref linkend='XConfigureWindow' xrefstyle='select: title'/>.
+</para>
+<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>unsigned int <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 to be reconfigured.
+ </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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XConfigureWindow' xrefstyle='select: title'/>
+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
+<xref linkend='XConfigureWindow' xrefstyle='select: title'/>),
+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 -->
+<xref linkend='XConfigureWindow' xrefstyle='select: title'/>
+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
+<xref linkend='XMoveWindow' xrefstyle='select: title'/>.
+</para>
+<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>int <parameter>x</parameter></paramdef>
+ <paramdef>int <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 to be moved.
+ </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, 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>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XMoveWindow' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XMoveWindow' xrefstyle='select: title'/>
+can generate a
+<errorname>BadWindow</errorname>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To change a window's size without changing the upper-left coordinate, use
+<xref linkend='XResizeWindow' xrefstyle='select: title'/>.
+</para>
+<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>unsigned int <parameter>width</parameter></paramdef>
+ <paramdef>unsigned int <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.
+ </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, which are the interior dimensions of the
+window after the call completes.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XResizeWindow' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XResizeWindow' xrefstyle='select: title'/>
+can generate
+<errorname>BadValue</errorname>
+and
+<errorname>BadWindow</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To change the size and location of a window, use
+<xref linkend='XMoveResizeWindow' xrefstyle='select: title'/>.
+</para>
+<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>int <parameter>x</parameter></paramdef>
+ <paramdef>int <parameter>y</parameter></paramdef>
+ <paramdef>unsigned int <parameter>width</parameter></paramdef>
+ <paramdef>unsigned int <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 to be reconfigured.
+ </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, which define the new position of the
+window relative to its parent.
+ </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, which define the interior size of the window.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XMoveResizeWindow' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XMoveResizeWindow' xrefstyle='select: title'/>
+can generate
+<errorname>BadValue</errorname>
+and
+<errorname>BadWindow</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To change the border width of a given window, use
+<xref linkend='XSetWindowBorderWidth' xrefstyle='select: title'/>.
+</para>
+<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>unsigned int <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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XSetWindowBorderWidth' xrefstyle='select: title'/>
+function sets the specified window's border width to the specified width.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XSetWindowBorderWidth' xrefstyle='select: title'/>
+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
+<xref linkend='XRaiseWindow' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XRaiseWindow' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XRaiseWindow' xrefstyle='select: title'/>
+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
+<xref linkend='XLowerWindow' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XLowerWindow' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XLowerWindow' xrefstyle='select: title'/>
+can generate a
+<errorname>BadWindow</errorname>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To circulate a subwindow up or down, use
+<xref linkend='XCirculateSubwindows' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XCirculateSubwindows' xrefstyle='select: title'/>
+function circulates children of the specified window in the specified
+direction.
+If you specify
+<symbol>RaiseLowest</symbol>,
+<xref linkend='XCirculateSubwindows' xrefstyle='select: title'/>
+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>,
+<xref linkend='XCirculateSubwindows' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XCirculateSubwindows' xrefstyle='select: title'/>
+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
+<xref linkend='XCirculateSubwindowsUp' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XCirculateSubwindowsUp' xrefstyle='select: title'/>
+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
+<xref linkend='XCirculateSubwindows' xrefstyle='select: title'/>
+with
+<symbol>RaiseLowest</symbol>
+specified.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XCirculateSubwindowsUp' xrefstyle='select: title'/>
+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
+<xref linkend='XCirculateSubwindowsDown' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XCirculateSubwindowsDown' xrefstyle='select: title'/>
+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
+<xref linkend='XCirculateSubwindows' xrefstyle='select: title'/>
+with
+<symbol>LowerHighest</symbol>
+specified.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XCirculateSubwindowsDown' xrefstyle='select: title'/>
+can generate a
+<errorname>BadWindow</errorname>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To restack a set of windows from top to bottom, use
+<xref linkend='XRestackWindows' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XRestackWindows' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XRestackWindows' xrefstyle='select: title'/>
+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.
+<xref linkend='XChangeWindowAttributes' xrefstyle='select: title'/>
+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
+<xref linkend='XChangeWindowAttributes' xrefstyle='select: title'/>.
+</para>
+<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>unsigned long <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
+<xref linkend='XCreateWindow' xrefstyle='select: title'/>.
+ </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 <link linkend="Window_Attributes">section 3.2</link>).
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+Depending on the valuemask,
+the
+<xref linkend='XChangeWindowAttributes' xrefstyle='select: title'/>
+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
+<xref linkend='XClearWindow' xrefstyle='select: title'/>.
+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
+<xref linkend='XInstallColormap' xrefstyle='select: title'/>).
+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 -->
+<xref linkend='XChangeWindowAttributes' xrefstyle='select: title'/>
+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
+<xref linkend='XSetWindowBackground' xrefstyle='select: title'/>.
+</para>
+<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>unsigned long <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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XSetWindowBackground' xrefstyle='select: title'/>
+function sets the background of the window to the specified pixel value.
+Changing the background does not cause the window contents to be changed.
+<xref linkend='XSetWindowBackground' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XSetWindowBackground' xrefstyle='select: title'/>
+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
+<xref linkend='XSetWindowBackgroundPixmap' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm><primary>Resource IDs</primary><secondary>freeing</secondary></indexterm>
+<indexterm><primary>Freeing</primary><secondary>resources</secondary></indexterm>
+The
+<xref linkend='XSetWindowBackgroundPixmap' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XSetWindowBackgroundPixmap' xrefstyle='select: title'/>
+can generate
+<errorname>BadMatch</errorname>,
+<errorname>BadPixmap</errorname>,
+and
+<errorname>BadWindow</errorname>
+errors.
+<!-- .NT Note -->
+<xref linkend='XSetWindowBackground' xrefstyle='select: title'/>
+and
+<xref linkend='XSetWindowBackgroundPixmap' xrefstyle='select: title'/>
+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
+<xref linkend='XSetWindowBorder' xrefstyle='select: title'/>.
+</para>
+<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>unsigned long <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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XSetWindowBorder' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XSetWindowBorder' xrefstyle='select: title'/>
+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
+<xref linkend='XSetWindowBorderPixmap' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XSetWindowBorderPixmap' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XSetWindowBorderPixmap' xrefstyle='select: title'/>
+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
+<xref linkend='XSetWindowColormap' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XSetWindowColormap' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XSetWindowColormap' xrefstyle='select: title'/>
+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
+<xref linkend='XDefineCursor' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .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
+<xref linkend='XUndefineCursor' xrefstyle='select: title'/>.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XDefineCursor' xrefstyle='select: title'/>
+can generate
+<errorname>BadCursor</errorname>
+and
+<errorname>BadWindow</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To undefine the cursor in a given window, use
+<xref linkend='XUndefineCursor' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XUndefineCursor' xrefstyle='select: title'/>
+function undoes the effect of a previous
+<xref linkend='XDefineCursor' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XUndefineCursor' xrefstyle='select: title'/>
+can generate a
+<errorname>BadWindow</errorname>
+error.
+<!-- .bp -->
+
+</para>
+</sect1>
+</chapter>
Index: create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/libX11/CH04.xml
===================================================================
--- create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/libX11/CH04.xml (nonexistent)
+++ create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/libX11/CH04.xml (revision 5)
@@ -0,0 +1,2507 @@
+<?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_Information_Functions'>
+<title>Window Information Functions</title>
+
+<para>
+After you connect the display to the X server and create a window, you can use the Xlib window
+information functions to:
+</para>
+<itemizedlist>
+ <listitem><para>Obtain information about a window</para></listitem>
+ <listitem><para>Translate screen coordinates</para></listitem>
+ <listitem><para>Manipulate property lists</para></listitem>
+ <listitem><para>Obtain and change window properties</para></listitem>
+ <listitem><para>Manipulate selections</para></listitem>
+</itemizedlist>
+
+<sect1 id="Obtaining_Window_Information">
+<title>Obtaining Window Information</title>
+<!-- .XS -->
+<!-- (SN Obtaining Window Information -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to obtain information about
+the window tree, the window's current attributes,
+the window's current geometry, or the current pointer coordinates.
+Because they are most frequently used by window managers,
+these functions all return a status to indicate whether the window still
+exists.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain the parent, a list of children, and number of children for
+a given window, use
+<xref linkend='XQueryTree' xrefstyle='select: title'/>.
+</para>
+<indexterm><primary>Child Window</primary></indexterm>
+<indexterm><primary>Parent Window</primary></indexterm>
+<indexterm significance="preferred"><primary>XQueryTree</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='XQueryTree'>
+<funcprototype>
+ <funcdef>Status <function>XQueryTree</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>Window <parameter>w</parameter></paramdef>
+ <paramdef>Window *<parameter>root_return</parameter></paramdef>
+ <paramdef>Window *<parameter>parent_return</parameter></paramdef>
+ <paramdef>Window **<parameter>children_return</parameter></paramdef>
+ <paramdef>unsigned int *<parameter>nchildren_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 whose list of children, root, parent, and number of
+children you want to obtain.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>root_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the root window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>parent_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the parent window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>children_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the list of children.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>nchildren_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the number of children.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XQueryTree' xrefstyle='select: title'/>
+function returns the root ID, the parent window ID,
+a pointer to the list of children windows
+(NULL when there are no children),
+and the number of children in the list for the specified window.
+The children are listed in current stacking order, from bottom-most
+(first) to top-most (last).
+<xref linkend='XQueryTree' xrefstyle='select: title'/>
+returns zero if it fails and nonzero if it succeeds.
+To free a non-NULL children list when it is no longer needed, use
+<xref linkend='XFree' xrefstyle='select: title'/>.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XQueryTree' xrefstyle='select: title'/>
+can generate a
+<errorname>BadWindow</errorname>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain the current attributes of a given window, use
+<xref linkend='XGetWindowAttributes' xrefstyle='select: title'/>.
+</para>
+<indexterm significance="preferred"><primary>XGetWindowAttributes</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='XGetWindowAttributes'>
+<funcprototype>
+ <funcdef>Status <function>XGetWindowAttributes</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>Window <parameter>w</parameter></paramdef>
+ <paramdef>XWindowAttributes *<parameter>window_attributes_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 whose current attributes you want to obtain.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>window_attributes_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the specified window's attributes in the
+<structname>XWindowAttributes</structname>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XGetWindowAttributes' xrefstyle='select: title'/>
+function returns the current attributes for the specified window to an
+<structname>XWindowAttributes</structname>
+structure.
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XWindowAttributes</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+ int x, y; /* location of window */
+ int width, height; /* width and height of window */
+ int border_width; /* border width of window */
+ int depth; /* depth of window */
+ Visual *visual; /* the associated visual structure */
+ Window root; /* root of screen containing window */
+ int class; /* InputOutput, InputOnly*/
+ int bit_gravity; /* one of the 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 be used when restoring planes */
+ Bool save_under; /* boolean, should bits under be saved? */
+ Colormap colormap; /* color map to be associated with window */
+ Bool map_installed; /* boolean, is color map currently installed*/
+ int map_state; /* IsUnmapped, IsUnviewable, IsViewable */
+ long all_event_masks; /* set of events all people have interest in*/
+ long your_event_mask; /* my event mask */
+ long do_not_propagate_mask; /* set of events that should not propagate */
+ Bool override_redirect; /* boolean value for override-redirect */
+ Screen *screen; /* back pointer to correct screen */
+} XWindowAttributes;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The x and y members are set to the upper-left outer
+corner relative to the parent window's origin.
+The width and height members are set to the inside size of the window,
+not including the border.
+The border_width member is set to the window's border width in pixels.
+The depth member is set to the depth of the window
+(that is, bits per pixel for the object).
+The visual member is a pointer to the screen's associated
+<structname>Visual</structname>
+structure.
+The root member is set to the root window of the screen containing the window.
+The class member is set to the window's class and can be either
+<symbol>InputOutput</symbol>
+or
+<symbol>InputOnly</symbol>.
+</para>
+<para>
+<!-- .LP -->
+The bit_gravity member is set to the window's bit gravity
+and can be one of the following:
+ <simplelist type="vert" columns="2">
+ <member><symbol>ForgetGravity</symbol></member>
+ <member><symbol>NorthWestGravity</symbol></member>
+ <member><symbol>NorthGravity</symbol></member>
+ <member><symbol>NorthEastGravity</symbol></member>
+ <member><symbol>WestGravity</symbol></member>
+
+ <member><symbol>EastGravity</symbol></member>
+ <member><symbol>SouthWestGravity</symbol></member>
+ <member><symbol>SouthGravity</symbol></member>
+ <member><symbol>SouthEastGravity</symbol></member>
+ <member><symbol>StaticGravity</symbol></member>
+ </simplelist>
+</para>
+<para>
+The win_gravity member is set to the window's window gravity
+and can be one of the following:
+ <simplelist type="vert" columns="2">
+ <member><symbol>UnmapGravity</symbol></member>
+ <member><symbol>NorthWestGravity</symbol></member>
+ <member><symbol>NorthGravity</symbol></member>
+ <member><symbol>NorthEastGravity</symbol></member>
+ <member><symbol>WestGravity</symbol></member>
+
+ <member><symbol>EastGravity</symbol></member>
+ <member><symbol>SouthWestGravity</symbol></member>
+ <member><symbol>SouthGravity</symbol></member>
+ <member><symbol>SouthEastGravity</symbol></member>
+ <member><symbol>StaticGravity</symbol></member>
+ <member><symbol>CenterGravity</symbol></member>
+ </simplelist>
+</para>
+<para>
+<!-- .LP -->
+For additional information on gravity,
+see <link linkend="Gravity_Attributes">section 3.2.3</link>.
+</para>
+<para>
+<!-- .LP -->
+The backing_store member is set to indicate how the X server should maintain
+the contents of a window
+and can be
+<symbol>WhenMapped</symbol>,
+<symbol>Always</symbol>,
+or
+<symbol>NotUseful</symbol>.
+The backing_planes member is set to indicate (with bits set to 1) which bit
+planes of the window hold dynamic data that must be preserved in backing_stores
+and during save_unders.
+The backing_pixel member is set to indicate what values to use
+for planes not set in backing_planes.
+</para>
+<para>
+<!-- .LP -->
+The save_under member is set to
+<symbol>True</symbol>
+or
+<symbol>False</symbol>.
+The colormap member is set to the colormap for the specified window and can be
+a colormap ID or
+<symbol>None</symbol>.
+The map_installed member is set to indicate whether the colormap is
+currently installed and can be
+<symbol>True</symbol>
+or
+<symbol>False</symbol>.
+The map_state member is set to indicate the state of the window and can be
+<symbol>IsUnmapped</symbol>,
+<symbol>IsUnviewable</symbol>,
+or
+<symbol>IsViewable</symbol>.
+<symbol>IsUnviewable</symbol>
+is used if the window is mapped but some ancestor is unmapped.
+</para>
+<para>
+<!-- .LP -->
+The all_event_masks member is set to the bitwise inclusive OR of all event
+masks selected on the window by all clients.
+The your_event_mask member is set to the bitwise inclusive OR of all event
+masks selected by the querying client.
+The do_not_propagate_mask member is set to the bitwise inclusive OR of the
+set of events that should not propagate.
+</para>
+<para>
+<!-- .LP -->
+The override_redirect member is set to indicate whether this window overrides
+structure control facilities and can be
+<symbol>True</symbol>
+or
+<symbol>False</symbol>.
+Window manager clients should ignore the window if this member is
+<symbol>True</symbol>.
+</para>
+<para>
+<!-- .LP -->
+The screen member is set to a screen pointer that gives you a back pointer
+to the correct screen.
+This makes it easier to obtain the screen information without
+having to loop over the root window fields to see which field matches.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XGetWindowAttributes' xrefstyle='select: title'/>
+can generate
+<errorname>BadDrawable</errorname>
+and
+<errorname>BadWindow</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain the current geometry of a given drawable, use
+<xref linkend='XGetGeometry' xrefstyle='select: title'/>.
+</para>
+<indexterm significance="preferred"><primary>XGetGeometry</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='XGetGeometry'>
+<funcprototype>
+ <funcdef>Status <function>XGetGeometry</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>Drawable <parameter>d</parameter></paramdef>
+ <paramdef>Window *<parameter>root_return</parameter></paramdef>
+ <paramdef>int *<parameter>x_return</parameter></paramdef>
+ <paramdef>int *<parameter>y_return</parameter></paramdef>
+ <paramdef>unsigned int *<parameter>width_return</parameter></paramdef>
+ <paramdef>unsigned int *<parameter>height_return</parameter></paramdef>
+ <paramdef>unsigned int *<parameter>border_width_return</parameter></paramdef>
+ <paramdef>unsigned int *<parameter>depth_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'>d</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the drawable, which can be a window or a pixmap.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>root_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the root 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 coordinates that define the location of the drawable.
+For a window,
+these coordinates specify the upper-left outer corner relative to
+its parent's origin.
+For pixmaps, these coordinates are always zero.
+ </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 drawable's dimensions (width and height).
+For a window,
+these dimensions specify the inside size, not including the border.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>border_width_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the border width in pixels.
+If the drawable is a pixmap, it returns zero.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>depth_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the depth of the drawable (bits per pixel for the object).
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XGetGeometry' xrefstyle='select: title'/>
+function returns the root window and the current geometry of the drawable.
+The geometry of the drawable includes the x and y coordinates, width and height,
+border width, and depth.
+These are described in the argument list.
+It is legal to pass to this function a window whose class is
+<symbol>InputOnly</symbol>.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XGetGeometry' xrefstyle='select: title'/>
+can generate a
+<errorname>BadDrawable</errorname>
+error.
+</para>
+</sect1>
+<sect1 id="Translating_Screen_Coordinates">
+<title>Translating Screen Coordinates</title>
+<!-- .XS -->
+<!-- (SN Translating Screen Coordinates -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Applications sometimes
+need to perform a coordinate transformation from the coordinate
+space of one window to another window or need to determine which
+window the pointing device is in.
+<xref linkend='XTranslateCoordinates' xrefstyle='select: title'/>
+and
+<xref linkend='XQueryPointer' xrefstyle='select: title'/>
+fulfill these needs (and avoid any race conditions) by
+asking the X server to perform these operations.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To translate a coordinate in one window to the coordinate
+space of another window, use
+<xref linkend='XTranslateCoordinates' xrefstyle='select: title'/>.
+</para>
+<indexterm significance="preferred"><primary>XTranslateCoordinates</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='XTranslateCoordinates'>
+<funcprototype>
+ <funcdef>Bool <function>XTranslateCoordinates</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>Window <parameter>src_w</parameter></paramdef>
+ <paramdef>Window <parameter>dest_w</parameter></paramdef>
+ <paramdef>int <parameter>src_x</parameter></paramdef>
+ <paramdef>int <parameter>src_y</parameter></paramdef>
+ <paramdef>int *<parameter>dest_x_return</parameter></paramdef>
+ <paramdef>int *<parameter>dest_y_return</parameter></paramdef>
+ <paramdef>Window *<parameter>child_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'>src_w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the source window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>dest_w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the destination window.
+ </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 within the source window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>dest_x_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>dest_y_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Return the x and y coordinates within the destination window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>child_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the child if the coordinates are contained in a mapped child of the
+destination window.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+If
+<xref linkend='XTranslateCoordinates' xrefstyle='select: title'/>
+returns
+<symbol>True</symbol>,
+it takes the src_x and src_y coordinates relative
+to the source window's origin and returns these coordinates to
+dest_x_return and dest_y_return
+relative to the destination window's origin.
+If
+<xref linkend='XTranslateCoordinates' xrefstyle='select: title'/>
+returns
+<symbol>False</symbol>,
+src_w and dest_w are on different screens,
+and dest_x_return and dest_y_return are zero.
+If the coordinates are contained in a mapped child of dest_w,
+that child is returned to child_return.
+Otherwise, child_return is set to
+<symbol>None</symbol>.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XTranslateCoordinates' xrefstyle='select: title'/>
+can generate a
+<errorname>BadWindow</errorname>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain the screen coordinates of the pointer
+or to determine the pointer coordinates relative to a specified window, use
+<xref linkend='XQueryPointer' xrefstyle='select: title'/>.
+</para>
+<indexterm significance="preferred"><primary>XQueryPointer</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='XQueryPointer'>
+<funcprototype>
+ <funcdef>Bool <function>XQueryPointer</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>Window <parameter>w</parameter></paramdef>
+ <paramdef>Window *<parameter>root_return</parameter></paramdef>
+ <paramdef>Window *<parameter>child_return</parameter></paramdef>
+ <paramdef>int *<parameter>root_x_return</parameter></paramdef>
+ <paramdef>int *<parameter>root_y_return</parameter></paramdef>
+ <paramdef>int *<parameter>win_x_return</parameter></paramdef>
+ <paramdef>int *<parameter>win_y_return</parameter></paramdef>
+ <paramdef>unsigned int *<parameter>mask_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'>root_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the root window that the pointer is in.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>child_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the child window that the pointer is located in, if any.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>root_x_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>root_y_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Return the pointer coordinates relative to the root window's origin.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>win_x_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+<!-- .br -->
+<!-- .ns -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>win_y_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Return the pointer coordinates relative to the specified window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>mask_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the current state of the modifier keys and pointer buttons.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XQueryPointer' xrefstyle='select: title'/>
+function returns the root window the pointer is logically on and the pointer
+coordinates relative to the root window's origin.
+If
+<xref linkend='XQueryPointer' xrefstyle='select: title'/>
+returns
+<symbol>False</symbol>,
+the pointer is not on the same screen as the specified window, and
+<xref linkend='XQueryPointer' xrefstyle='select: title'/>
+returns
+<symbol>None</symbol>
+to child_return and zero to win_x_return and win_y_return.
+If
+<xref linkend='XQueryPointer' xrefstyle='select: title'/>
+returns
+<symbol>True</symbol>,
+the pointer coordinates returned to win_x_return and win_y_return
+are relative to the origin of the specified window.
+In this case,
+<xref linkend='XQueryPointer' xrefstyle='select: title'/>
+returns the child that contains the pointer, if any,
+or else
+<symbol>None</symbol>
+to child_return.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XQueryPointer' xrefstyle='select: title'/>
+returns the current logical state of the keyboard buttons
+and the modifier keys in mask_return.
+It sets mask_return to the bitwise inclusive OR of one or more
+of the button or modifier key bitmasks to match
+the current state of the mouse buttons and the modifier keys.
+</para>
+<para>
+<!-- .LP -->
+Note that the logical state of a device (as seen through Xlib)
+may lag the physical state if device event processing is frozen
+(see <link linkend='Pointer_Grabbing'>section 12.1</link>).
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XQueryPointer' xrefstyle='select: title'/>
+can generate a
+<errorname>BadWindow</errorname>
+error.
+</para>
+</sect1>
+<sect1 id="Properties_and_Atoms">
+<title>Properties and Atoms</title>
+<!-- .XS -->
+<!-- (SN Properties and Atoms -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+A property is a collection of named, typed data.
+The window system has a set of predefined properties
+<indexterm><primary>Atom</primary><secondary>predefined</secondary></indexterm>
+(for example, the name of a window, size hints, and so on), and users can
+define any other arbitrary information and associate it with windows.
+Each property has a name,
+which is an ISO Latin-1 string.
+For each named property,
+a unique identifier (atom) is associated with it.
+A property also has a type, for example, string or integer.
+These types are also indicated using atoms, so arbitrary new
+types can be defined.
+Data of only one type may be associated with a single
+property name.
+Clients can store and retrieve properties associated with windows.
+For efficiency reasons,
+an atom is used rather than a character string.
+<xref linkend='XInternAtom' xrefstyle='select: title'/>
+can be used to obtain the atom for property names.
+<indexterm><primary>Atom</primary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+A property is also stored in one of several possible formats.
+The X server can store the information as 8-bit quantities, 16-bit
+quantities, or 32-bit quantities.
+This permits the X server to present the data in the byte order that the
+client expects.
+<!-- .NT Note -->
+If you define further properties of complex type,
+you must encode and decode them yourself.
+These functions must be carefully written if they are to be portable.
+For further information about how to write a library extension,
+see <link linkend="extensions">appendix C</link>.
+<!-- .NE -->
+The type of a property is defined by an atom, which allows for
+arbitrary extension in this type scheme.
+<indexterm><primary>Atom</primary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+Certain property names are
+predefined in the server for commonly used functions.
+The atoms for these properties are defined in
+<filename class="headerfile"><X11/Xatom.h></filename>.
+<indexterm type="file"><primary><filename class="headerfile">X11/Xatom.h</filename></primary></indexterm>
+<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/Xatom.h></filename></secondary></indexterm>
+<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/Xatom.h></filename></secondary></indexterm>
+To avoid name clashes with user symbols, the
+<code>#define</code>
+name for each atom has the XA_ prefix.
+For an explanation of the functions that let you get and set
+much of the information stored in these predefined properties,
+see <link linkend='Inter_Client_Communication_Functions'>chapter 14</link>.
+</para>
+<para>
+<!-- .LP -->
+The core protocol imposes no semantics on these property names,
+but semantics are specified in other X Consortium standards,
+such as the <citetitle>Inter-Client Communication Conventions Manual</citetitle>
+and the <citetitle>X Logical Font Description Conventions</citetitle>.
+</para>
+<para>
+<!-- .LP -->
+You can use properties to communicate other information between
+applications.
+The functions described in this section let you define new properties
+and get the unique atom IDs in your applications.
+</para>
+<para>
+<!-- .LP -->
+Although any particular atom can have some client interpretation
+within each of the name spaces,
+atoms occur in five distinct name spaces within the protocol:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Selections
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Property names
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Property types
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Font properties
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Type of a
+<symbol>ClientMessage</symbol>
+event (none are built into the X server)
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+</para>
+<para>
+<!-- .LP -->
+The built-in selection property names are:
+<simplelist type="vert" columns="2">
+ <member><property>PRIMARY</property></member>
+ <member><property>SECONDARY</property></member>
+</simplelist>
+</para>
+<para>
+<!-- .LP -->
+The built-in property names are:
+ <simplelist type="vert" columns="2">
+ <member><property>CUT_BUFFER0</property></member>
+ <member><property>CUT_BUFFER1</property></member>
+ <member><property>CUT_BUFFER2</property></member>
+ <member><property>CUT_BUFFER3</property></member>
+ <member><property>CUT_BUFFER4</property></member>
+ <member><property>CUT_BUFFER5</property></member>
+ <member><property>CUT_BUFFER6</property></member>
+ <member><property>CUT_BUFFER7</property></member>
+ <member><property>RGB_BEST_MAP</property></member>
+ <member><property>RGB_BLUE_MAP</property></member>
+ <member><property>RGB_DEFAULT_MAP</property></member>
+ <member><property>RGB_GRAY_MAP</property></member>
+ <member><property>RGB_GREEN_MAP</property></member>
+ <member><property>RGB_RED_MAP</property></member>
+
+ <member><property>RESOURCE_MANAGER</property></member>
+ <member><property>WM_CLASS</property></member>
+ <member><property>WM_CLIENT_MACHINE</property></member>
+ <member><property>WM_COLORMAP_WINDOWS</property></member>
+ <member><property>WM_COMMAND</property></member>
+ <member><property>WM_HINTS</property></member>
+ <member><property>WM_ICON_NAME</property></member>
+ <member><property>WM_ICON_SIZE</property></member>
+ <member><property>WM_NAME</property></member>
+ <member><property>WM_NORMAL_HINTS</property></member>
+ <member><property>WM_PROTOCOLS</property></member>
+ <member><property>WM_STATE</property></member>
+ <member><property>WM_TRANSIENT_FOR</property></member>
+ <member><property>WM_ZOOM_HINTS</property></member>
+ </simplelist>
+</para>
+<para>
+The built-in property types are:
+ <simplelist type="vert" columns="2">
+ <member><property>ARC</property></member>
+ <member><property>ATOM</property></member>
+ <member><property>BITMAP</property></member>
+ <member><property>CARDINAL</property></member>
+ <member><property>COLORMAP</property></member>
+ <member><property>CURSOR</property></member>
+ <member><property>DRAWABLE</property></member>
+ <member><property>FONT</property></member>
+ <member><property>INTEGER</property></member>
+ <member><property>PIXMAP</property></member>
+ <member><property>POINT</property></member>
+ <member><property>RGB_COLOR_MAP</property></member>
+ <member><property>RECTANGLE</property></member>
+ <member><property>STRING</property></member>
+ <member><property>VISUALID</property></member>
+ <member><property>WINDOW</property></member>
+ <member><property>WM_HINTS</property></member>
+ <member><property>WM_SIZE_HINTS</property></member>
+ </simplelist>
+</para>
+<para>
+The built-in font property names are:
+ <simplelist type="vert" columns="2">
+ <member><property>MIN_SPACE</property></member>
+ <member><property>NORM_SPACE</property></member>
+ <member><property>MAX_SPACE</property></member>
+ <member><property>END_SPACE</property></member>
+ <member><property>SUPERSCRIPT_X</property></member>
+ <member><property>SUPERSCRIPT_Y</property></member>
+ <member><property>SUBSCRIPT_X</property></member>
+ <member><property>SUBSCRIPT_Y</property></member>
+ <member><property>UNDERLINE_POSITION</property></member>
+ <member><property>UNDERLINE_THICKNESS</property></member>
+ <member><property>FONT_NAME</property></member>
+ <member><property>FULL_NAME</property></member>
+
+ <member><property>STRIKEOUT_DESCENT</property></member>
+ <member><property>STRIKEOUT_ASCENT</property></member>
+ <member><property>ITALIC_ANGLE</property></member>
+ <member><property>X_HEIGHT</property></member>
+ <member><property>QUAD_WIDTH</property></member>
+ <member><property>WEIGHT</property></member>
+ <member><property>POINT_SIZE</property></member>
+ <member><property>RESOLUTION</property></member>
+ <member><property>COPYRIGHT</property></member>
+ <member><property>NOTICE</property></member>
+ <member><property>FAMILY_NAME</property></member>
+ <member><property>CAP_HEIGHT</property></member>
+ </simplelist>
+</para>
+<para>
+<!-- .LP -->
+For further information about font properties,
+see <link linkend="Font_Metrics">section 8.5</link>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To return an atom for a given name, use
+<xref linkend='XInternAtom' xrefstyle='select: title'/>.
+</para>
+<indexterm><primary>Atom</primary><secondary>interning</secondary></indexterm>
+<indexterm significance="preferred"><primary>XInternAtom</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='XInternAtom'>
+<funcprototype>
+ <funcdef>Atom <function>XInternAtom</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>char *<parameter>atom_name</parameter></paramdef>
+ <paramdef>Bool <parameter>only_if_exists</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>atom_name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the name associated with the atom you want returned.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>only_if_exists</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a Boolean value that indicates whether the atom must be created.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XInternAtom' xrefstyle='select: title'/>
+function returns the atom identifier associated with the specified atom_name
+string.
+If only_if_exists is
+<symbol>False</symbol>,
+the atom is created if it does not exist.
+Therefore,
+<xref linkend='XInternAtom' xrefstyle='select: title'/>
+can return
+<symbol>None</symbol>.
+If the atom name is not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+Uppercase and lowercase matter;
+the strings ``thing'', ``Thing'', and ``thinG''
+all designate different atoms.
+The atom will remain defined even after the client's connection closes.
+It will become undefined only when the last connection to
+the X server closes.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XInternAtom' xrefstyle='select: title'/>
+can generate
+<errorname>BadAlloc</errorname>
+and
+<errorname>BadValue</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To return atoms for an array of names, use
+<xref linkend='XInternAtoms' xrefstyle='select: title'/>.
+</para>
+<indexterm><primary>Atom</primary><secondary>interning</secondary></indexterm>
+<indexterm significance="preferred"><primary>XInternAtoms</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='XInternAtoms'>
+<funcprototype>
+ <funcdef>Status <function>XInternAtoms</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>char **<parameter>names</parameter></paramdef>
+ <paramdef>int <parameter>count</parameter></paramdef>
+ <paramdef>Bool <parameter>only_if_exists</parameter></paramdef>
+ <paramdef>Atom *<parameter>atoms_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'>names</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the array of atom names.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>count</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of atom names in the array.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>only_if_exists</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a Boolean value that indicates whether the atom must be created.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>atoms_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the atoms.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XInternAtoms' xrefstyle='select: title'/>
+function returns the atom identifiers associated with the specified names.
+The atoms are stored in the atoms_return array supplied by the caller.
+Calling this function is equivalent to calling
+<xref linkend='XInternAtom' xrefstyle='select: title'/>
+for each of the names in turn with the specified value of only_if_exists,
+but this function minimizes the number of round-trip protocol exchanges
+between the client and the X server.
+</para>
+<para>
+<!-- .LP -->
+This function returns a nonzero status if atoms are returned for
+all of the names;
+otherwise, it returns zero.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XInternAtoms' xrefstyle='select: title'/>
+can generate
+<errorname>BadAlloc</errorname>
+and
+<errorname>BadValue</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To return a name for a given atom identifier, use
+<xref linkend='XGetAtomName' xrefstyle='select: title'/>.
+</para>
+<indexterm><primary>Atom</primary><secondary>getting name</secondary></indexterm>
+<indexterm significance="preferred"><primary>XGetAtomName</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='XGetAtomName'>
+<funcprototype>
+ <funcdef>char *<function>XGetAtomName</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>Atom <parameter>atom</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </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>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XGetAtomName' xrefstyle='select: title'/>
+function returns the name associated with the specified atom.
+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.
+To free the resulting string,
+call
+<xref linkend='XFree' xrefstyle='select: title'/>.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XGetAtomName' xrefstyle='select: title'/>
+can generate a
+<errorname>BadAtom</errorname>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To return the names for an array of atom identifiers, use
+<xref linkend='XGetAtomNames' xrefstyle='select: title'/>.
+</para>
+<indexterm><primary>Atom</primary><secondary>getting name</secondary></indexterm>
+<indexterm significance="preferred"><primary>XGetAtomNames</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='XGetAtomNames'>
+<funcprototype>
+ <funcdef>Status <function>XGetAtomNames</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>Atom *<parameter>atoms</parameter></paramdef>
+ <paramdef>int <parameter>count</parameter></paramdef>
+ <paramdef>char **<parameter>names_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'>atoms</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the array of atoms.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>count</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of atoms in the array.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>names_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the atom names.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XGetAtomNames' xrefstyle='select: title'/>
+function returns the names associated with the specified atoms.
+The names are stored in the names_return array supplied by the caller.
+Calling this function is equivalent to calling
+<xref linkend='XGetAtomName' xrefstyle='select: title'/>
+for each of the atoms in turn,
+but this function minimizes the number of round-trip protocol exchanges
+between the client and the X server.
+</para>
+<para>
+<!-- .LP -->
+This function returns a nonzero status if names are returned for
+all of the atoms;
+otherwise, it returns zero.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XGetAtomNames' xrefstyle='select: title'/>
+can generate a
+<errorname>BadAtom</errorname>
+error.
+</para>
+</sect1>
+<sect1 id="Obtaining_and_Changing_Window_Properties">
+<title>Obtaining and Changing Window Properties</title>
+<!-- .XS -->
+<!-- (SN Obtaining and Changing Window Properties -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+You can attach a property list to every window.
+Each property has a name, a type, and a value
+(see <link linkend="Properties_and_Atoms">section 4.3</link>).
+The value is an array of 8-bit, 16-bit, or 32-bit quantities,
+whose interpretation is left to the clients. The type
+<type>char</type>
+is used to represent 8-bit quantities, the type
+<type>short</type>
+is used to represent 16-bit quantities, and the type
+<type>long</type>
+is used to represent 32-bit quantities.
+</para>
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to obtain,
+change, update, or interchange window properties.
+In addition, Xlib provides other utility functions for inter-client
+communication
+(see <link linkend='Inter_Client_Communication_Functions'>chapter 14</link>).
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain the type, format, and value of a property of a given window, use
+<xref linkend='XGetWindowProperty' xrefstyle='select: title'/>.
+<indexterm><primary>Property</primary><secondary>getting</secondary></indexterm>
+</para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XGetWindowProperty</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='XGetWindowProperty'>
+<funcprototype>
+ <funcdef>int <function>XGetWindowProperty</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>Window <parameter>w</parameter></paramdef>
+ <paramdef>Atom <parameter>property</parameter></paramdef>
+ <paramdef>long <parameter>long_offset</parameter></paramdef>
+ <paramdef>long <parameter>long_length</parameter></paramdef>
+ <paramdef>Bool <parameter>delete</parameter></paramdef>
+ <paramdef>Atom <parameter>req_type</parameter></paramdef>
+ <paramdef>Atom *<parameter>actual_type_return</parameter></paramdef>
+ <paramdef>int *<parameter>actual_format_return</parameter></paramdef>
+ <paramdef>unsigned long *<parameter>nitems_return</parameter></paramdef>
+ <paramdef>unsigned long *<parameter>bytes_after_return</parameter></paramdef>
+ <paramdef>unsigned char **<parameter>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 whose property you want to obtain.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>property</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the property name.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>long_offset</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the offset in the specified property (in 32-bit quantities)
+where the data is to be retrieved.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>long_length</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the length in 32-bit multiples of the data to be retrieved.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>delete</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a Boolean value that determines whether the property is deleted.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>req_type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the atom identifier associated with the property type or
+<symbol>AnyPropertyType</symbol>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>actual_type_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the atom identifier that defines the actual type of the property.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>actual_format_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the actual format of the property.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>nitems_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the actual number of 8-bit, 16-bit, or 32-bit items
+stored in the prop_return data.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>bytes_after_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the number of bytes remaining to be read in the property if
+a partial read was performed.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>prop_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the data in the specified format.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XGetWindowProperty' xrefstyle='select: title'/>
+function returns the actual type of the property; the actual format of the property;
+the number of 8-bit, 16-bit, or 32-bit items transferred; the number of bytes remaining
+to be read in the property; and a pointer to the data actually returned.
+<xref linkend='XGetWindowProperty' xrefstyle='select: title'/>
+sets the return arguments as follows:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+If the specified property does not exist for the specified window,
+<xref linkend='XGetWindowProperty' xrefstyle='select: title'/>
+returns
+<symbol>None</symbol>
+to actual_type_return and the value zero to
+actual_format_return and bytes_after_return.
+The nitems_return argument is empty.
+In this case, the delete argument is ignored.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If the specified property exists
+but its type does not match the specified type,
+<xref linkend='XGetWindowProperty' xrefstyle='select: title'/>
+returns the actual property type to actual_type_return,
+the actual property format (never zero) to actual_format_return,
+and the property length in bytes
+(even if the actual_format_return is 16 or 32)
+to bytes_after_return.
+It also ignores the delete argument.
+The nitems_return argument is empty.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If the specified property exists and either you assign
+<symbol>AnyPropertyType</symbol>
+to the req_type argument or the specified type matches the actual property type,
+<xref linkend='XGetWindowProperty' xrefstyle='select: title'/>
+returns the actual property type to actual_type_return and the actual
+property format (never zero) to actual_format_return.
+It also returns a value to bytes_after_return and nitems_return, by
+defining the following
+values:
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<!-- .nf -->
+ N = actual length of the stored property in bytes
+ (even if the format is 16 or 32)
+ I = 4 * long_offset
+ T = N - I
+ L = MINIMUM(T, 4 * long_length)
+ A = N - (I + L)
+<!-- .fi -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The returned value starts at byte index I in the property (indexing
+from zero), and its length in bytes is L.
+If the value for long_offset causes L to be negative,
+a
+<errorname>BadValue</errorname>
+error results.
+The value of bytes_after_return is A,
+giving the number of trailing unread bytes in the stored property.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+If the returned format is 8, the returned data is represented as a
+<type>char</type>
+array.
+If the returned format is 16, the returned data is represented as a
+<type>short</type>
+array and should be cast to that type to obtain the elements.
+If the returned format is 32, the returned data is represented as a
+<type>long</type>
+array and should be cast to that type to obtain the elements.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XGetWindowProperty' xrefstyle='select: title'/>
+always allocates one extra byte in prop_return
+(even if the property is zero length)
+and sets it to zero so that simple properties consisting of characters
+do not have to be copied into yet another string before use.
+</para>
+<para>
+<!-- .LP -->
+If delete is
+<symbol>True</symbol>
+and bytes_after_return is zero,
+<xref linkend='XGetWindowProperty' xrefstyle='select: title'/>
+deletes the property
+from the window and generates a
+<symbol>PropertyNotify</symbol>
+event on the window.
+</para>
+<para>
+<!-- .LP -->
+The function returns
+<symbol>Success</symbol>
+if it executes successfully.
+To free the resulting data,
+use
+<xref linkend='XFree' xrefstyle='select: title'/>.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XGetWindowProperty' xrefstyle='select: title'/>
+can generate
+<errorname>BadAtom</errorname>,
+<errorname>BadValue</errorname>,
+and
+<errorname>BadWindow</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain a given window's property list, use
+<xref linkend='XListProperties' xrefstyle='select: title'/>.
+</para>
+<indexterm><primary>Property</primary><secondary>listing</secondary></indexterm>
+<indexterm significance="preferred"><primary>XListProperties</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='XListProperties'>
+<funcprototype>
+ <funcdef>Atom *<function>XListProperties</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>Window <parameter>w</parameter></paramdef>
+ <paramdef>int *<parameter>num_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 whose property list you want to obtain.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_prop_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the length of the properties array.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XListProperties' xrefstyle='select: title'/>
+function returns a pointer to an array of atom properties that are defined for
+the specified window or returns NULL if no properties were found.
+To free the memory allocated by this function, use
+<xref linkend='XFree' xrefstyle='select: title'/>.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XListProperties' xrefstyle='select: title'/>
+can generate a
+<errorname>BadWindow</errorname>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To change a property of a given window, use
+<xref linkend='XChangeProperty' xrefstyle='select: title'/>.
+</para>
+<indexterm><primary>Property</primary><secondary>changing</secondary></indexterm>
+<indexterm><primary>Property</primary><secondary>appending</secondary></indexterm>
+<indexterm><primary>Property</primary><secondary>prepending</secondary></indexterm>
+<indexterm><primary>Property</primary><secondary>replacing</secondary></indexterm>
+<indexterm><primary>Property</primary><secondary>format</secondary></indexterm>
+<indexterm><primary>Property</primary><secondary>type</secondary></indexterm>
+<indexterm significance="preferred"><primary>XChangeProperty</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='XChangeProperty'>
+<funcprototype>
+ <funcdef><function>XChangeProperty</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>Window <parameter>w</parameter></paramdef>
+ <paramdef>Atom <parameter>property</parameter></paramdef>
+ <paramdef>Atom <parameter>type</parameter></paramdef>
+ <paramdef>int <parameter>format</parameter></paramdef>
+ <paramdef>int <parameter>mode</parameter></paramdef>
+ <paramdef>unsignedchar *<parameter>data</parameter></paramdef>
+ <paramdef>int <parameter>nelements</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <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 whose property you want to change.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>property</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the property name.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the type of the property.
+The X server does not interpret the type but simply
+passes it back to an application that later calls
+<xref linkend='XGetWindowProperty' xrefstyle='select: title'/>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>format</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies whether the data should be viewed as a list
+of 8-bit, 16-bit, or 32-bit quantities.
+Possible values are 8, 16, and 32.
+This information allows the X server to correctly perform
+byte-swap operations as necessary.
+If the format is 16-bit or 32-bit,
+you must explicitly cast your data pointer to an (unsigned char *) in the call
+to
+<xref linkend='XChangeProperty' xrefstyle='select: title'/>.
+<!-- .\" Changed name of this file to prop_mode.a on 1/13/87 -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>mode</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the mode of the operation.
+You can pass
+<symbol>PropModeReplace</symbol>,
+<symbol>PropModePrepend</symbol>,
+or
+<symbol>PropModeAppend</symbol>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the property data.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>nelements</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of elements of the specified data format.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XChangeProperty' xrefstyle='select: title'/>
+function alters the property for the specified window and
+causes the X server to generate a
+<symbol>PropertyNotify</symbol>
+event on that window.
+<xref linkend='XChangeProperty' xrefstyle='select: title'/>
+performs the following:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+If mode is
+<symbol>PropModeReplace</symbol>,
+<xref linkend='XChangeProperty' xrefstyle='select: title'/>
+discards the previous property value and stores the new data.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If mode is
+<symbol>PropModePrepend</symbol>
+or
+<symbol>PropModeAppend</symbol>,
+<xref linkend='XChangeProperty' xrefstyle='select: title'/>
+inserts the specified data before the beginning of the existing data
+or onto the end of the existing data, respectively.
+The type and format must match the existing property value,
+or a
+<errorname>BadMatch</errorname>
+error results.
+If the property is undefined,
+it is treated as defined with the correct type and
+format with zero-length data.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+If the specified format is 8, the property data must be a
+<type>char</type>
+array.
+If the specified format is 16, the property data must be a
+<type>short</type>
+array.
+If the specified format is 32, the property data must be a
+<type>long</type>
+array.
+</para>
+<para>
+<!-- .LP -->
+The lifetime of a property is not tied to the storing client.
+Properties remain until explicitly deleted, until the window is destroyed,
+or until the server resets.
+For a discussion of what happens when the connection to the X server is closed,
+see <link linkend='Using_X_Server_Connection_Close_Operations'>section 2.6</link>.
+The maximum size of a property is server dependent and can vary dynamically
+depending on the amount of memory the server has available.
+(If there is insufficient space, a
+<errorname>BadAlloc</errorname>
+error results.)
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XChangeProperty' xrefstyle='select: title'/>
+can generate
+<errorname>BadAlloc</errorname>,
+<errorname>BadAtom</errorname>,
+<errorname>BadMatch</errorname>,
+<errorname>BadValue</errorname>,
+and
+<errorname>BadWindow</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To rotate a window's property list, use
+<xref linkend='XRotateWindowProperties' xrefstyle='select: title'/>.
+</para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XRotateWindowProperties</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='XRotateWindowProperties'>
+<funcprototype>
+ <funcdef><function>XRotateWindowProperties</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>Window <parameter>w</parameter></paramdef>
+ <paramdef>Atom <parameter>properties[]</parameter></paramdef>
+ <paramdef>int <parameter>num_prop</parameter></paramdef>
+ <paramdef>int <parameter>npositions</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <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'>properties</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the array of properties that are to be rotated.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_prop</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the length of the properties array.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>npositions</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the rotation amount.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XRotateWindowProperties' xrefstyle='select: title'/>
+function allows you to rotate properties on a window and causes
+the X server to generate
+<symbol>PropertyNotify</symbol>
+events.
+If the property names in the properties array are viewed as being numbered
+starting from zero and if there are num_prop property names in the list,
+then the value associated with property name I becomes the value associated
+with property name (I + npositions) mod N for all I from zero to N − 1.
+The effect is to rotate the states by npositions places around the virtual ring
+of property names (right for positive npositions,
+left for negative npositions).
+If npositions mod N is nonzero,
+the X server generates a
+<symbol>PropertyNotify</symbol>
+event for each property in the order that they are listed in the array.
+If an atom occurs more than once in the list or no property with that
+name is defined for the window,
+a
+<errorname>BadMatch</errorname>
+error results.
+If a
+<errorname>BadAtom</errorname>
+or
+<errorname>BadMatch</errorname>
+error results,
+no properties are changed.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XRotateWindowProperties' xrefstyle='select: title'/>
+can generate
+<errorname>BadAtom</errorname>,
+<errorname>BadMatch</errorname>,
+and
+<errorname>BadWindow</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To delete a property on a given window, use
+<xref linkend='XDeleteProperty' xrefstyle='select: title'/>.
+</para>
+<indexterm><primary>Property</primary><secondary>deleting</secondary></indexterm>
+<indexterm significance="preferred"><primary>XDeleteProperty</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='XDeleteProperty'>
+<funcprototype>
+ <funcdef><function>XDeleteProperty</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>Window <parameter>w</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 whose property you want to delete.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>property</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the property name.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XDeleteProperty' xrefstyle='select: title'/>
+function deletes the specified property only if the
+property was defined on the specified window
+and causes the X server to generate a
+<symbol>PropertyNotify</symbol>
+event on the window unless the property does not exist.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XDeleteProperty' xrefstyle='select: title'/>
+can generate
+<errorname>BadAtom</errorname>
+and
+<errorname>BadWindow</errorname>
+errors.
+</para>
+</sect1>
+<sect1 id="Selections">
+<title>Selections</title>
+<!-- .XS -->
+<!-- (SN Selections -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Selection</primary></indexterm>
+Selections are one method used by applications to exchange data.
+By using the property mechanism,
+applications can exchange data of arbitrary types and can negotiate
+the type of the data.
+A selection can be thought of as an indirect property with a dynamic type.
+That is, rather than having the property stored in the X server,
+the property is maintained by some client (the owner).
+A selection is global in nature (considered to belong to the user
+but be maintained by clients) rather than being private to a particular
+window subhierarchy or a particular set of clients.
+</para>
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to set, get, or request conversion
+of selections.
+This allows applications to implement the notion of current selection,
+which requires that notification be sent to applications when they no
+longer own the selection.
+Applications that support selection often highlight the current selection
+and so must be informed when another application has
+acquired the selection so that they can unhighlight the selection.
+</para>
+<para>
+<!-- .LP -->
+When a client asks for the contents of
+a selection, it specifies a selection target type.
+This target type
+can be used to control the transmitted representation of the contents.
+For example, if the selection is ``the last thing the user clicked on''
+and that is currently an image, then the target type might specify
+whether the contents of the image should be sent in XY format or Z format.
+</para>
+<para>
+<!-- .LP -->
+The target type can also be used to control the class of
+contents transmitted, for example,
+asking for the ``looks'' (fonts, line
+spacing, indentation, and so forth) of a paragraph selection, not the
+text of the paragraph.
+The target type can also be used for other
+purposes.
+The protocol does not constrain the semantics.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set the selection owner, use
+<xref linkend='XSetSelectionOwner' xrefstyle='select: title'/>.
+</para>
+<indexterm><primary>Selection</primary><secondary>setting the owner</secondary></indexterm>
+<indexterm significance="preferred"><primary>XSetSelectionOwner</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='XSetSelectionOwner'>
+<funcprototype>
+ <funcdef><function>XSetSelectionOwner</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>Atom <parameter>selection</parameter></paramdef>
+ <paramdef>Window <parameter>owner</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'>selection</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the selection atom.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>owner</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the owner of the specified selection atom.
+You can pass a window 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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XSetSelectionOwner' xrefstyle='select: title'/>
+function changes the owner and last-change time for the specified selection
+and has no effect if the specified time is earlier than the current
+last-change time of the specified selection
+or is later than the current X server time.
+Otherwise, the last-change time is set to the specified time,
+with
+<symbol>CurrentTime</symbol>
+replaced by the current server time.
+If the owner window is specified as
+<symbol>None</symbol>,
+then the owner of the selection becomes
+<symbol>None</symbol>
+(that is, no owner).
+Otherwise, the owner of the selection becomes the client executing
+the request.
+</para>
+<para>
+<!-- .LP -->
+If the new owner (whether a client or
+<symbol>None</symbol>)
+is not
+the same as the current owner of the selection and the current
+owner is not
+<symbol>None</symbol>,
+the current owner is sent a
+<symbol>SelectionClear</symbol>
+event.
+If the client that is the owner of a selection is later
+terminated (that is, its connection is closed)
+or if the owner window it has specified in the request is later
+destroyed,
+the owner of the selection automatically
+reverts to
+<symbol>None</symbol>,
+but the last-change time is not affected.
+The selection atom is uninterpreted by the X server.
+<xref linkend='XGetSelectionOwner' xrefstyle='select: title'/>
+returns the owner window, which is reported in
+<symbol>SelectionRequest</symbol>
+and
+<symbol>SelectionClear</symbol>
+events.
+Selections are global to the X server.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XSetSelectionOwner' xrefstyle='select: title'/>
+can generate
+<errorname>BadAtom</errorname>
+and
+<errorname>BadWindow</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To return the selection owner, use
+<xref linkend='XGetSelectionOwner' xrefstyle='select: title'/>.
+</para>
+<indexterm><primary>Selection</primary><secondary>getting the owner</secondary></indexterm>
+<indexterm significance="preferred"><primary>XGetSelectionOwner</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='XGetSelectionOwner'>
+<funcprototype>
+ <funcdef>Window <function>XGetSelectionOwner</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>Atom <parameter>selection</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>selection</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the selection atom whose owner you want returned.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XGetSelectionOwner' xrefstyle='select: title'/>
+function
+returns the window ID associated with the window that currently owns the
+specified selection.
+If no selection was specified, the function returns the constant
+<symbol>None</symbol>.
+If
+<symbol>None</symbol>
+is returned,
+there is no owner for the selection.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XGetSelectionOwner' xrefstyle='select: title'/>
+can generate a
+<errorname>BadAtom</errorname>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To request conversion of a selection, use
+<xref linkend='XConvertSelection' xrefstyle='select: title'/>.
+</para>
+<indexterm><primary>Selection</primary><secondary>converting</secondary></indexterm>
+<indexterm significance="preferred"><primary>XConvertSelection</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='XConvertSelection'>
+<funcprototype>
+ <funcdef><function>XConvertSelection</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>Atom <parameter>selection</parameter></paramdef>
+ <paramdef>Atom <parameter>target</parameter></paramdef>
+ <paramdef>Atom <parameter>property</parameter></paramdef>
+ <paramdef>Window <parameter>requestor</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'>selection</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the selection atom.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>target</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the target atom.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>property</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the property name.
+You also can pass
+<symbol>None</symbol>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>requestor</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the requestor.
+ </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>
+<!-- .LP -->
+<!-- .eM -->
+<xref linkend='XConvertSelection' xrefstyle='select: title'/>
+requests that the specified selection be converted to the specified target
+type:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+If the specified selection has an owner, the X server sends a
+<symbol>SelectionRequest</symbol>
+event to that owner.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If no owner for the specified
+selection exists, the X server generates a
+<symbol>SelectionNotify</symbol>
+event to the
+requestor with property
+<symbol>None</symbol>.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+The arguments are passed on unchanged in either of the events.
+There are two predefined selection atoms: PRIMARY and SECONDARY.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XConvertSelection' xrefstyle='select: title'/>
+can generate
+<errorname>BadAtom</errorname>
+and
+<errorname>BadWindow</errorname>
+errors.
+<!-- .bp -->
+
+
+</para>
+</sect1>
+</chapter>
Index: create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/libX11/CH06.xml
===================================================================
--- create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/libX11/CH06.xml (nonexistent)
+++ create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/libX11/CH06.xml (revision 5)
@@ -0,0 +1,7406 @@
+<?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"><X11/Xcms.h></filename>.
+<indexterm type="file"><primary><filename class="headerfile">X11/Xcms.h</filename></primary></indexterm>
+<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/Xcms.h></filename></secondary></indexterm>
+<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/Xcms.h></filename></secondary></indexterm>
+The remaining functions and types are defined in
+<filename class="headerfile"><X11/Xlib.h></filename>.
+<indexterm type="file"><primary><filename class="headerfile">X11/Xlib.h</filename></primary></indexterm>
+<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/Xlib.h></filename></secondary></indexterm>
+<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/Xlib.h></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
+<xref linkend='XInstallColormap' xrefstyle='select: title'/>
+and
+<xref linkend='XUninstallColormap' xrefstyle='select: title'/>.
+</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 <link linkend="Visual_Types">section 3.1</link>).
+</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 <link linkend="Creating_Additional_Color_Spaces">section 6.12.4</link>).
+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
+<xref linkend='XcmsFormatOfPrefix' xrefstyle='select: title'/>
+and
+<xref linkend='XcmsPrefixOfFormat' xrefstyle='select: title'/>).
+</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>
+<xref linkend='XAllocNamedColor' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XcmsAllocNamedColor' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XLookupColor' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XcmsLookupColor' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XParseColor' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XStoreNamedColor' xrefstyle='select: title'/>
+ </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'><color_space_name></emphasis>:<emphasis remap='I'><value>/.../<value></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'><red>/<green>/<blue></emphasis>
+
+ <emphasis remap='I'><red></emphasis>, <emphasis remap='I'><green></emphasis>, <emphasis remap='I'><blue></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'><red>/<green>/<blue></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'><X>/<Y>/<Z></emphasis>
+CIEuvY:<emphasis remap='I'><u>/<v>/<Y></emphasis>
+CIExyY:<emphasis remap='I'><x>/<y>/<Y></emphasis>
+CIELab:<emphasis remap='I'><L>/<a>/<b></emphasis>
+CIELuv:<emphasis remap='I'><L>/<u>/<v></emphasis>
+TekHVC:<emphasis remap='I'><H>/<V>/<C></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
+<xref linkend='XCreateColormap' xrefstyle='select: title'/>.</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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window on whose screen you want to create a colormap.
+ </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
+<xref linkend='XCreateColormap' xrefstyle='select: title'/>
+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 <link linkend="Visual_Types">section 3.1</link>.
+</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
+<xref linkend='XAllocColorCells' xrefstyle='select: title'/>
+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
+<xref linkend='XAllocColorPlanes' xrefstyle='select: title'/>
+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
+<xref linkend='XFreeColors' xrefstyle='select: title'/>.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XCreateColormap' xrefstyle='select: title'/>
+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
+<xref linkend='XCopyColormapAndFree' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XCopyColormapAndFree' xrefstyle='select: title'/>
+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
+<xref linkend='XAllocColor' xrefstyle='select: title'/>,
+<xref linkend='XAllocNamedColor' xrefstyle='select: title'/>,
+<xref linkend='XAllocColorCells' xrefstyle='select: title'/>,
+or
+<xref linkend='XAllocColorPlanes' xrefstyle='select: title'/>
+and that have not been freed since they were allocated.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XCopyColormapAndFree' xrefstyle='select: title'/>
+can generate
+<errorname>BadAlloc</errorname>
+and
+<errorname>BadColor</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To destroy a colormap, use
+<xref linkend='XFreeColormap' xrefstyle='select: title'/>.
+<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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>colormap</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the colormap that you want to destroy.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XFreeColormap' xrefstyle='select: title'/>
+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
+<xref linkend='XUninstallColormap' xrefstyle='select: title'/>).
+If the specified colormap is defined as the colormap for a window (by
+<xref linkend='XCreateWindow' xrefstyle='select: title'/>,
+<xref linkend='XSetWindowColormap' xrefstyle='select: title'/>,
+or
+<xref linkend='XChangeWindowAttributes' xrefstyle='select: title'/>),
+<xref linkend='XFreeColormap' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XFreeColormap' xrefstyle='select: title'/>
+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
+<xref linkend='XLookupColor' xrefstyle='select: title'/>.
+<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 *<parameter>exact_def_return</parameter></paramdef>
+ <paramdef>XColor *<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
+<xref linkend='XLookupColor' xrefstyle='select: title'/>
+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.
+<xref linkend='XLookupColor' xrefstyle='select: title'/>
+returns nonzero if the name is resolved;
+otherwise, it returns zero.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XLookupColor' xrefstyle='select: title'/>
+can generate a
+<errorname>BadColor</errorname>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To map a color name to the exact <acronym>RGB</acronym> value, use
+<xref linkend='XParseColor' xrefstyle='select: title'/>.
+</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
+<xref linkend='XParseColor' xrefstyle='select: title'/>
+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.
+<xref linkend='XParseColor' xrefstyle='select: title'/>
+returns nonzero if the name is resolved;
+otherwise, it returns zero.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XParseColor' xrefstyle='select: title'/>
+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
+<xref linkend='XcmsLookupColor' xrefstyle='select: title'/>.
+</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 *<parameter>color_exact_return</parameter></paramdef>
+ <paramdef>XcmsColor *<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
+<xref linkend='XcmsLookupColor' xrefstyle='select: title'/>
+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.
+<xref linkend='XcmsLookupColor' xrefstyle='select: title'/>
+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
+<xref linkend='XAllocColor' xrefstyle='select: title'/>.
+</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
+<xref linkend='XAllocColor' xrefstyle='select: title'/>
+function allocates a read-only colormap entry corresponding to the closest
+<acronym>RGB</acronym> value supported by the hardware.
+<xref linkend='XAllocColor' xrefstyle='select: title'/>
+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,
+<xref linkend='XAllocColor' xrefstyle='select: title'/>
+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.
+<xref linkend='XAllocColor' xrefstyle='select: title'/>
+does not use or affect the flags in the
+<structname>XColor</structname>
+structure.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XAllocColor' xrefstyle='select: title'/>
+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
+<xref linkend='XcmsAllocColor' xrefstyle='select: title'/>.
+</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
+<xref linkend='XcmsAllocColor' xrefstyle='select: title'/>
+function is similar to
+<xref linkend='XAllocColor' xrefstyle='select: title'/>
+except the color can be specified in any format.
+The
+<xref linkend='XcmsAllocColor' xrefstyle='select: title'/>
+function ultimately calls
+<xref linkend='XAllocColor' xrefstyle='select: title'/>
+to allocate a read-only color cell (colormap entry) with the specified color.
+<xref linkend='XcmsAllocColor' xrefstyle='select: title'/>
+first converts the color specified
+to an <acronym>RGB</acronym> value and then passes this to
+<xref linkend='XAllocColor' xrefstyle='select: title'/>.
+<xref linkend='XcmsAllocColor' xrefstyle='select: title'/>
+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
+<xref linkend='XAllocColor' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XcmsAllocColor' xrefstyle='select: title'/>
+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
+<xref linkend='XAllocNamedColor' xrefstyle='select: title'/>.
+</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 *<parameter>screen_def_return</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'>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
+<xref linkend='XAllocNamedColor' xrefstyle='select: title'/>
+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.
+<xref linkend='XAllocNamedColor' xrefstyle='select: title'/>
+returns nonzero if a cell is allocated;
+otherwise, it returns zero.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XAllocNamedColor' xrefstyle='select: title'/>
+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
+<xref linkend='XcmsAllocNamedColor' xrefstyle='select: title'/>.
+</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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>color_string</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the color string whose color definition structure is to be
+returned.
+ </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
+<xref linkend='XcmsAllocNamedColor' xrefstyle='select: title'/>
+function is similar to
+<xref linkend='XAllocNamedColor' xrefstyle='select: title'/>
+except that the color returned can be in any format specified.
+This function
+ultimately calls
+<xref linkend='XAllocColor' xrefstyle='select: title'/>
+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
+<xref linkend='XcmsLookupColor' xrefstyle='select: title'/>),
+converted
+to an <acronym>RGB</acronym> value, and finally passed to
+<xref linkend='XAllocColor' xrefstyle='select: title'/>.
+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
+<xref linkend='XAllocColor' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XcmsAllocNamedColor' xrefstyle='select: title'/>
+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
+<xref linkend='XAllocColorCells' xrefstyle='select: title'/>.
+</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>unsigned long <parameter>plane_masks_return[]</parameter></paramdef>
+ <paramdef>unsigned int <parameter>nplanes</parameter></paramdef>
+ <paramdef>unsigned long <parameter>pixels_return[]</parameter></paramdef>
+ <paramdef>unsigned int <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
+<xref linkend='XAllocColorCells' xrefstyle='select: title'/>
+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 × 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.
+<xref linkend='XAllocColorCells' xrefstyle='select: title'/>
+returns nonzero if it succeeded or zero if it failed.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XAllocColorCells' xrefstyle='select: title'/>
+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
+<xref linkend='XAllocColorPlanes' xrefstyle='select: title'/>.
+</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>unsigned long <parameter>pixels_return[]</parameter></paramdef>
+ <paramdef>int <parameter>ncolors</parameter></paramdef>
+ <paramdef>int <parameter>nreds</parameter></paramdef>
+ <paramdef>int <parameter>ngreens</parameter></paramdef>
+ <paramdef>int <parameter>nblues</parameter></paramdef>
+ <paramdef>unsigned long *<parameter>rmask_return</parameter></paramdef>
+ <paramdef>unsigned long *<parameter>gmask_return</parameter></paramdef>
+ <paramdef>unsigned long *<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.
+<xref linkend='XAllocColorPlanes' xrefstyle='select: title'/>
+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 × 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 × 2<superscript><emphasis>nreds</emphasis></superscript>
+independent red entries,
+ncolors × 2<superscript><emphasis>ngreens</emphasis></superscript>
+independent green entries, and
+ncolors × 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
+<xref linkend='XStoreColors' xrefstyle='select: title'/>,
+<xref linkend='XStoreColor' xrefstyle='select: title'/>,
+or
+<xref linkend='XStoreNamedColor' xrefstyle='select: title'/>),
+the pixel is decomposed according to the masks,
+and the corresponding independent entries are updated.
+<xref linkend='XAllocColorPlanes' xrefstyle='select: title'/>
+returns nonzero if it succeeded or zero if it failed.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XAllocColorPlanes' xrefstyle='select: title'/>
+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
+<xref linkend='XFreeColors' xrefstyle='select: title'/>.
+<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>unsigned long <parameter>pixels[]</parameter></paramdef>
+ <paramdef>int <parameter>npixels</parameter></paramdef>
+ <paramdef>unsigned long <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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>pixels</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies an array of pixel values that map to the cells in the specified
+colormap.
+ </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
+<xref linkend='XFreeColors' xrefstyle='select: title'/>
+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>
+<xref linkend='XAllocColor' xrefstyle='select: title'/>,
+<xref linkend='XAllocNamedColor' xrefstyle='select: title'/>,
+<xref linkend='XAllocColorCells' xrefstyle='select: title'/>,
+and
+<xref linkend='XAllocColorPlanes' xrefstyle='select: title'/>).
+Note that freeing an
+individual pixel obtained from
+<xref linkend='XAllocColorPlanes' xrefstyle='select: title'/>
+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
+<xref linkend='XCreateColormap' xrefstyle='select: title'/>),
+a
+<errorname>BadAccess</errorname>
+error results.
+If more than one pixel is in error,
+the one that gets reported is arbitrary.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XFreeColors' xrefstyle='select: title'/>
+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
+<xref linkend='XStoreColor' xrefstyle='select: title'/>.
+</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
+<xref linkend='XStoreColor' xrefstyle='select: title'/>
+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.
+<xref linkend='XStoreColor' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XStoreColor' xrefstyle='select: title'/>
+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
+<xref linkend='XStoreColors' xrefstyle='select: title'/>.
+</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
+<xref linkend='XStoreColors' xrefstyle='select: title'/>
+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.
+<xref linkend='XStoreColors' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XStoreColors' xrefstyle='select: title'/>
+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
+<xref linkend='XcmsStoreColor' xrefstyle='select: title'/>.
+</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
+<xref linkend='XcmsStoreColor' xrefstyle='select: title'/>
+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
+<xref linkend='XStoreColor' xrefstyle='select: title'/>
+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
+<xref linkend='XStoreColor' xrefstyle='select: title'/>
+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
+<xref linkend='XStoreColor' xrefstyle='select: title'/>
+was made.
+To obtain the actual color stored, use
+<xref linkend='XcmsQueryColor' xrefstyle='select: title'/>.
+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 -->
+<xref linkend='XcmsStoreColor' xrefstyle='select: title'/>
+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
+<xref linkend='XcmsStoreColors' xrefstyle='select: title'/>.
+</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
+<xref linkend='XcmsStoreColors' xrefstyle='select: title'/>
+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
+<xref linkend='XStoreColors' xrefstyle='select: title'/>
+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
+<xref linkend='XStoreColors' xrefstyle='select: title'/>
+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
+<xref linkend='XStoreColors' xrefstyle='select: title'/>
+was made.
+To obtain the actual colors stored, use
+<xref linkend='XcmsQueryColors' xrefstyle='select: title'/>.
+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 -->
+<xref linkend='XcmsStoreColors' xrefstyle='select: title'/>
+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
+<xref linkend='XStoreNamedColor' xrefstyle='select: title'/>.
+</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>unsigned long <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
+<xref linkend='XStoreNamedColor' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XStoreNamedColor' xrefstyle='select: title'/>
+can generate
+<errorname>BadAccess</errorname>,
+<errorname>BadColor</errorname>,
+<errorname>BadName</errorname>,
+and
+<errorname>BadValue</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+The
+<xref linkend='XQueryColor' xrefstyle='select: title'/>
+and
+<xref linkend='XQueryColors' xrefstyle='select: title'/>
+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
+<xref linkend='XQueryColor' xrefstyle='select: title'/>.
+</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
+<xref linkend='XQueryColor' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XQueryColor' xrefstyle='select: title'/>
+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
+<xref linkend='XQueryColors' xrefstyle='select: title'/>.
+</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
+<xref linkend='XQueryColors' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XQueryColors' xrefstyle='select: title'/>
+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
+<xref linkend='XcmsQueryColor' xrefstyle='select: title'/>.
+</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
+<xref linkend='XcmsQueryColor' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XcmsQueryColor' xrefstyle='select: title'/>
+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
+<xref linkend='XcmsQueryColors' xrefstyle='select: title'/>.
+</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>unsigned int <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
+<xref linkend='XcmsQueryColors' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XcmsQueryColors' xrefstyle='select: title'/>
+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
+<xref linkend='XcmsCCCOfColormap' xrefstyle='select: title'/>.
+</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
+<xref linkend='XcmsCCCOfColormap' xrefstyle='select: title'/>
+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
+<xref linkend='XcmsSetCCCOfColormap' xrefstyle='select: title'/>,
+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
+<xref linkend='XcmsSetCCCOfColormap' xrefstyle='select: title'/>.
+</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
+<xref linkend='XcmsSetCCCOfColormap' xrefstyle='select: title'/>
+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
+<xref linkend='XcmsFreeCCC' xrefstyle='select: title'/>.
+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
+<xref linkend='XcmsDefaultCCC' xrefstyle='select: title'/>.
+</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
+<xref linkend='XcmsDefaultCCC' xrefstyle='select: title'/>
+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
+<xref linkend='XcmsSetWhitePoint' xrefstyle='select: title'/>.
+</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.
+ </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
+<xref linkend='XcmsSetWhitePoint' xrefstyle='select: title'/>
+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
+<xref linkend='XcmsSetCompressionProc' xrefstyle='select: title'/>.
+</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>.
+ </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
+<xref linkend='XcmsSetCompressionProc' xrefstyle='select: title'/>
+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
+<xref linkend='XcmsSetWhiteAdjustProc' xrefstyle='select: title'/>.
+</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.
+ </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
+<xref linkend='XcmsSetWhiteAdjustProc' xrefstyle='select: title'/>
+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
+<xref linkend='XcmsCreateCCC' xrefstyle='select: title'/>.
+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
+<xref linkend='XcmsFreeCCC' xrefstyle='select: title'/>.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To create a CCC, use
+<xref linkend='XcmsCreateCCC' xrefstyle='select: title'/>.
+</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
+<xref linkend='XcmsCreateCCC' xrefstyle='select: title'/>
+function creates a CCC for the specified display, screen, and visual.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To free a CCC, use
+<xref linkend='XcmsFreeCCC' xrefstyle='select: title'/>.
+</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
+<xref linkend='XcmsFreeCCC' xrefstyle='select: title'/>
+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
+<xref linkend='XcmsConvertColors' xrefstyle='select: title'/>.
+</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>unsigned int <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
+<xref linkend='XcmsConvertColors' xrefstyle='select: title'/>
+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>unsigned int <parameter>ncolors</parameter></paramdef>
+ <paramdef>unsigned int <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
+<xref linkend='XcmsAddColorSpace' xrefstyle='select: title'/>
+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
+<xref linkend='XcmsCIELabQueryMaxC' xrefstyle='select: title'/>.
+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
+<xref linkend='XcmsCIELuvQueryMaxC' xrefstyle='select: title'/>.
+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>unsigned int <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
+<xref linkend='XcmsAddColorSpace' xrefstyle='select: title'/>
+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
+<xref linkend='XcmsAllocColor' xrefstyle='select: title'/>
+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
+<xref linkend='XcmsAllocColor' xrefstyle='select: title'/>
+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
+<xref linkend='XAllocColor' xrefstyle='select: title'/>,
+and the <acronym>RGB</acronym>
+specification returned by
+<xref linkend='XAllocColor' xrefstyle='select: title'/>
+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'><color_space></emphasis>QueryMax<emphasis remap='I'><dimensions></emphasis>
+
+Xcms<emphasis remap='I'><color_space></emphasis>QueryMin<emphasis remap='I'><dimensions></emphasis>
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+The <dimensions> consists of a letter or letters
+that identify the dimensions of the color space
+that are not fixed.
+For example,
+<xref linkend='XcmsTekHVCQueryMaxC' xrefstyle='select: title'/>
+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
+<xref linkend='XcmsQueryBlack' xrefstyle='select: title'/>.
+</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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>color_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the color specification in the specified target format
+for zero-intensity red, green, and blue.
+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
+<xref linkend='XcmsQueryBlack' xrefstyle='select: title'/>
+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
+<xref linkend='XcmsQueryBlue' xrefstyle='select: title'/>.
+</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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>color_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the color specification in the specified target format
+for full-intensity blue while red and green are zero.
+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
+<xref linkend='XcmsQueryBlue' xrefstyle='select: title'/>
+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
+<xref linkend='XcmsQueryGreen' xrefstyle='select: title'/>.
+</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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>color_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the color specification in the specified target format
+for full-intensity green while red and blue are zero.
+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
+<xref linkend='XcmsQueryGreen' xrefstyle='select: title'/>
+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
+<xref linkend='XcmsQueryRed' xrefstyle='select: title'/>.
+</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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>color_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the color specification in the specified target format
+for full-intensity red while green and blue are zero.
+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
+<xref linkend='XcmsQueryRed' xrefstyle='select: title'/>
+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
+<xref linkend='XcmsQueryWhite' xrefstyle='select: title'/>.
+</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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>color_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the color specification in the specified target format
+for full-intensity red, green, and blue.
+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
+<xref linkend='XcmsQueryWhite' xrefstyle='select: title'/>
+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
+<xref linkend='XcmsCIELabQueryMaxC' xrefstyle='select: title'/>.
+</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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>hue_angle</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the hue angle (in degrees) at which to find maximum chroma.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>L_star</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the lightness (L*) at which to find maximum 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 maximum chroma
+displayable by the screen for the given hue angle and lightness.
+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
+<xref linkend='XcmsCIELabQueryMaxC' xrefstyle='select: title'/>
+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
+<xref linkend='XcmsCIELabQueryMaxL' xrefstyle='select: title'/>.
+</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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>hue_angle</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the hue angle (in degrees) at which to find maximum lightness.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>chroma</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the chroma at which to find maximum 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 maximum lightness
+displayable by the screen for the given hue angle and chroma.
+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
+<xref linkend='XcmsCIELabQueryMaxL' xrefstyle='select: title'/>
+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
+<xref linkend='XcmsCIELabQueryMaxLC' xrefstyle='select: title'/>.
+</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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>hue_angle</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the hue angle (in degrees) at which to find maximum 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 maximum chroma
+displayable by the screen for the given hue angle.
+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
+<xref linkend='XcmsCIELabQueryMaxLC' xrefstyle='select: title'/>
+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
+<xref linkend='XcmsCIELabQueryMinL' xrefstyle='select: title'/>.
+</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='XcmsCIELabQueryMinL'>
+<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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>hue_angle</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the hue angle (in degrees) at which to find minimum lightness.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>chroma</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the chroma at which to find minimum 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 minimum lightness
+displayable by the screen for the given hue angle and chroma.
+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
+<xref linkend='XcmsCIELabQueryMinL' xrefstyle='select: title'/>
+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
+<xref linkend='XcmsCIELuvQueryMaxC' xrefstyle='select: title'/>.
+</para>
+<indexterm significance="preferred"><primary>XcmsCIELuvQueryMaxC</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='XcmsCIELuvQueryMaxC'>
+<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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>hue_angle</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the hue angle (in degrees) at which to find maximum chroma.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>L_star</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the lightness (L*) at which to find maximum 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 maximum chroma
+displayable by the screen for the given hue angle and lightness.
+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
+<xref linkend='XcmsCIELuvQueryMaxC' xrefstyle='select: title'/>
+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
+<xref linkend='XcmsCIELuvQueryMaxL' xrefstyle='select: title'/>.
+</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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>hue_angle</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the hue angle (in degrees) at which to find maximum lightness.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>L_star</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the lightness (L*) at which to find maximum 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 maximum lightness
+displayable by the screen for the given hue angle and chroma.
+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
+<xref linkend='XcmsCIELuvQueryMaxL' xrefstyle='select: title'/>
+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
+<xref linkend='XcmsCIELuvQueryMaxLC' xrefstyle='select: title'/>.
+</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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>hue_angle</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the hue angle (in degrees) at which to find maximum 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 maximum chroma
+displayable by the screen for the given hue angle.
+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
+<xref linkend='XcmsCIELuvQueryMaxLC' xrefstyle='select: title'/>
+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
+<xref linkend='XcmsCIELuvQueryMinL' xrefstyle='select: title'/>.
+</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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>hue_angle</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the hue angle (in degrees) at which to find minimum lightness.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>chroma</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the chroma at which to find minimum 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 minimum lightness
+displayable by the screen for the given hue angle and chroma.
+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
+<xref linkend='XcmsCIELuvQueryMinL' xrefstyle='select: title'/>
+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
+<xref linkend='XcmsTekHVCQueryMaxC' xrefstyle='select: title'/>.
+</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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>hue</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the Hue in which to find the maximum Chroma.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>value</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the Value in which to find the maximum Chroma.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>color_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the maximum Chroma along with the actual Hue and Value at which
+the maximum Chroma 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
+<xref linkend='XcmsTekHVCQueryMaxC' xrefstyle='select: title'/>
+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
+<xref linkend='XcmsTekHVCQueryMaxV' xrefstyle='select: title'/>.
+</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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>hue</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the Hue in which to find the maximum Value.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>chroma</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the chroma at which to find maximum Value.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>color_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the maximum Value along with the Hue and Chroma at which the
+maximum Value
+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
+<xref linkend='XcmsTekHVCQueryMaxV' xrefstyle='select: title'/>
+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
+<xref linkend='XcmsTekHVCQueryMaxVC' xrefstyle='select: title'/>.
+</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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>hue</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the Hue in which to find the maximum Chroma.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>color_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the color specification in XcmsTekHVC for the maximum Chroma, the
+Value at which that maximum Chroma is reached, and the actual Hue at which
+the maximum Chroma 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
+<xref linkend='XcmsTekHVCQueryMaxVC' xrefstyle='select: title'/>
+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
+<xref linkend='XcmsTekHVCQueryMaxVSamples' xrefstyle='select: title'/>.
+</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>unsigned int <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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>hue</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the Hue for maximum Chroma/Value samples.
+ </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
+<xref linkend='XcmsTekHVCQueryMaxVSamples' xrefstyle='select: title'/>
+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
+<xref linkend='XcmsTekHVCQueryMinV' xrefstyle='select: title'/>.
+</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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>hue</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the Hue in which to find the minimum Value.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>value</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the Value in which to find the minimum Value.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>color_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the minimum Value and the actual Hue and Chroma at which the
+minimum Value
+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
+<xref linkend='XcmsTekHVCQueryMinV' xrefstyle='select: title'/>
+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
+<xref linkend='XcmsAddColorSpace' xrefstyle='select: title'/>
+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
+<xref linkend='XcmsAddFunctionSet' xrefstyle='select: title'/>
+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
+<xref linkend='XcmsAddColorSpace' xrefstyle='select: title'/>.
+</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
+<xref linkend='XcmsAddColorSpace' xrefstyle='select: title'/>
+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
+<xref linkend='XcmsFormatOfPrefix' xrefstyle='select: title'/>
+and
+<xref linkend='XcmsPrefixOfFormat' xrefstyle='select: title'/>).
+</para>
+<para>
+<!-- .LP -->
+If the
+<structname>XcmsColorSpace</structname>
+structure is already accessible in the color management system,
+<xref linkend='XcmsAddColorSpace' xrefstyle='select: title'/>
+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
+<xref linkend='XcmsFormatOfPrefix' xrefstyle='select: title'/>.
+</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
+<xref linkend='XcmsFormatOfPrefix' xrefstyle='select: title'/>
+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,
+<xref linkend='XcmsFormatOfPrefix' xrefstyle='select: title'/>
+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
+<xref linkend='XcmsPrefixOfFormat' xrefstyle='select: title'/>.
+</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
+<xref linkend='XcmsPrefixOfFormat' xrefstyle='select: title'/>
+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
+<xref linkend='XcmsAddColorSpace' xrefstyle='select: title'/>
+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
+<xref linkend='XcmsFormatOfPrefix' xrefstyle='select: title'/>
+and
+<xref linkend='XcmsPrefixOfFormat' xrefstyle='select: title'/>).
+<!-- .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 <= i < 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>unsigned int <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>unsigned int <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 frame='topbot'>
+ <?dbfo keep-together="auto" ?>
+ <tgroup cols='3' align='left' colsep='0' rowsep='0'>
+ <colspec colname='c1' colwidth='1.0*'/>
+ <colspec colname='c2' colwidth='1.0*'/>
+ <colspec colname='c3' colwidth='1.0*'/>
+ <thead>
+ <row rowsep='1'>
+ <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
+<citetitle>Inter-Client Communication Conventions Manual</citetitle>.
+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
+<xref linkend='XcmsAddFunctionSet' xrefstyle='select: title'/>.
+</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
+<xref linkend='XcmsAddFunctionSet' xrefstyle='select: title'/>
+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,
+<xref linkend='XcmsAddFunctionSet' xrefstyle='select: title'/>
+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
+<xref linkend='XcmsFormatOfPrefix' xrefstyle='select: title'/>
+and
+<xref linkend='XcmsPrefixOfFormat' xrefstyle='select: title'/>).
+</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
+<xref linkend='XcmsAddFunctionSet' xrefstyle='select: title'/>.
+</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>
Index: create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/libX11/CH08.xml
===================================================================
--- create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/libX11/CH08.xml (nonexistent)
+++ create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/libX11/CH08.xml (revision 5)
@@ -0,0 +1,5990 @@
+<?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
+<xref linkend='XFillRectangle' xrefstyle='select: title'/>,
+which sets the pixmap to a known value.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To clear a rectangular area of a given window, use
+<xref linkend='XClearArea' xrefstyle='select: title'/>.
+</para>
+<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>int <parameter>x</parameter></paramdef>
+ <paramdef>int <parameter>y</parameter></paramdef>
+ <paramdef>unsigned int <parameter>width</parameter></paramdef>
+ <paramdef>unsigned int <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.
+ </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, 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'>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, which are the dimensions of the rectangle.
+ </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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XClearArea' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XClearArea' xrefstyle='select: title'/>
+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
+<xref linkend='XClearWindow' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XClearWindow' xrefstyle='select: title'/>
+function clears the entire area in the specified window and is
+equivalent to
+<xref linkend='XClearArea' xrefstyle='select: title'/>
+(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 -->
+<xref linkend='XClearWindow' xrefstyle='select: title'/>
+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
+<xref linkend='XCopyArea' xrefstyle='select: title'/>.
+</para>
+<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>Drawable <parameter>src</parameter></paramdef>
+ <paramdef>Drawable <parameter>dest</parameter></paramdef>
+ <paramdef>GC <parameter>gc</parameter></paramdef>
+ <paramdef>int <parameter>src_x</parameter></paramdef>
+ <paramdef>int <parameter>src_y</parameter></paramdef>
+ <paramdef>unsigned int <parameter>width</parameter></paramdef>
+ <paramdef>unsigned int <parameter>height</parameter></paramdef>
+ <paramdef>int <parameter>dest_x</parameter></paramdef>
+ <paramdef>int <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.
+ </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, which are the dimensions of both the source
+and destination rectangles.
+ </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, which are relative to the origin of the
+destination rectangle and specify its upper-left corner.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XCopyArea' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XCopyArea' xrefstyle='select: title'/>
+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
+<xref linkend='XCopyPlane' xrefstyle='select: title'/>.
+</para>
+<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>Drawable <parameter>src</parameter></paramdef>
+ <paramdef>Drawable <parameter>dest</parameter></paramdef>
+ <paramdef>GC <parameter>gc</parameter></paramdef>
+ <paramdef>int <parameter>src_x</parameter></paramdef>
+ <paramdef>int <parameter>src_y</parameter></paramdef>
+ <paramdef>unsigned int <parameter>width</parameter></paramdef>
+ <paramdef>unsigned int <parameter>height</parameter></paramdef>
+ <paramdef>int <parameter>dest_x</parameter></paramdef>
+ <paramdef>int <parameter>dest_y</parameter></paramdef>
+ <paramdef>unsigned long <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.
+ </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, which are the dimensions of both the source
+and destination rectangles.
+ </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, which are relative to the origin of the
+destination rectangle and specify its upper-left corner.
+ </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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XCopyPlane' xrefstyle='select: title'/>
+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,
+<xref linkend='XCopyPlane' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XCopyPlane' xrefstyle='select: title'/>
+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
+<xref linkend='XDrawPoint' xrefstyle='select: title'/>.
+</para>
+<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>int <parameter>x</parameter></paramdef>
+ <paramdef>int <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>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To draw multiple points in a given drawable, use
+<xref linkend='XDrawPoints' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XDrawPoint' xrefstyle='select: title'/>
+function uses the foreground pixel and function components of the
+GC to draw a single point into the specified drawable;
+<xref linkend='XDrawPoints' xrefstyle='select: title'/>
+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.
+<xref linkend='XDrawPoints' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XDrawPoint' xrefstyle='select: title'/>
+can generate
+<errorname>BadDrawable</errorname>,
+<errorname>BadGC</errorname>,
+and
+<errorname>BadMatch</errorname>
+errors.
+<xref linkend='XDrawPoints' xrefstyle='select: title'/>
+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
+<xref linkend='XDrawLine' xrefstyle='select: title'/>.
+</para>
+<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>int <parameter>x1</parameter></paramdef>
+ <paramdef>int <parameter>y1</parameter></paramdef>
+ <paramdef>int <parameter>x2</parameter></paramdef>
+ <paramdef>int <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>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To draw multiple lines in a given drawable, use
+<xref linkend='XDrawLines' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To draw multiple, unconnected lines in a given drawable,
+use
+<xref linkend='XDrawSegments' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XDrawLine' xrefstyle='select: title'/>
+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,
+<xref linkend='XDrawLine' xrefstyle='select: title'/>
+does not draw a pixel more than once.
+If lines intersect, the intersecting pixels are drawn multiple times.
+</para>
+<para>
+<!-- .LP -->
+The
+<xref linkend='XDrawLines' xrefstyle='select: title'/>
+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,
+<xref linkend='XDrawLines' xrefstyle='select: title'/>
+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
+<xref linkend='XDrawSegments' xrefstyle='select: title'/>
+function draws multiple, unconnected lines.
+For each segment,
+<xref linkend='XDrawSegments' xrefstyle='select: title'/>
+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,
+<xref linkend='XDrawSegments' xrefstyle='select: title'/>
+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
+<xref linkend='XDrawLines' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XDrawLine' xrefstyle='select: title'/>,
+<xref linkend='XDrawLines' xrefstyle='select: title'/>,
+and
+<xref linkend='XDrawSegments' xrefstyle='select: title'/>
+can generate
+<errorname>BadDrawable</errorname>,
+<errorname>BadGC</errorname>,
+and
+<errorname>BadMatch</errorname>
+errors.
+<xref linkend='XDrawLines' xrefstyle='select: title'/>
+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
+<xref linkend='XDrawRectangle' xrefstyle='select: title'/>.
+</para>
+<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>int <parameter>x</parameter></paramdef>
+ <paramdef>int <parameter>y</parameter></paramdef>
+ <paramdef>unsigned int <parameter>width</parameter></paramdef>
+ <paramdef>unsigned int <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'>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, which specify the upper-left corner 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, which specify the dimensions of the
+rectangle.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To draw the outline of multiple rectangles
+in a given drawable, use
+<xref linkend='XDrawRectangles' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XDrawRectangle' xrefstyle='select: title'/>
+and
+<xref linkend='XDrawRectangles' xrefstyle='select: title'/>
+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.
+<xref linkend='XDrawRectangles' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XDrawRectangle' xrefstyle='select: title'/>
+and
+<xref linkend='XDrawRectangles' xrefstyle='select: title'/>
+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
+<xref linkend='XDrawArc' xrefstyle='select: title'/>.
+</para>
+<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>int <parameter>x</parameter></paramdef>
+ <paramdef>int <parameter>y</parameter></paramdef>
+ <paramdef>unsigned int <parameter>width</parameter></paramdef>
+ <paramdef>unsigned int <parameter>height</parameter></paramdef>
+ <paramdef>int <parameter>angle1</parameter></paramdef>
+ <paramdef>int <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.
+ </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, 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'>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, which are the major and minor axes of the
+arc.
+ </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>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To draw multiple arcs in a given drawable, use
+<xref linkend='XDrawArcs' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .EQ -->
+delim %%
+<!-- .EN -->
+<xref linkend='XDrawArc' xrefstyle='select: title'/>
+draws a single circular or elliptical arc, and
+<xref linkend='XDrawArcs' xrefstyle='select: title'/>
+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,
+<xref linkend='XDrawArc' xrefstyle='select: title'/>
+or
+<xref linkend='XDrawArcs' xrefstyle='select: title'/>
+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,
+<xref linkend='XDrawArc' xrefstyle='select: title'/>
+and
+<xref linkend='XDrawArcs' xrefstyle='select: title'/>
+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,
+<xref linkend='XDrawArc' xrefstyle='select: title'/>
+and
+<xref linkend='XDrawArcs' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XDrawArc' xrefstyle='select: title'/>
+and
+<xref linkend='XDrawArcs' xrefstyle='select: title'/>
+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
+<xref linkend='XFillRectangle' xrefstyle='select: title'/>.
+</para>
+<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>int <parameter>x</parameter></paramdef>
+ <paramdef>int <parameter>y</parameter></paramdef>
+ <paramdef>unsigned int <parameter>width</parameter></paramdef>
+ <paramdef>unsigned int <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'>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, 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'>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, which are the dimensions of the rectangle to
+be filled.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To fill multiple rectangular areas in a given drawable, use
+<xref linkend='XFillRectangles' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XFillRectangle' xrefstyle='select: title'/>
+and
+<xref linkend='XFillRectangles' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XFillRectangles' xrefstyle='select: title'/>
+fills the rectangles in the order listed in the array.
+For any given rectangle,
+<xref linkend='XFillRectangle' xrefstyle='select: title'/>
+and
+<xref linkend='XFillRectangles' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XFillRectangle' xrefstyle='select: title'/>
+and
+<xref linkend='XFillRectangles' xrefstyle='select: title'/>
+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
+<xref linkend='XFillPolygon' xrefstyle='select: title'/>.
+<indexterm><primary>Polygons</primary><secondary>filling</secondary></indexterm>
+<indexterm><primary>Filling</primary><secondary>polygon</secondary></indexterm>
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+<xref linkend='XFillPolygon' xrefstyle='select: title'/>
+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.
+<xref linkend='XFillPolygon' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XFillPolygon' xrefstyle='select: title'/>
+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
+<xref linkend='XFillArc' xrefstyle='select: title'/>.
+</para>
+<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>int <parameter>x</parameter></paramdef>
+ <paramdef>int <parameter>y</parameter></paramdef>
+ <paramdef>unsigned int <parameter>width</parameter></paramdef>
+ <paramdef>unsigned int <parameter>height</parameter></paramdef>
+ <paramdef>int <parameter>angle1</parameter></paramdef>
+ <paramdef>int <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.
+ </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, 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'>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, which are the major and minor axes of the
+arc.
+ </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>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To fill multiple arcs in a given drawable, use
+<xref linkend='XFillArcs' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+For each arc,
+<xref linkend='XFillArc' xrefstyle='select: title'/>
+or
+<xref linkend='XFillArcs' xrefstyle='select: title'/>
+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.
+<xref linkend='XFillArcs' xrefstyle='select: title'/>
+fills the arcs in the order listed in the array.
+For any given arc,
+<xref linkend='XFillArc' xrefstyle='select: title'/>
+and
+<xref linkend='XFillArcs' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XFillArc' xrefstyle='select: title'/>
+and
+<xref linkend='XFillArcs' xrefstyle='select: title'/>
+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
+<xref linkend='XLoadQueryFont' xrefstyle='select: title'/>
+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
+<citetitle>X Logical Font Description Conventions</citetitle>.
+</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
+<xref linkend='XLoadFont' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XLoadFont' xrefstyle='select: title'/>
+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
+<citetitle>X Logical Font Description Conventions</citetitle>.
+If
+<xref linkend='XLoadFont' xrefstyle='select: title'/>
+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
+<xref linkend='XUnloadFont' xrefstyle='select: title'/>.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XLoadFont' xrefstyle='select: title'/>
+can generate
+<errorname>BadAlloc</errorname>
+and
+<errorname>BadName</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To return information about an available font, use
+<xref linkend='XQueryFont' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XQueryFont' xrefstyle='select: title'/>
+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
+<xref linkend='XGContextFromGC' xrefstyle='select: title'/>).
+If the font does not exist,
+<xref linkend='XQueryFont' xrefstyle='select: title'/>
+returns NULL.
+To free this data, use
+<xref linkend='XFreeFontInfo' xrefstyle='select: title'/>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To perform a
+<xref linkend='XLoadFont' xrefstyle='select: title'/>
+and
+<xref linkend='XQueryFont' xrefstyle='select: title'/>
+in a single operation, use
+<xref linkend='XLoadQueryFont' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XLoadQueryFont' xrefstyle='select: title'/>
+function provides the most common way for accessing a font.
+<xref linkend='XLoadQueryFont' xrefstyle='select: title'/>
+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,
+<xref linkend='XLoadQueryFont' xrefstyle='select: title'/>
+returns NULL.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XLoadQueryFont' xrefstyle='select: title'/>
+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
+<xref linkend='XQueryFont' xrefstyle='select: title'/>
+or
+<xref linkend='XLoadQueryFont' xrefstyle='select: title'/>,
+use
+<xref linkend='XFreeFont' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XFreeFont' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XFreeFont' xrefstyle='select: title'/>
+can generate a
+<errorname>BadFont</errorname>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To return a given font property, use
+<xref linkend='XGetFontProperty' xrefstyle='select: title'/>.
+</para>
+<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>unsigned long *<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>
+<!-- .LP -->
+<!-- .eM -->
+Given the atom for that property,
+the
+<xref linkend='XGetFontProperty' xrefstyle='select: title'/>
+function returns the value of the specified font property.
+<xref linkend='XGetFontProperty' xrefstyle='select: title'/>
+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"><X11/Xatom.h></filename>.
+<indexterm type="file"><primary><filename class="headerfile">X11/Xatom.h</filename></primary></indexterm>
+<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/Xatom.h></filename></secondary></indexterm>
+<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/Xatom.h></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
+<xref linkend='XLoadFont' xrefstyle='select: title'/>,
+use
+<xref linkend='XUnloadFont' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XUnloadFont' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XUnloadFont' xrefstyle='select: title'/>
+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
+<xref linkend='XListFonts' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XListFonts' xrefstyle='select: title'/>
+function returns an array of available font names
+(as controlled by the font search path; see
+<xref linkend='XSetFontPath' xrefstyle='select: title'/>)
+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,
+<xref linkend='XListFonts' xrefstyle='select: title'/>
+returns NULL.
+The client should call
+<xref linkend='XFreeFontNames' xrefstyle='select: title'/>
+when finished with the result to free the memory.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To free a font name array, use
+<xref linkend='XFreeFontNames' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XFreeFontNames' xrefstyle='select: title'/>
+function frees the array and strings returned by
+<xref linkend='XListFonts' xrefstyle='select: title'/>
+or
+<xref linkend='XListFontsWithInfo' xrefstyle='select: title'/>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain the names and information about available fonts, use
+<xref linkend='XListFontsWithInfo' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XListFontsWithInfo' xrefstyle='select: title'/>
+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
+<xref linkend='XLoadQueryFont' xrefstyle='select: title'/>
+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,
+<xref linkend='XListFontsWithInfo' xrefstyle='select: title'/>
+returns NULL.
+</para>
+<para>
+<!-- .LP -->
+To free only the allocated name array,
+the client should call
+<xref linkend='XFreeFontNames' xrefstyle='select: title'/>.
+To free both the name array and the font information array
+or to free just the font information array,
+the client should call
+<xref linkend='XFreeFontInfo' xrefstyle='select: title'/>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To free font structures and font names, use
+<xref linkend='XFreeFontInfo' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XFreeFontInfo' xrefstyle='select: title'/>
+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
+<xref linkend='XLoadQueryFont' xrefstyle='select: title'/>)
+is passed, the structure is freed,
+but the font is not closed; use
+<xref linkend='XUnloadFont' xrefstyle='select: title'/>
+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
+<xref linkend='XTextWidth' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To determine the width of a 2-byte character string, use
+<xref linkend='XTextWidth16' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .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
+<xref linkend='XTextExtents' xrefstyle='select: title'/>.
+</para>
+<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 *<parameter>font_ascent_return</parameter></paramdef>
+ <paramdef>int *<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>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To compute the bounding box of a 2-byte character string in a given font, use
+<xref linkend='XTextExtents16' xrefstyle='select: title'/>.
+</para>
+<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 *<parameter>font_ascent_return</parameter></paramdef>
+ <paramdef>int *<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XTextExtents' xrefstyle='select: title'/>
+and
+<xref linkend='XTextExtents16' xrefstyle='select: title'/>
+functions
+perform the size computation locally and, thereby,
+avoid the round-trip overhead of
+<xref linkend='XQueryTextExtents' xrefstyle='select: title'/>
+and
+<xref linkend='XQueryTextExtents16' xrefstyle='select: title'/>.
+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
+<xref linkend='XQueryTextExtents' xrefstyle='select: title'/>.
+</para>
+<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 *<parameter>font_ascent_return</parameter></paramdef>
+ <paramdef>int *<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>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To query the server for the bounding box of a 2-byte character string
+in a given font, use
+<xref linkend='XQueryTextExtents16' xrefstyle='select: title'/>.
+</para>
+<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 *<parameter>font_ascent_return</parameter></paramdef>
+ <paramdef>int *<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XQueryTextExtents' xrefstyle='select: title'/>
+and
+<xref linkend='XQueryTextExtents16' xrefstyle='select: title'/>
+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
+<xref linkend='XTextExtents' xrefstyle='select: title'/>
+and
+<xref linkend='XTextExtents16' xrefstyle='select: title'/>.
+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 -->
+<xref linkend='XQueryTextExtents' xrefstyle='select: title'/>
+and
+<xref linkend='XQueryTextExtents16' xrefstyle='select: title'/>
+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
+<xref linkend='XDrawText' xrefstyle='select: title'/>
+and
+<xref linkend='XDrawText16' xrefstyle='select: title'/>
+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
+<xref linkend='XDrawImageString' xrefstyle='select: title'/>.
+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
+<xref linkend='XDrawText' xrefstyle='select: title'/>.
+</para>
+<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>int <parameter>x</parameter></paramdef>
+ <paramdef>int <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.
+ </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, 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'>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>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To draw 2-byte characters in a given drawable, use
+<xref linkend='XDrawText16' xrefstyle='select: title'/>.
+</para>
+<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>int <parameter>x</parameter></paramdef>
+ <paramdef>int <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.
+ </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, 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'>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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XDrawText16' xrefstyle='select: title'/>
+function is similar to
+<xref linkend='XDrawText' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XDrawText' xrefstyle='select: title'/>
+and
+<xref linkend='XDrawText16' xrefstyle='select: title'/>
+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
+<xref linkend='XDrawString' xrefstyle='select: title'/>.
+</para>
+<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>int <parameter>x</parameter></paramdef>
+ <paramdef>int <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.
+ </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, 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'>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>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To draw 2-byte characters in a given drawable, use
+<xref linkend='XDrawString16' xrefstyle='select: title'/>.
+</para>
+<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>int <parameter>x</parameter></paramdef>
+ <paramdef>int <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.
+ </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, 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'>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>
+<!-- .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
+<xref linkend='XDrawString16' xrefstyle='select: title'/>,
+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 -->
+<xref linkend='XDrawString' xrefstyle='select: title'/>
+and
+<xref linkend='XDrawString16' xrefstyle='select: title'/>
+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
+<xref linkend='XDrawImageString' xrefstyle='select: title'/>.
+</para>
+<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>int <parameter>x</parameter></paramdef>
+ <paramdef>int <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.
+ </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, 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'>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>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To draw 2-byte image text characters in a given drawable, use
+<xref linkend='XDrawImageString16' xrefstyle='select: title'/>.
+</para>
+<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>int <parameter>x</parameter></paramdef>
+ <paramdef>int <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.
+ </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, 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'>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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XDrawImageString16' xrefstyle='select: title'/>
+function is similar to
+<xref linkend='XDrawImageString' xrefstyle='select: title'/>
+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
+<xref linkend='XQueryTextExtents' xrefstyle='select: title'/>
+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
+<xref linkend='XDrawImageString' xrefstyle='select: title'/>,
+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 -->
+<xref linkend='XDrawImageString' xrefstyle='select: title'/>
+and
+<xref linkend='XDrawImageString16' xrefstyle='select: title'/>
+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 <link linkend="Manipulating_Images">section 16.8</link>).
+</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
+<xref linkend='XInitImage' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XInitImage' xrefstyle='select: title'/>
+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,
+<xref linkend='XInitImage' xrefstyle='select: title'/>
+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
+<xref linkend='XPutImage' xrefstyle='select: title'/>.
+</para>
+<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>int <parameter>src_x</parameter></paramdef>
+ <paramdef>int <parameter>src_y</parameter></paramdef>
+ <paramdef>int <parameter>dest_x</parameter></paramdef>
+ <paramdef>int <parameter>dest_y</parameter></paramdef>
+ <paramdef>unsigned int <parameter>width</parameter></paramdef>
+ <paramdef>unsigned int <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.
+ </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, which are relative to the origin of the
+drawable and are the coordinates of the subimage.
+ </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 of the subimage, which define the dimensions
+of the rectangle.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XPutImage' xrefstyle='select: title'/>
+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,
+<xref linkend='XPutImage' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XPutImage' xrefstyle='select: title'/>
+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
+<xref linkend='XGetImage' xrefstyle='select: title'/>.
+This function specifically supports rudimentary screen dumps.
+</para>
+<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>int <parameter>x</parameter></paramdef>
+ <paramdef>int <parameter>y</parameter></paramdef>
+ <paramdef>unsigned int <parameter>width</parameter></paramdef>
+ <paramdef>unsigned int <parameter>height</parameter></paramdef>
+ <paramdef>unsigned long <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.
+ </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, 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'>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 of the subimage, which define the dimensions
+of the rectangle.
+ </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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XGetImage' xrefstyle='select: title'/>
+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>,
+<xref linkend='XGetImage' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XGetImage' xrefstyle='select: title'/>
+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,
+<xref linkend='XGetImage' xrefstyle='select: title'/>
+returns NULL.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XGetImage' xrefstyle='select: title'/>
+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
+<xref linkend='XGetSubImage' xrefstyle='select: title'/>.
+</para>
+<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>int <parameter>x</parameter></paramdef>
+ <paramdef>int <parameter>y</parameter></paramdef>
+ <paramdef>unsigned int <parameter>width</parameter></paramdef>
+ <paramdef>unsigned int <parameter>height</parameter></paramdef>
+ <paramdef>unsigned long <parameter>plane_mask</parameter></paramdef>
+ <paramdef>int <parameter>format</parameter></paramdef>
+ <paramdef>XImage *<parameter>dest_image</parameter></paramdef>
+ <paramdef>int <parameter>dest_x</parameter></paramdef>
+ <paramdef>int <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.
+ </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, 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'>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 of the subimage, which define the dimensions
+of the rectangle.
+ </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.
+ </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, 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>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XGetSubImage' xrefstyle='select: title'/>
+function updates dest_image with the specified subimage in the same manner as
+<xref linkend='XGetImage' xrefstyle='select: title'/>.
+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>,
+<xref linkend='XGetSubImage' xrefstyle='select: title'/>
+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,
+<xref linkend='XGetSubImage' xrefstyle='select: title'/>
+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,
+<xref linkend='XGetSubImage' xrefstyle='select: title'/>
+returns NULL.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XGetSubImage' xrefstyle='select: title'/>
+can generate
+<errorname>BadDrawable</errorname>,
+<errorname>BadGC</errorname>,
+<errorname>BadMatch</errorname>,
+and
+<errorname>BadValue</errorname>
+errors.
+<!-- .bp -->
+
+
+</para>
+</sect1>
+</chapter>
Index: create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/libX11/CH09.xml
===================================================================
--- create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/libX11/CH09.xml (nonexistent)
+++ create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/libX11/CH09.xml (revision 5)
@@ -0,0 +1,2011 @@
+<?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
+<xref linkend='XReparentWindow' xrefstyle='select: title'/>.
+There is no way to move a window between screens.
+</para>
+<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>int <parameter>x</parameter></paramdef>
+ <paramdef>int <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.
+ </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 of the position in the new parent window.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+If the specified window is mapped,
+<xref linkend='XReparentWindow' xrefstyle='select: title'/>
+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,
+<xref linkend='XReparentWindow' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XReparentWindow' xrefstyle='select: title'/>
+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 <link linkend='Using_X_Server_Connection_Close_Operations'>section 2.6</link>.
+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
+<xref linkend='XChangeSaveSet' xrefstyle='select: title'/>.
+</para>
+<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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window that you want to add to or delete from the client's
+save-set.
+ </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>
+<!-- .LP -->
+<!-- .eM -->
+Depending on the specified mode,
+<xref linkend='XChangeSaveSet' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XChangeSaveSet' xrefstyle='select: title'/>
+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
+<xref linkend='XAddToSaveSet' xrefstyle='select: title'/>.
+</para>
+<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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window that you want to add to the client's save-set.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XAddToSaveSet' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XAddToSaveSet' xrefstyle='select: title'/>
+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
+<xref linkend='XRemoveFromSaveSet' xrefstyle='select: title'/>.
+</para>
+<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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window that you want to delete from the client's save-set.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XRemoveFromSaveSet' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XRemoveFromSaveSet' xrefstyle='select: title'/>
+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
+<xref linkend='XInstallColormap' xrefstyle='select: title'/>,
+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
+<xref linkend='XUninstallColormap' xrefstyle='select: title'/>
+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
+<xref linkend='XInstallColormap' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XInstallColormap' xrefstyle='select: title'/>
+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
+<xref linkend='XCreateWindow' xrefstyle='select: title'/>,
+<xref linkend='XCreateSimpleWindow' xrefstyle='select: title'/>,
+<xref linkend='XChangeWindowAttributes' xrefstyle='select: title'/>,
+or
+<xref linkend='XSetWindowColormap' xrefstyle='select: title'/>.
+</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
+<xref linkend='XInstallColormap' xrefstyle='select: title'/>,
+the X server generates a
+<symbol>ColormapNotify</symbol>
+event on each window that has that colormap.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XInstallColormap' xrefstyle='select: title'/>
+can generate a
+<errorname>BadColor</errorname>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To uninstall a colormap, use
+<xref linkend='XUninstallColormap' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XUninstallColormap' xrefstyle='select: title'/>
+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
+<xref linkend='XUninstallColormap' xrefstyle='select: title'/>,
+the X server generates a
+<symbol>ColormapNotify</symbol>
+event on each window that has that colormap.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XUninstallColormap' xrefstyle='select: title'/>
+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
+<xref linkend='XListInstalledColormaps' xrefstyle='select: title'/>.
+</para>
+<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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window that determines the screen.
+ </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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XListInstalledColormaps' xrefstyle='select: title'/>
+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
+<xref linkend='XFree' xrefstyle='select: title'/>.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XListInstalledColormaps' xrefstyle='select: title'/>
+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
+<xref linkend='XSetFontPath' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XSetFontPath' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XSetFontPath' xrefstyle='select: title'/>
+can generate a
+<errorname>BadValue</errorname>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To get the current font search path, use
+<xref linkend='XGetFontPath' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XGetFontPath' xrefstyle='select: title'/>
+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
+<xref linkend='XFreeFontPath' xrefstyle='select: title'/>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To free data returned by
+<xref linkend='XGetFontPath' xrefstyle='select: title'/>,
+use
+<xref linkend='XFreeFontPath' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XFreeFontPath' xrefstyle='select: title'/>
+function
+frees the data allocated by
+<xref linkend='XGetFontPath' xrefstyle='select: title'/>.
+</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
+<xref linkend='XGrabServer' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XGrabServer' xrefstyle='select: title'/>
+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
+<xref linkend='XUngrabServer' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XUngrabServer' xrefstyle='select: title'/>
+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
+<xref linkend='XKillClient' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XKillClient' xrefstyle='select: title'/>
+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 <link linkend="Closing_the_Display">section 2.5</link>).
+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 -->
+<xref linkend='XKillClient' xrefstyle='select: title'/>
+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
+<xref linkend='XSetScreenSaver' xrefstyle='select: title'/>.
+</para>
+<indexterm significance="preferred"><primary>XSetScreenSaver</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='XSetScreenSaver'>
+<funcprototype>
+ <funcdef><function>XSetScreenSaver</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>int <parameter>timeout</parameter></paramdef>
+ <paramdef>int <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>
+<!-- .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 −1 restores the default.
+Other negative values generate a
+<errorname>BadValue</errorname>
+error.
+If the timeout value is nonzero,
+<xref linkend='XSetScreenSaver' xrefstyle='select: title'/>
+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
+<xref linkend='XForceScreenSaver' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XSetScreenSaver' xrefstyle='select: title'/>
+can generate a
+<errorname>BadValue</errorname>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To force the screen saver on or off, use
+<xref linkend='XForceScreenSaver' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+If the specified mode is
+<symbol>ScreenSaverActive</symbol>
+and the screen saver currently is deactivated,
+<xref linkend='XForceScreenSaver' xrefstyle='select: title'/>
+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,
+<xref linkend='XForceScreenSaver' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XForceScreenSaver' xrefstyle='select: title'/>
+can generate a
+<errorname>BadValue</errorname>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To activate the screen saver, use
+<xref linkend='XActivateScreenSaver' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To reset the screen saver, use
+<xref linkend='XResetScreenSaver' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To get the current screen saver values, use
+<xref linkend='XGetScreenSaver' xrefstyle='select: title'/>.
+</para>
+<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 *<parameter>timeout_return</parameter></paramdef>
+ <paramdef>int *<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>
+<!-- .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 <citetitle>X Window System Protocol</citetitle>.
+</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
+<xref linkend='XAddHost' xrefstyle='select: title'/>.
+</para>
+<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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>host</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the host that is to be added.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XAddHost' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XAddHost' xrefstyle='select: title'/>
+can generate
+<errorname>BadAccess</errorname>
+and
+<errorname>BadValue</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To add multiple hosts at one time, use
+<xref linkend='XAddHosts' xrefstyle='select: title'/>.
+</para>
+<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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>hosts</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies each host that is to be added.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_hosts</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of hosts.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XAddHosts' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XAddHosts' xrefstyle='select: title'/>
+can generate
+<errorname>BadAccess</errorname>
+and
+<errorname>BadValue</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain a host list, use
+<xref linkend='XListHosts' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XListHosts' xrefstyle='select: title'/>
+function returns the current access control list as well as whether the use
+of the list at connection setup was enabled or disabled.
+<xref linkend='XListHosts' xrefstyle='select: title'/>
+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
+<xref linkend='XFree' xrefstyle='select: title'/>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To remove a single host, use
+<xref linkend='XRemoveHost' xrefstyle='select: title'/>.
+</para>
+<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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>host</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the host that is to be removed.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XRemoveHost' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XRemoveHost' xrefstyle='select: title'/>
+can generate
+<errorname>BadAccess</errorname>
+and
+<errorname>BadValue</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To remove multiple hosts at one time, use
+<xref linkend='XRemoveHosts' xrefstyle='select: title'/>.
+</para>
+<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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>hosts</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies each host that is to be removed.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>num_hosts</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of hosts.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XRemoveHosts' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XRemoveHosts' xrefstyle='select: title'/>
+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
+<xref linkend='XSetAccessControl' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XSetAccessControl' xrefstyle='select: title'/>
+function either enables or disables the use of the access control list
+at each connection setup.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XSetAccessControl' xrefstyle='select: title'/>
+can generate
+<errorname>BadAccess</errorname>
+and
+<errorname>BadValue</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To enable access control, use
+<xref linkend='XEnableAccessControl' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XEnableAccessControl' xrefstyle='select: title'/>
+function enables the use of the access control list at each connection setup.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XEnableAccessControl' xrefstyle='select: title'/>
+can generate a
+<errorname>BadAccess</errorname>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To disable access control, use
+<xref linkend='XDisableAccessControl' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XDisableAccessControl' xrefstyle='select: title'/>
+function disables the use of the access control list at each connection setup.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XDisableAccessControl' xrefstyle='select: title'/>
+can generate a
+<errorname>BadAccess</errorname>
+error.
+<!-- .bp -->
+
+</para>
+</sect2>
+</sect1>
+</chapter>
Index: create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/libX11/CH10.xml
===================================================================
--- create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/libX11/CH10.xml (nonexistent)
+++ create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/libX11/CH10.xml (revision 5)
@@ -0,0 +1,4719 @@
+<?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='Events'>
+<title>Events</title>
+
+<para>
+A client application communicates with the X server through the connection you establish with
+the XOpenDisplay function. A client application sends requests to the X server over this
+connection. These requests are made by the Xlib functions that are called in the client application.
+Many Xlib functions cause the X server to generate events, and the user’s typing or moving the
+pointer can generate events asynchronously. The X server returns events to the client on the same
+connection.
+</para>
+<para>
+This chapter discusses the following topics associated with events:
+</para>
+
+<itemizedlist>
+ <listitem><para>Event types</para></listitem>
+ <listitem><para>Event structures</para></listitem>
+ <listitem><para>Event masks</para></listitem>
+ <listitem><para>Event processing</para></listitem>
+</itemizedlist>
+
+<para>
+Functions for handling events are dealt with in
+<link linkend='Event_Handling_Functions'>the next chapter</link>.
+</para>
+
+<sect1 id="Event_Types">
+<title>Event Types</title>
+<!-- .XS -->
+<!-- (SN Event Types -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Event</primary><secondary>types</secondary></indexterm>
+An event is data generated asynchronously by the X server as a result of some
+device activity or as side effects of a request sent by an Xlib function.
+<indexterm><primary>Event</primary></indexterm>
+Device-related events propagate from the source window to ancestor windows
+until some client application has selected that event type
+or until the event is explicitly discarded.
+The X server generally sends an event to a client application
+only if the client has specifically asked to be informed of that event type,
+typically by setting the event-mask attribute of the window.
+The mask can also be set when you create a window
+or by changing the window's
+event-mask.
+You can also mask out events that would propagate to ancestor windows
+by manipulating the
+do-not-propagate mask of the window's attributes.
+However,
+<symbol>MappingNotify</symbol>
+events are always sent to all clients.
+<indexterm><primary>Input Control</primary></indexterm>
+<indexterm><primary>Output Control</primary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+An event type describes a specific event generated by the X server.
+For each event type,
+a corresponding constant name is defined in
+<filename class="headerfile"><X11/X.h></filename>,
+<indexterm type="file"><primary><filename class="headerfile">X11/X.h</filename></primary></indexterm>
+<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/X.h></filename></secondary></indexterm>
+<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/X.h></filename></secondary></indexterm>
+which is used when referring to an event type.
+<indexterm><primary>Event</primary><secondary>categories</secondary></indexterm>
+The following table lists the event category
+and its associated event type or types.
+The processing associated with these events is discussed in section 10.5.
+</para>
+<para>
+<!-- .LP -->
+<!-- .\".CP T 1 -->
+<!-- .\"Event Categories and Event Types -->
+</para>
+<para>
+<!-- .LP -->
+<informaltable frame='topbot'>
+ <?dbfo keep-together="always" ?>
+ <tgroup cols='2' align='left' colsep='0' rowsep='0'>
+ <colspec colname='c1' colwidth='1.0*'/>
+ <colspec colname='c2' colwidth='4.0*'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Event Category</entry>
+ <entry>Event Type</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>Keyboard events</entry>
+ <entry><symbol>KeyPress</symbol>,
+ <symbol>KeyRelease</symbol></entry>
+ </row>
+ <row>
+ <entry>Pointer events</entry>
+ <entry><symbol>ButtonPress</symbol>,
+ <symbol>ButtonRelease</symbol>,
+ <symbol>MotionNotify</symbol></entry>
+ </row>
+ <row>
+ <entry>Window crossing events</entry>
+ <entry><symbol>EnterNotify</symbol>,
+ <symbol>LeaveNotify</symbol></entry>
+ </row>
+ <row>
+ <entry>Input focus events</entry>
+ <entry><symbol>FocusIn</symbol>,
+ <symbol>FocusOut</symbol></entry>
+ </row>
+ <row>
+ <entry>Keymap state notification event</entry>
+ <entry><symbol>KeymapNotify</symbol></entry>
+ </row>
+ <row>
+ <entry>Exposure events</entry>
+ <entry><symbol>Expose</symbol>,
+ <symbol>GraphicsExpose</symbol>,
+ <symbol>NoExpose</symbol></entry>
+ </row>
+ <row>
+ <entry>Structure control events</entry>
+ <entry><symbol>CirculateRequest</symbol>,
+ <symbol>ConfigureRequest</symbol>,
+ <symbol>MapRequest</symbol>,
+ <symbol>ResizeRequest</symbol></entry>
+ </row>
+ <row>
+ <entry>Window state notification events</entry>
+ <entry>
+ <symbol>CirculateNotify</symbol>,
+ <symbol>ConfigureNotify</symbol>,
+ <symbol>CreateNotify</symbol>,
+ <symbol>DestroyNotify</symbol>,
+ <symbol>GravityNotify</symbol>,
+ <symbol>MapNotify</symbol>,
+ <symbol>MappingNotify</symbol>,
+ <symbol>ReparentNotify</symbol>,
+ <symbol>UnmapNotify</symbol>,
+ <symbol>VisibilityNotify</symbol></entry>
+ </row>
+ <row>
+ <entry>Colormap state notification event</entry>
+ <entry><symbol>ColormapNotify</symbol></entry>
+ </row>
+ <row>
+ <entry>Client communication events</entry>
+ <entry><symbol>ClientMessage</symbol>,
+ <symbol>PropertyNotify</symbol>,
+ <symbol>SelectionClear</symbol>,
+ <symbol>SelectionNotify</symbol>,
+ <symbol>SelectionRequest</symbol></entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<!-- .\".LP -->
+<!-- .\"Table 8-1 lists the event types and the Xlib functions that could cause -->
+<!-- .\"the X server to generate that event type. -->
+<!-- .\"The event types are listed alphabetically. -->
+<!-- .\"Note that the error event is not listed in this table. -->
+<!-- .\"For a list of the constants associated with an error event, see the Handling -->
+<!-- .\"Errors section in this chapter. -->
+<!-- .\".LP -->
+<!-- .\".so eventtable -->
+</para>
+</sect1>
+<sect1 id="Event_Structures">
+<title>Event Structures</title>
+<!-- .XS -->
+<!-- (SN Event Structures -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+For each event type,
+a corresponding structure is declared in
+<filename class="headerfile"><X11/Xlib.h></filename>.
+<indexterm type="file"><primary><filename class="headerfile">X11/Xlib.h</filename></primary></indexterm>
+<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/Xlib.h></filename></secondary></indexterm>
+<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/Xlib.h></filename></secondary></indexterm>
+All the event structures have the following common members:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XAnyEvent</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+ int type;
+ unsigned long serial; /* # of last request processed by server */
+ Bool send_event; /* true if this came from a SendEvent request */
+ Display *display; /* Display the event was read from */
+ Window window;
+} XAnyEvent;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The type member is set to the event type constant name that uniquely identifies
+it.
+For example, when the X server reports a
+<symbol>GraphicsExpose</symbol>
+event to a client application, it sends an
+<structname>XGraphicsExposeEvent</structname>
+structure with the type member set to
+<symbol>GraphicsExpose</symbol>.
+The display member is set to a pointer to the display the event was read on.
+The send_event member is set to
+<symbol>True</symbol>
+if the event came from a
+<systemitem>SendEvent</systemitem>
+protocol request.
+The serial member is set from the serial number reported in the protocol
+but expanded from the 16-bit least-significant bits to a full 32-bit value.
+The window member is set to the window that is most useful to toolkit
+dispatchers.
+</para>
+<para>
+<!-- .LP -->
+The X server can send events at any time in the input stream.
+Xlib stores any events received while waiting for a reply in an event queue
+for later use.
+Xlib also provides functions that allow you to check events in the event queue
+(see <link linkend="Event_Queue_Management">section 11.3</link>).
+</para>
+<para>
+<!-- .LP -->
+In addition to the individual structures declared for each event type, the
+<structname>XEvent</structname>
+structure is a union of the individual structures declared for each event type.
+Depending on the type,
+you should access members of each event by using the
+<structname>XEvent</structname>
+union.
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XEvent</primary></indexterm>
+<!-- .sM -->
+</para>
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef union _XEvent {
+ int type; /* must not be changed */
+ XAnyEvent xany;
+ XKeyEvent xkey;
+ XButtonEvent xbutton;
+ XMotionEvent xmotion;
+ XCrossingEvent xcrossing;
+ XFocusChangeEvent xfocus;
+ XExposeEvent xexpose;
+ XGraphicsExposeEvent xgraphicsexpose;
+ XNoExposeEvent xnoexpose;
+ XVisibilityEvent xvisibility;
+ XCreateWindowEvent xcreatewindow;
+ XDestroyWindowEvent xdestroywindow;
+ XUnmapEvent xunmap;
+ XMapEvent xmap;
+ XMapRequestEvent xmaprequest;
+ XReparentEvent xreparent;
+ XConfigureEvent xconfigure;
+ XGravityEvent xgravity;
+ XResizeRequestEvent xresizerequest;
+ XConfigureRequestEvent xconfigurerequest;
+ XCirculateEvent xcirculate;
+ XCirculateRequestEvent xcirculaterequest;
+ XPropertyEvent xproperty;
+ XSelectionClearEvent xselectionclear;
+ XSelectionRequestEvent xselectionrequest;
+ XSelectionEvent xselection;
+ XColormapEvent xcolormap;
+ XClientMessageEvent xclient;
+ XMappingEvent xmapping;
+ XErrorEvent xerror;
+ XKeymapEvent xkeymap;
+ long pad[24];
+} XEvent;
+</literallayout>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+An
+<structname>XEvent</structname>
+structure's first entry always is the type member,
+which is set to the event type.
+The second member always is the serial number of the protocol request
+that generated the event.
+The third member always is send_event,
+which is a
+<type>Bool</type>
+that indicates if the event was sent by a different client.
+The fourth member always is a display,
+which is the display that the event was read from.
+Except for keymap events,
+the fifth member always is a window,
+which has been carefully selected to be useful to toolkit dispatchers.
+To avoid breaking toolkits,
+the order of these first five entries is not to change.
+Most events also contain a time member,
+which is the time at which an event occurred.
+In addition, a pointer to the generic event must be cast before it
+is used to access any other information in the structure.
+</para>
+</sect1>
+<sect1 id="Event_Masks">
+<title>Event Masks</title>
+<!-- .XS -->
+<!-- (SN Event Masks -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>Event mask</primary></indexterm>
+Clients select event reporting of most events relative to a window.
+To do this, pass an event mask to an Xlib event-handling
+function that takes an event_mask argument.
+The bits of the event mask are defined in
+<filename class="headerfile"><X11/X.h></filename>.
+<indexterm type="file"><primary><filename class="headerfile">X11/X.h</filename></primary></indexterm>
+<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/X.h></filename></secondary></indexterm>
+<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/X.h></filename></secondary></indexterm>
+Each bit in the event mask maps to an event mask name,
+which describes the event or events you want the X server to
+return to a client application.
+</para>
+<para>
+<!-- .LP -->
+Unless the client has specifically asked for them,
+most events are not reported to clients when they are generated.
+Unless the client suppresses them by setting graphics-exposures in the GC to
+<symbol>False</symbol>,
+<symbol>GraphicsExpose</symbol>
+and
+<symbol>NoExpose</symbol>
+are reported by default as a result of
+<xref linkend='XCopyPlane' xrefstyle='select: title'/>
+and
+<xref linkend='XCopyArea' xrefstyle='select: title'/>.
+<symbol>SelectionClear</symbol>,
+<symbol>SelectionRequest</symbol>,
+<symbol>SelectionNotify</symbol>,
+or
+<symbol>ClientMessage</symbol>
+cannot be masked.
+Selection-related events are only sent to clients cooperating
+with selections
+(see <link linkend="Obtaining_and_Changing_Window_Properties">section 4.5</link>).
+When the keyboard or pointer mapping is changed,
+<symbol>MappingNotify</symbol>
+is always sent to clients.
+</para>
+<para>
+<!-- .LP -->
+<!-- .\"Table 8-2 -->
+The following table
+lists the event mask constants you can pass to
+the event_mask argument and
+the circumstances in which you would want to specify the
+event mask:
+</para>
+<!-- .LP -->
+<!-- .\" .CP T 2 -->
+<!-- .\"Event Mask Definitions -->
+<informaltable frame='topbot'>
+ <?dbfo keep-together="auto" ?>
+ <tgroup cols='2' align='left' colsep='0' rowsep='0'>
+ <colspec colname='c1' colwidth='1.0*'/>
+ <colspec colname='c2' colwidth='2.5*'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Event Mask</entry>
+ <entry>Circumstances</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><symbol>NoEventMask</symbol></entry>
+ <entry>No events wanted</entry>
+ </row>
+ <row>
+ <entry><symbol>KeyPressMask</symbol></entry>
+ <entry>Keyboard down events wanted</entry>
+ </row>
+ <row>
+ <entry><symbol>KeyReleaseMask</symbol></entry>
+ <entry>Keyboard up events wanted</entry>
+ </row>
+ <row>
+ <entry><symbol>ButtonPressMask</symbol></entry>
+ <entry>Pointer button down events wanted</entry>
+ </row>
+ <row>
+ <entry><symbol>ButtonReleaseMask</symbol></entry>
+ <entry>Pointer button up events wanted</entry>
+ </row>
+ <row>
+ <entry><symbol>EnterWindowMask</symbol></entry>
+ <entry>Pointer window entry events wanted</entry>
+ </row>
+ <row>
+ <entry><symbol>LeaveWindowMask</symbol></entry>
+ <entry>Pointer window leave events wanted</entry>
+ </row>
+ <row>
+ <entry><symbol>PointerMotionMask</symbol></entry>
+ <entry>Pointer motion events wanted</entry>
+ </row>
+ <row>
+ <entry><symbol>PointerMotionHintMask</symbol></entry>
+ <entry>Pointer motion hints wanted</entry>
+ </row>
+ <row>
+ <entry><symbol>Button1MotionMask</symbol></entry>
+ <entry>Pointer motion while button 1 down</entry>
+ </row>
+ <row>
+ <entry><symbol>Button2MotionMask</symbol></entry>
+ <entry>Pointer motion while button 2 down</entry>
+ </row>
+ <row>
+ <entry><symbol>Button3MotionMask</symbol></entry>
+ <entry>Pointer motion while button 3 down</entry>
+ </row>
+ <row>
+ <entry><symbol>Button4MotionMask</symbol></entry>
+ <entry>Pointer motion while button 4 down</entry>
+ </row>
+ <row>
+ <entry><symbol>Button5MotionMask</symbol></entry>
+ <entry>Pointer motion while button 5 down</entry>
+ </row>
+ <row>
+ <entry><symbol>ButtonMotionMask</symbol></entry>
+ <entry>Pointer motion while any button down</entry>
+ </row>
+ <row>
+ <entry><symbol>KeymapStateMask</symbol></entry>
+ <entry>Keyboard state wanted at window entry and focus in</entry>
+ </row>
+ <row>
+ <entry><symbol>ExposureMask</symbol></entry>
+ <entry>Any exposure wanted</entry>
+ </row>
+ <row>
+ <entry><symbol>VisibilityChangeMask</symbol></entry>
+ <entry>Any change in visibility wanted</entry>
+ </row>
+ <row>
+ <entry><symbol>StructureNotifyMask</symbol></entry>
+ <entry>Any change in window structure wanted</entry>
+ </row>
+ <row>
+ <entry><symbol>ResizeRedirectMask</symbol></entry>
+ <entry>Redirect resize of this window</entry>
+ </row>
+ <row>
+ <entry><symbol>SubstructureNotifyMask</symbol></entry>
+ <entry>Substructure notification wanted</entry>
+ </row>
+ <row>
+ <entry><symbol>SubstructureRedirectMask</symbol></entry>
+ <entry>Redirect structure requests on children</entry>
+ </row>
+ <row>
+ <entry><symbol>FocusChangeMask</symbol></entry>
+ <entry>Any change in input focus wanted</entry>
+ </row>
+ <row>
+ <entry><symbol>PropertyChangeMask</symbol></entry>
+ <entry>Any change in property wanted</entry>
+ </row>
+ <row>
+ <entry><symbol>ColormapChangeMask</symbol></entry>
+ <entry>Any change in colormap wanted</entry>
+ </row>
+ <row>
+ <entry><symbol>OwnerGrabButtonMask</symbol></entry>
+ <entry>Automatic grabs should activate with owner_events set to True</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+<!-- .LP -->
+</para>
+</sect1>
+<sect1 id="Event_Processing_Overview">
+<title>Event Processing Overview</title>
+<!-- .XS -->
+<!-- (SN Event Processing Overview -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The event reported to a client application during event processing
+depends on which event masks you provide as the event-mask attribute
+for a window.
+For some event masks, there is a one-to-one correspondence between
+the event mask constant and the event type constant.
+For example, if you pass the event mask
+<symbol>ButtonPressMask</symbol>,
+the X server sends back only
+<symbol>ButtonPress</symbol>
+events.
+<indexterm><primary>CurrentTime</primary></indexterm>
+Most events contain a time member,
+which is the time at which an event occurred.
+</para>
+<para>
+<!-- .LP -->
+In other cases, one event mask constant can map to several event type constants.
+For example, if you pass the event mask
+<symbol>SubstructureNotifyMask</symbol>,
+the X server can send back
+<symbol>CirculateNotify</symbol>,
+<symbol>ConfigureNotify</symbol>,
+<symbol>CreateNotify</symbol>,
+<symbol>DestroyNotify</symbol>,
+<symbol>GravityNotify</symbol>,
+<symbol>MapNotify</symbol>,
+<symbol>ReparentNotify</symbol>,
+or
+<symbol>UnmapNotify</symbol>
+events.
+</para>
+<para>
+<!-- .LP -->
+In another case,
+two event masks can map to one event type.
+For example,
+if you pass either
+<symbol>PointerMotionMask</symbol>
+or
+<symbol>ButtonMotionMask</symbol>,
+the X server sends back
+a
+<symbol>MotionNotify</symbol>
+event.
+</para>
+<para>
+<!-- .LP -->
+The following table
+lists the event mask,
+its associated event type or types,
+and the structure name associated with the event type.
+Some of these structures actually are typedefs to a generic structure
+that is shared between two event types.
+Note that N.A. appears in columns for which the information is not applicable.
+</para>
+<!-- .LP -->
+<!-- .ps 9 -->
+<!-- .nr PS 9 -->
+<informaltable frame='topbot'>
+ <?dbfo keep-together="auto" ?>
+ <tgroup cols='4' align='left' colsep='0' rowsep='0'>
+ <colspec colname='c1' colwidth='1.2*'/>
+ <colspec colname='c2' colwidth='1.0*'/>
+ <colspec colname='c3' colwidth='1.2*'/>
+ <colspec colname='c4' colwidth='1.0*'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Event Mask</entry>
+ <entry>Event Type</entry>
+ <entry>Structure</entry>
+ <entry>Generic Structure</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <para>ButtonMotionMask</para>
+ <para>Button1MotionMask</para>
+ <para>Button2MotionMask</para>
+ <para>Button3MotionMask</para>
+ <para>Button4MotionMask</para>
+ <para>Button5MotionMask</para>
+ </entry>
+ <entry>MotionNotify</entry>
+ <entry>XPointerMovedEvent</entry>
+ <entry>XMotionEvent</entry>
+ </row>
+ <row>
+ <entry>ButtonPressMask</entry>
+ <entry>ButtonPress</entry>
+ <entry>XButtonPressedEvent</entry>
+ <entry>XButtonEvent</entry>
+ </row>
+ <row>
+ <entry>ButtonReleaseMask</entry>
+ <entry>ButtonRelease</entry>
+ <entry>XButtonReleasedEvent</entry>
+ <entry>XButtonEvent</entry>
+ </row>
+ <row>
+ <entry>ColormapChangeMask</entry>
+ <entry>ColormapNotify</entry>
+ <entry>XColormapEvent</entry>
+ </row>
+ <row>
+ <entry>EnterWindowMask</entry>
+ <entry>EnterNotify</entry>
+ <entry>XEnterWindowEvent</entry>
+ <entry>XCrossingEvent</entry>
+ </row>
+ <row>
+ <entry>LeaveWindowMask</entry>
+ <entry>LeaveNotify</entry>
+ <entry>XLeaveWindowEvent</entry>
+ <entry>XCrossingEvent</entry>
+ </row>
+ <row>
+ <entry>ExposureMask</entry>
+ <entry>Expose</entry>
+ <entry>XExposeEvent </entry>
+ </row>
+ <row>
+ <entry morerows='1'>GCGraphicsExposures in GC</entry>
+ <entry>GraphicsExpose</entry>
+ <entry>XGraphicsExposeEvent</entry>
+ </row>
+ <row>
+ <entry>NoExpose</entry>
+ <entry>XNoExposeEvent</entry>
+ </row>
+ <row>
+ <entry morerows='1'>FocusChangeMask</entry>
+ <entry>FocusIn</entry>
+ <entry>XFocusInEvent</entry>
+ <entry>XFocusChangeEvent</entry>
+ </row>
+ <row>
+ <entry>FocusOut</entry>
+ <entry>XFocusOutEvent</entry>
+ <entry>XFocusChangeEvent</entry>
+ </row>
+ <row>
+ <entry>KeymapStateMask</entry>
+ <entry>KeymapNotify</entry>
+ <entry>XKeymapEvent</entry>
+ </row>
+ <row>
+ <entry>KeyPressMask</entry>
+ <entry>KeyPress</entry>
+ <entry>XKeyPressedEvent</entry>
+ <entry>XKeyEvent</entry>
+ </row>
+ <row>
+ <entry>KeyReleaseMask</entry>
+ <entry>KeyRelease</entry>
+ <entry>XKeyReleasedEvent</entry>
+ <entry>XKeyEvent</entry>
+ </row>
+ <row>
+ <entry>OwnerGrabButtonMask</entry>
+ <entry>N.A.</entry>
+ <entry>N.A.</entry>
+ </row>
+ <row>
+ <entry>PointerMotionMask</entry>
+ <entry>MotionNotify</entry>
+ <entry>XPointerMovedEvent</entry>
+ <entry>XMotionEvent</entry>
+ </row>
+ <row>
+ <entry>PointerMotionHintMask</entry>
+ <entry>N.A.</entry>
+ <entry>N.A.</entry>
+ </row>
+ <row>
+ <entry>PropertyChangeMask</entry>
+ <entry>PropertyNotify</entry>
+ <entry>XPropertyEvent</entry>
+ </row>
+ <row>
+ <entry>ResizeRedirectMask</entry>
+ <entry>ResizeRequest</entry>
+ <entry>XResizeRequestEvent</entry>
+ </row>
+ <row>
+ <entry morerows='6'>StructureNotifyMask</entry>
+ <entry>CirculateNotify</entry>
+ <entry>XCirculateEvent</entry>
+ </row>
+ <row>
+ <entry>ConfigureNotify</entry>
+ <entry>XConfigureEvent</entry>
+ </row>
+ <row>
+ <entry>DestroyNotify</entry>
+ <entry>XDestroyWindowEvent</entry>
+ </row>
+ <row>
+ <entry>GravityNotify</entry>
+ <entry>XGravityEvent</entry>
+ </row>
+ <row>
+ <entry>MapNotify</entry>
+ <entry>XMapEvent</entry>
+ </row>
+ <row>
+ <entry>ReparentNotify</entry>
+ <entry>XReparentEvent</entry>
+ </row>
+ <row>
+ <entry>UnmapNotify</entry>
+ <entry>XUnmapEvent</entry>
+ </row>
+ <row>
+ <entry morerows='7'>SubstructureNotifyMask</entry>
+ <entry>CirculateNotify</entry>
+ <entry>XCirculateEvent</entry>
+ </row>
+ <row>
+ <entry>ConfigureNotify</entry>
+ <entry>XConfigureEvent</entry>
+ </row>
+ <row>
+ <entry>CreateNotify</entry>
+ <entry>XCreateWindowEvent</entry>
+ </row>
+ <row>
+ <entry>DestroyNotify</entry>
+ <entry>XDestroyWindowEvent</entry>
+ </row>
+ <row>
+ <entry>GravityNotify</entry>
+ <entry>XGravityEvent</entry>
+ </row>
+ <row>
+ <entry>MapNotify</entry>
+ <entry>XMapEvent</entry>
+ </row>
+ <row>
+ <entry>ReparentNotify</entry>
+ <entry>XReparentEvent</entry>
+ </row>
+ <row>
+ <entry>UnmapNotify</entry>
+ <entry>XUnmapEvent</entry>
+ </row>
+ <row>
+ <entry morerows='2'>SubstructureRedirectMask</entry>
+ <entry>CirculateRequest</entry>
+ <entry>XCirculateRequestEvent</entry>
+ </row>
+ <row>
+ <entry>ConfigureRequest</entry>
+ <entry>XConfigureRequestEvent</entry>
+ </row>
+ <row>
+ <entry>MapRequest</entry>
+ <entry>XMapRequestEvent</entry>
+ </row>
+ <row>
+ <entry>N.A.</entry>
+ <entry>ClientMessage</entry>
+ <entry>XClientMessageEvent</entry>
+ </row>
+ <row>
+ <entry>N.A.</entry>
+ <entry>MappingNotify</entry>
+ <entry>XMappingEvent</entry>
+ </row>
+ <row>
+ <entry>N.A.</entry>
+ <entry>SelectionClear</entry>
+ <entry>XSelectionClearEvent</entry>
+ </row>
+ <row>
+ <entry>N.A.</entry>
+ <entry>SelectionNotify</entry>
+ <entry>XSelectionEvent</entry>
+ </row>
+ <row>
+ <entry>N.A.</entry>
+ <entry>SelectionRequest</entry>
+ <entry>XSelectionRequestEvent</entry>
+ </row>
+ <row>
+ <entry>VisibilityChangeMask</entry>
+ <entry>VisibilityNotify</entry>
+ <entry>XVisibilityEvent</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+<!-- .LP -->
+The sections that follow describe the processing that occurs
+when you select the different event masks.
+The sections are organized according to these processing categories:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Keyboard and pointer events
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Window crossing events
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Input focus events
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Keymap state notification events
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Exposure events
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Window state notification events
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Structure control events
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Colormap state notification events
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Client communication events
+ </para>
+ </listitem>
+</itemizedlist>
+
+</sect1>
+
+<sect1 id="Keyboard_and_Pointer_Events">
+<title>Keyboard and Pointer Events</title>
+<!-- .XS -->
+<!-- (SN Keyboard and Pointer Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+This section discusses:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Pointer button events
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Keyboard and pointer events
+ </para>
+ </listitem>
+</itemizedlist>
+<sect2 id="Pointer_Button_Events">
+<title>Pointer Button Events</title>
+<!-- .XS -->
+<!-- (SN Pointer Button Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The following describes the event processing that occurs when a pointer button
+press is processed with the pointer in some window w and
+when no active pointer grab is in progress.
+</para>
+<para>
+<!-- .LP -->
+The X server searches the ancestors of w from the root down,
+looking for a passive grab to activate.
+If no matching passive grab on the button exists,
+the X server automatically starts an active grab for the client receiving
+the event and sets the last-pointer-grab time to the current server time.
+The effect is essentially equivalent to an
+<xref linkend='XGrabButton' xrefstyle='select: title'/>
+with these client passed arguments:
+</para>
+<informaltable frame='topbot'>
+ <?dbfo keep-together="always" ?>
+ <tgroup cols='2' align='left' colsep='0' rowsep='0'>
+ <colspec colname='c1' colwidth='1.0*'/>
+ <colspec colname='c2' colwidth='4.0*'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Argument</entry>
+ <entry>Value</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><emphasis remap='I'>w</emphasis></entry>
+ <entry>The event window </entry>
+ </row>
+ <row>
+ <entry><emphasis remap='I'>event_mask</emphasis></entry>
+ <entry>The client's selected pointer events on the event window</entry>
+ </row>
+ <row>
+ <entry><emphasis remap='I'>pointer_mode</emphasis></entry>
+ <entry><symbol>GrabModeAsync</symbol></entry>
+ </row>
+ <row>
+ <entry><emphasis remap='I'>keyboard_mode</emphasis></entry>
+ <entry><symbol>GrabModeAsync</symbol></entry>
+ </row>
+ <row>
+ <entry><emphasis remap='I'>owner_events</emphasis></entry>
+ <entry><symbol>True</symbol>,
+ if the client has selected
+ <symbol>OwnerGrabButtonMask</symbol>
+ on the event window,
+ otherwise
+ <symbol>False</symbol></entry>
+ </row>
+ <row>
+ <entry><emphasis remap='I'>confine_to</emphasis></entry>
+ <entry><symbol>None</symbol></entry>
+ </row>
+ <row>
+ <entry><emphasis remap='I'>cursor</emphasis></entry>
+ <entry><symbol>None</symbol></entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+<!-- .LP -->
+The active grab is automatically terminated when
+the logical state of the pointer has all buttons released.
+Clients can modify the active grab by calling
+<xref linkend='XUngrabPointer' xrefstyle='select: title'/>
+and
+<xref linkend='XChangeActivePointerGrab' xrefstyle='select: title'/>.
+</para>
+</sect2>
+
+<sect2 id="Keyboard_and_Pointer_Events_b">
+<title>Keyboard and Pointer Events</title>
+<!-- .XS -->
+<!-- (SN Keyboard and Pointer Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Events</primary><secondary>ButtonPress</secondary></indexterm>
+<indexterm><primary>Events</primary><secondary>ButtonRelease</secondary></indexterm>
+<indexterm><primary>Events</primary><secondary>KeyPress</secondary></indexterm>
+<indexterm><primary>Events</primary><secondary>KeyRelease</secondary></indexterm>
+<indexterm><primary>Events</primary><secondary>MotionNotify</secondary></indexterm>
+This section discusses the processing that occurs for the
+keyboard events
+<symbol>KeyPress</symbol>
+and
+<symbol>KeyRelease</symbol>
+and the pointer events
+<symbol>ButtonPress</symbol>,
+<symbol>ButtonRelease</symbol>,
+and
+<symbol>MotionNotify</symbol>.
+For information about the keyboard event-handling utilities,
+see <link linkend='Event_Handling_Functions'>chapter 11</link>.
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>KeyPress</primary></indexterm>
+<indexterm significance="preferred"><primary>KeyRelease</primary></indexterm>
+The X server reports
+<symbol>KeyPress</symbol>
+or
+<symbol>KeyRelease</symbol>
+events to clients wanting information about keys that logically change state.
+Note that these events are generated for all keys,
+even those mapped to modifier bits.
+<indexterm significance="preferred"><primary>ButtonPress</primary></indexterm>
+<indexterm significance="preferred"><primary>ButtonRelease</primary></indexterm>
+The X server reports
+<symbol>ButtonPress</symbol>
+or
+<symbol>ButtonRelease</symbol>
+events to clients wanting information about buttons that logically change state.
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>MotionNotify</primary></indexterm>
+The X server reports
+<symbol>MotionNotify</symbol>
+events to clients wanting information about when the pointer logically moves.
+The X server generates this event whenever the pointer is moved
+and the pointer motion begins and ends in the window.
+The granularity of
+<symbol>MotionNotify</symbol>
+events is not guaranteed,
+but a client that selects this event type is guaranteed
+to receive at least one event when the pointer moves and then rests.
+</para>
+<para>
+<!-- .LP -->
+The generation of the logical changes lags the physical changes
+if device event processing is frozen.
+</para>
+<para>
+<!-- .LP -->
+To receive
+<symbol>KeyPress</symbol>,
+<symbol>KeyRelease</symbol>,
+<symbol>ButtonPress</symbol>,
+and
+<symbol>ButtonRelease</symbol>
+events, set
+<symbol>KeyPressMask</symbol>,
+<symbol>KeyReleaseMask</symbol>,
+<symbol>ButtonPressMask</symbol>,
+and
+<symbol>ButtonReleaseMask</symbol>
+bits in the event-mask attribute of the window.
+</para>
+<para>
+<!-- .LP -->
+To receive
+<symbol>MotionNotify</symbol>
+events, set one or more of the following event
+masks bits in the event-mask attribute of the window.
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+<symbol>Button1MotionMask</symbol> - <symbol>Button5MotionMask</symbol>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The client application receives
+<symbol>MotionNotify</symbol>
+events only when one or more of the specified buttons is pressed.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<symbol>ButtonMotionMask</symbol>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The client application receives
+<symbol>MotionNotify</symbol>
+events only when at least one button is pressed.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<symbol>PointerMotionMask</symbol>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The client application receives
+<symbol>MotionNotify</symbol>
+events independent of the state of
+the pointer buttons.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<symbol>PointerMotionHintMask</symbol>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If
+<symbol>PointerMotionHintMask</symbol>
+is selected in combination with one or more of the above masks,
+the X server is free to send only one
+<symbol>MotionNotify</symbol>
+event (with the is_hint member of the
+<type>XPointerMovedEvent</type>
+structure set to
+<symbol>NotifyHint</symbol>)
+to the client for the event window,
+until either the key or button state changes,
+the pointer leaves the event window, or the client calls
+<xref linkend='XQueryPointer' xrefstyle='select: title'/>
+or
+<xref linkend='XGetMotionEvents' xrefstyle='select: title'/>.
+The server still may send
+<symbol>MotionNotify</symbol>
+events without is_hint set to
+<symbol>NotifyHint</symbol>.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+The source of the event is the viewable window that the pointer is in.
+The window used by the X server to report these events depends on
+the window's position in the window hierarchy
+and whether any intervening window prohibits the generation of these events.
+Starting with the source window,
+the X server searches up the window hierarchy until it locates the first
+window specified by a client as having an interest in these events.
+If one of the intervening windows has its do-not-propagate-mask
+set to prohibit generation of the event type,
+the events of those types will be suppressed.
+Clients can modify the actual window used for reporting by performing
+active grabs and, in the case of keyboard events, by using the focus window.
+</para>
+<para>
+<!-- .LP -->
+The structures for these event types contain:
+</para>
+<literallayout class="monospaced">
+typedef struct {
+ int type; /* ButtonPress or ButtonRelease */
+ unsigned long serial; /* # of last request processed by server */
+ Bool send_event; /* true if this came from a SendEvent request */
+ Display *display; /* Display the event was read from */
+ Window window; /* ``event'' window it is reported relative to */
+ Window root; /* root window that the event occurred on */
+ Window subwindow; /* child window */
+ Time time; /* milliseconds */
+ int x, y; /* pointer x, y coordinates in event window */
+ int x_root, y_root; /* coordinates relative to root */
+ unsigned int state; /* key or button mask */
+ unsigned int button; /* detail */
+ Bool same_screen; /* same screen flag */
+} XButtonEvent;
+typedef XButtonEvent XButtonPressedEvent;
+typedef XButtonEvent XButtonReleasedEvent;
+</literallayout>
+
+<literallayout class="monospaced">
+typedef struct {
+ int type; /* KeyPress or KeyRelease */
+ unsigned long serial; /* # of last request processed by server */
+ Bool send_event; /* true if this came from a SendEvent request */
+ Display *display; /* Display the event was read from */
+ Window window; /* ``event'' window it is reported relative to */
+ Window root; /* root window that the event occurred on */
+ Window subwindow; /* child window */
+ Time time; /* milliseconds */
+ int x, y; /* pointer x, y coordinates in event window */
+ int x_root, y_root; /* coordinates relative to root */
+ unsigned int state; /* key or button mask */
+ unsigned int keycode; /* detail */
+ Bool same_screen; /* same screen flag */
+} XKeyEvent;
+typedef XKeyEvent XKeyPressedEvent;
+typedef XKeyEvent XKeyReleasedEvent;
+</literallayout>
+
+<literallayout class="monospaced">
+typedef struct {
+ int type; /* MotionNotify */
+ unsigned long serial; /* # of last request processed by server */
+ Bool send_event; /* true if this came from a SendEvent request */
+ Display *display; /* Display the event was read from */
+ Window window; /* ``event'' window reported relative to */
+ Window root; /* root window that the event occurred on */
+ Window subwindow; /* child window */
+ Time time; /* milliseconds */
+ int x, y; /* pointer x, y coordinates in event window */
+ int x_root, y_root; /* coordinates relative to root */
+ unsigned int state; /* key or button mask */
+ char is_hint; /* detail */
+ Bool same_screen; /* same screen flag */
+} XMotionEvent;
+typedef XMotionEvent XPointerMovedEvent;
+</literallayout>
+
+<para>
+These structures have the following common members:
+window, root, subwindow, time, x, y, x_root, y_root, state, and same_screen.
+The window member is set to the window on which the
+event was generated and is referred to as the event window.
+As long as the conditions previously discussed are met,
+this is the window used by the X server to report the event.
+The root member is set to the source window's root window.
+The x_root and y_root members are set to the pointer's coordinates
+relative to the root window's origin at the time of the event.
+</para>
+
+<para>
+<!-- .LP -->
+The same_screen member is set to indicate whether the event
+window is on the same screen
+as the root window and can be either
+<symbol>True</symbol>
+or
+<symbol>False</symbol>.
+If
+<symbol>True</symbol>,
+the event and root windows are on the same screen.
+If
+<symbol>False</symbol>,
+the event and root windows are not on the same screen.
+</para>
+<para>
+<!-- .LP -->
+If the source window is an inferior of the event window,
+the subwindow member of the structure is set to the child of the event window
+that is the source window or the child of the event window that is
+an ancestor of the source window.
+Otherwise, the X server sets the subwindow member to
+<symbol>None</symbol>.
+The time member is set to the time when the event was generated
+and is expressed in milliseconds.
+</para>
+<para>
+<!-- .LP -->
+If the event window is on the same screen as the root window,
+the x and y members
+are set to the coordinates relative to the event window's origin.
+Otherwise, these members are set to zero.
+</para>
+<para>
+<!-- .LP -->
+The state member is set to indicate the logical state of the pointer buttons
+and modifier keys just prior to the event,
+which is the bitwise inclusive OR of one or more of the
+button or modifier key masks:
+<symbol>Button1Mask</symbol>,
+<symbol>Button2Mask</symbol>,
+<symbol>Button3Mask</symbol>,
+<symbol>Button4Mask</symbol>,
+<symbol>Button5Mask</symbol>,
+<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 -->
+Each of these structures also has a member that indicates the detail.
+For the
+<type>XKeyPressedEvent</type>
+and
+<type>XKeyReleasedEvent</type>
+structures, this member is called a keycode.
+It is set to a number that represents a physical key on the keyboard.
+The keycode is an arbitrary representation for any key on the keyboard
+(see sections <link linkend="Manipulating_the_Keyboard_Encoding">12.7</link>
+ and <link linkend="Using_Keyboard_Utility_Functions">16.1</link>).
+</para>
+<para>
+<!-- .LP -->
+For the
+<type>XButtonPressedEvent</type>
+and
+<type>XButtonReleasedEvent</type>
+structures, this member is called button.
+It represents the pointer button that changed state and can be the
+<symbol>Button1</symbol>,
+<symbol>Button2</symbol>,
+<symbol>Button3</symbol>,
+<symbol>Button4</symbol>,
+or
+<symbol>Button5</symbol>
+value.
+For the
+<type>XPointerMovedEvent</type>
+structure, this member is called is_hint.
+It can be set to
+<symbol>NotifyNormal</symbol>
+or
+<symbol>NotifyHint</symbol>.
+</para>
+<para>
+<!-- .LP -->
+Some of the symbols mentioned in this section have fixed values, as
+follows:
+</para>
+<informaltable frame='topbot'>
+ <?dbfo keep-together="always" ?>
+ <tgroup cols='2' align='left' colsep='0' rowsep='0'>
+ <colspec colname='c1' colwidth='1.0*'/>
+ <colspec colname='c2' colwidth='3.0*'/>
+ <thead>
+ <row rowsep='1'>
+ <entry>Symbol</entry>
+ <entry>Value</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><symbol>Button1MotionMask</symbol></entry>
+ <entry>(1L<<8)</entry>
+ </row>
+ <row>
+ <entry><symbol>Button2MotionMask</symbol></entry>
+ <entry>(1L<<9)</entry>
+ </row>
+ <row>
+ <entry><symbol>Button3MotionMask</symbol></entry>
+ <entry>(1L<<10)</entry>
+ </row>
+ <row>
+ <entry><symbol>Button4MotionMask</symbol></entry>
+ <entry>(1L<<11)</entry>
+ </row>
+ <row>
+ <entry><symbol>Button5MotionMask</symbol></entry>
+ <entry>(1L<<12)</entry>
+ </row>
+ <row>
+ <entry><symbol>Button1Mask</symbol></entry>
+ <entry>(1<<8)</entry>
+ </row>
+ <row>
+ <entry><symbol>Button2Mask</symbol></entry>
+ <entry>(1<<9)</entry>
+ </row>
+ <row>
+ <entry><symbol>Button3Mask</symbol></entry>
+ <entry>(1<<10)</entry>
+ </row>
+ <row>
+ <entry><symbol>Button4Mask</symbol></entry>
+ <entry>(1<<11)</entry>
+ </row>
+ <row>
+ <entry><symbol>Button5Mask</symbol></entry>
+ <entry>(1<<12)</entry>
+ </row>
+ <row>
+ <entry><symbol>ShiftMask</symbol></entry>
+ <entry>(1<<0)</entry>
+ </row>
+ <row>
+ <entry><symbol>LockMask</symbol></entry>
+ <entry>(1<<1)</entry>
+ </row>
+ <row>
+ <entry><symbol>ControlMask</symbol></entry>
+ <entry>(1<<2)</entry>
+ </row>
+ <row>
+ <entry><symbol>Mod1Mask</symbol></entry>
+ <entry>(1<<3)</entry>
+ </row>
+ <row>
+ <entry><symbol>Mod2Mask</symbol></entry>
+ <entry>(1<<4)</entry>
+ </row>
+ <row>
+ <entry><symbol>Mod3Mask</symbol></entry>
+ <entry>(1<<5)</entry>
+ </row>
+ <row>
+ <entry><symbol>Mod4Mask</symbol></entry>
+ <entry>(1<<6)</entry>
+ </row>
+ <row>
+ <entry><symbol>Mod5Mask</symbol></entry>
+ <entry>(1<<7)</entry>
+ </row>
+ <row>
+ <entry><symbol>Button1</symbol></entry>
+ <entry>1</entry>
+ </row>
+ <row>
+ <entry><symbol>Button2</symbol></entry>
+ <entry>2</entry>
+ </row>
+ <row>
+ <entry><symbol>Button3</symbol></entry>
+ <entry>3</entry>
+ </row>
+ <row>
+ <entry><symbol>Button4</symbol></entry>
+ <entry>4</entry>
+ </row>
+ <row>
+ <entry><symbol>Button5</symbol></entry>
+ <entry>5</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+</sect2>
+</sect1>
+<sect1 id='Window_EntryExit_Events'>
+<title>Window Entry/Exit Events</title>
+<!-- .XS -->
+<!-- (SN Window Entry/Exit Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Events</primary><secondary>EnterNotify</secondary></indexterm>
+<indexterm><primary>Events</primary><secondary>LeaveNotify</secondary></indexterm>
+This section describes the processing that
+occurs for the window crossing events
+<symbol>EnterNotify</symbol>
+and
+<symbol>LeaveNotify</symbol>.
+<indexterm significance="preferred"><primary>EnterNotify</primary></indexterm>
+<indexterm significance="preferred"><primary>LeaveNotify</primary></indexterm>
+If a pointer motion or a window hierarchy change causes the
+pointer to be in a different window than before, the X server reports
+<symbol>EnterNotify</symbol>
+or
+<symbol>LeaveNotify</symbol>
+events to clients who have selected for these events.
+All
+<symbol>EnterNotify</symbol>
+and
+<symbol>LeaveNotify</symbol>
+events caused by a hierarchy change are
+generated after any hierarchy event
+(<symbol>UnmapNotify</symbol>,
+<symbol>MapNotify</symbol>,
+<symbol>ConfigureNotify</symbol>,
+<symbol>GravityNotify</symbol>,
+<symbol>CirculateNotify</symbol>)
+caused by that change;
+however, the X protocol does not constrain the ordering of
+<symbol>EnterNotify</symbol>
+and
+<symbol>LeaveNotify</symbol>
+events with respect to
+<symbol>FocusOut</symbol>,
+<symbol>VisibilityNotify</symbol>,
+and
+<symbol>Expose</symbol>
+events.
+</para>
+<para>
+<!-- .LP -->
+This contrasts with
+<symbol>MotionNotify</symbol>
+events, which are also generated when the pointer moves
+but only when the pointer motion begins and ends in a single window.
+An
+<symbol>EnterNotify</symbol>
+or
+<symbol>LeaveNotify</symbol>
+event also can be generated when some client application calls
+<xref linkend='XGrabPointer' xrefstyle='select: title'/>
+and
+<xref linkend='XUngrabPointer' xrefstyle='select: title'/>.
+</para>
+<para>
+<!-- .LP -->
+To receive
+<symbol>EnterNotify</symbol>
+or
+<symbol>LeaveNotify</symbol>
+events, set the
+<symbol>EnterWindowMask</symbol>
+or
+<symbol>LeaveWindowMask</symbol>
+bits of the event-mask attribute of the window.
+</para>
+<para>
+<!-- .LP -->
+The structure for these event types contains:
+</para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XCrossingEvent</primary></indexterm>
+<indexterm significance="preferred"><primary>XEnterWindowEvent</primary></indexterm>
+<indexterm significance="preferred"><primary>XLeaveWindowEvent</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+ int type; /* EnterNotify or LeaveNotify */
+ unsigned long serial; /* # of last request processed by server */
+ Bool send_event; /* true if this came from a SendEvent request */
+ Display *display; /* Display the event was read from */
+ Window window; /* ``event'' window reported relative to */
+ Window root; /* root window that the event occurred on */
+ Window subwindow; /* child window */
+ Time time; /* milliseconds */
+ int x, y; /* pointer x, y coordinates in event window */
+ int x_root, y_root; /* coordinates relative to root */
+ int mode; /* NotifyNormal, NotifyGrab, NotifyUngrab */
+ int detail;
+ /*
+ * NotifyAncestor, NotifyVirtual, NotifyInferior,
+ * NotifyNonlinear,NotifyNonlinearVirtual
+ */
+ Bool same_screen; /* same screen flag */
+ Bool focus; /* boolean focus */
+ unsigned int state; /* key or button mask */
+} XCrossingEvent;
+typedef XCrossingEvent XEnterWindowEvent;
+typedef XCrossingEvent XLeaveWindowEvent;
+</literallayout>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The window member is set to the window on which the
+<symbol>EnterNotify</symbol>
+or
+<symbol>LeaveNotify</symbol>
+event was generated and is referred to as the event window.
+This is the window used by the X server to report the event,
+and is relative to the root
+window on which the event occurred.
+The root member is set to the root window of the screen
+on which the event occurred.
+</para>
+<para>
+<!-- .LP -->
+For a
+<symbol>LeaveNotify</symbol>
+event,
+if a child of the event window contains the initial position of the pointer,
+the subwindow component is set to that child.
+Otherwise, the X server sets the subwindow member to
+<symbol>None</symbol>.
+For an
+<symbol>EnterNotify</symbol>
+event, if a child of the event window contains the final pointer position,
+the subwindow component is set to that child or
+<symbol>None</symbol>.
+</para>
+<para>
+<!-- .LP -->
+The time member is set to the time when the event was generated
+and is expressed in milliseconds.
+The x and y members are set to the coordinates of the pointer position in
+the event window.
+This position is always the pointer's final position,
+not its initial position.
+If the event window is on the same
+screen as the root window, x and y are the pointer coordinates
+relative to the event window's origin.
+Otherwise, x and y are set to zero.
+The x_root and y_root members are set to the pointer's coordinates relative to the
+root window's origin at the time of the event.
+</para>
+<para>
+<!-- .LP -->
+The same_screen member is set to indicate whether the event window is on the same screen
+as the root window and can be either
+<symbol>True</symbol>
+or
+<symbol>False</symbol>.
+If
+<symbol>True</symbol>,
+the event and root windows are on the same screen.
+If
+<symbol>False</symbol>,
+the event and root windows are not on the same screen.
+</para>
+<para>
+<!-- .LP -->
+The focus member is set to indicate whether the event window is the focus window or an
+inferior of the focus window.
+The X server can set this member to either
+<symbol>True</symbol>
+or
+<symbol>False</symbol>.
+If
+<symbol>True</symbol>,
+the event window is the focus window or an inferior of the focus window.
+If
+<symbol>False</symbol>,
+the event window is not the focus window or an inferior of the focus window.
+</para>
+<para>
+<!-- .LP -->
+The state member is set to indicate the state of the pointer buttons and
+modifier keys just prior to the
+event.
+The X server can set this member to the bitwise inclusive OR of one
+or more of the button or modifier key masks:
+<symbol>Button1Mask</symbol>,
+<symbol>Button2Mask</symbol>,
+<symbol>Button3Mask</symbol>,
+<symbol>Button4Mask</symbol>,
+<symbol>Button5Mask</symbol>,
+<symbol>ShiftMask</symbol>,
+<symbol>LockMask</symbol>,
+<symbol>ControlMask</symbol>,
+<symbol>Mod1Mask</symbol>,
+<symbol>Mod2Mask</symbol>,
+<symbol>Mod3Mask</symbol>,
+<symbol>Mod4Mask</symbol>,
+<symbol>Mod5Mask</symbol>.
+</para>
+<para>
+<!-- .LP -->
+The mode member is set to indicate whether the events are normal events,
+pseudo-motion events
+when a grab activates, or pseudo-motion events when a grab deactivates.
+The X server can set this member to
+<symbol>NotifyNormal</symbol>,
+<symbol>NotifyGrab</symbol>,
+or
+<symbol>NotifyUngrab</symbol>.
+</para>
+<para>
+<!-- .LP -->
+The detail member is set to indicate the notify detail and can be
+<symbol>NotifyAncestor</symbol>,
+<symbol>NotifyVirtual</symbol>,
+<symbol>NotifyInferior</symbol>,
+<symbol>NotifyNonlinear</symbol>,
+or
+<symbol>NotifyNonlinearVirtual</symbol>.
+</para>
+<sect2 id='Normal_EntryExit_Events'>
+<title>Normal Entry/Exit Events</title>
+<!-- .XS -->
+<!-- (SN Normal Entry/Exit Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<symbol>EnterNotify</symbol>
+and
+<symbol>LeaveNotify</symbol>
+events are generated when the pointer moves from
+one window to another window.
+Normal events are identified by
+<type>XEnterWindowEvent</type>
+or
+<type>XLeaveWindowEvent</type>
+structures whose mode member is set to
+<symbol>NotifyNormal</symbol>.
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+When the pointer moves from window A to window B and A is an inferior of B,
+the X server does the following:
+<!-- .RS -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates a
+<symbol>LeaveNotify</symbol>
+event on window A, with the detail member of the
+<type>XLeaveWindowEvent</type>
+structure set to
+<symbol>NotifyAncestor</symbol>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates a
+<symbol>LeaveNotify</symbol>
+event on each window between window A and window B, exclusive,
+with the detail member of each
+<type>XLeaveWindowEvent</type>
+structure set to
+<symbol>NotifyVirtual</symbol>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates an
+<symbol>EnterNotify</symbol>
+event on window B, with the detail member of the
+<type>XEnterWindowEvent</type>
+structure set to
+<symbol>NotifyInferior</symbol>.
+<!-- .RE -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+When the pointer moves from window A to window B and B is an inferior of A,
+the X server does the following:
+<!-- .RS -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates a
+<symbol>LeaveNotify</symbol>
+event on window A,
+with the detail member of the
+<type>XLeaveWindowEvent</type>
+structure set to
+<symbol>NotifyInferior</symbol>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates an
+<symbol>EnterNotify</symbol>
+event on each window between window A and window B, exclusive, with the
+detail member of each
+<type>XEnterWindowEvent</type>
+structure set to
+<symbol>NotifyVirtual</symbol>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates an
+<symbol>EnterNotify</symbol>
+event on window B, with the detail member of the
+<type>XEnterWindowEvent</type>
+structure set to
+<symbol>NotifyAncestor</symbol>.
+<!-- .RE -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+When the pointer moves from window A to window B
+and window C is their least common ancestor,
+the X server does the following:
+<!-- .RS -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates a
+<symbol>LeaveNotify</symbol>
+event on window A,
+with the detail member of the
+<type>XLeaveWindowEvent</type>
+structure set to
+<symbol>NotifyNonlinear</symbol>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates a
+<symbol>LeaveNotify</symbol>
+event on each window between window A and window C, exclusive,
+with the detail member of each
+<type>XLeaveWindowEvent</type>
+structure set to
+<symbol>NotifyNonlinearVirtual</symbol>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates an
+<symbol>EnterNotify</symbol>
+event on each window between window C and window B, exclusive,
+with the detail member of each
+<type>XEnterWindowEvent</type>
+structure set to
+<symbol>NotifyNonlinearVirtual</symbol>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates an
+<symbol>EnterNotify</symbol>
+event on window B, with the detail member of the
+<type>XEnterWindowEvent</type>
+structure set to
+<symbol>NotifyNonlinear</symbol>.
+<!-- .RE -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+When the pointer moves from window A to window B on different screens,
+the X server does the following:
+<!-- .RS -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates a
+<symbol>LeaveNotify</symbol>
+event on window A,
+with the detail member of the
+<type>XLeaveWindowEvent</type>
+structure set to
+<symbol>NotifyNonlinear</symbol>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If window A is not a root window,
+it generates a
+<symbol>LeaveNotify</symbol>
+event on each window above window A up to and including its root,
+with the detail member of each
+<type>XLeaveWindowEvent</type>
+structure set to
+<symbol>NotifyNonlinearVirtual</symbol>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If window B is not a root window,
+it generates an
+<symbol>EnterNotify</symbol>
+event on each window from window B's root down to but not including
+window B, with the detail member of each
+<type>XEnterWindowEvent</type>
+structure set to
+<symbol>NotifyNonlinearVirtual</symbol>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates an
+<symbol>EnterNotify</symbol>
+event on window B, with the detail member of the
+<type>XEnterWindowEvent</type>
+structure set to
+<symbol>NotifyNonlinear</symbol>.
+<!-- .RE -->
+<!-- .\".SH 3 -->
+ </para>
+ </listitem>
+</itemizedlist>
+</sect2>
+<sect2 id='Grab_and_Ungrab_EntryExit_Events'>
+<title>Grab and Ungrab Entry/Exit Events</title>
+<!-- .XS -->
+<!-- (SN Grab and Ungrab Entry/Exit Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Pseudo-motion mode
+<symbol>EnterNotify</symbol>
+and
+<symbol>LeaveNotify</symbol>
+events are generated when a pointer grab activates or deactivates.
+Events in which the pointer grab activates
+are identified by
+<type>XEnterWindowEvent</type>
+or
+<type>XLeaveWindowEvent</type>
+structures whose mode member is set to
+<symbol>NotifyGrab</symbol>.
+Events in which the pointer grab deactivates
+are identified by
+<type>XEnterWindowEvent</type>
+or
+<type>XLeaveWindowEvent</type>
+structures whose mode member is set to
+<symbol>NotifyUngrab</symbol>
+(see
+<xref linkend='XGrabPointer' xrefstyle='select: title'/>).
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+When a pointer grab activates after any initial warp into a confine_to
+window and before generating any actual
+<symbol>ButtonPress</symbol>
+event that activates the grab,
+G is the grab_window for the grab,
+and P is the window the pointer is in,
+the X server does the following:
+<!-- .RS -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates
+<symbol>EnterNotify</symbol>
+and
+<symbol>LeaveNotify</symbol>
+events (see <link linkend='Normal_EntryExit_Events'>section 10.6.1</link>)
+with the mode members of the
+<type>XEnterWindowEvent</type>
+and
+<type>XLeaveWindowEvent</type>
+structures set to
+<symbol>NotifyGrab</symbol>.
+These events are generated
+as if the pointer were to suddenly warp from
+its current position in P to some position in G.
+However, the pointer does not warp, and the X server uses the pointer position
+as both the initial and final positions for the events.
+<!-- .RE -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+When a pointer grab deactivates after generating any actual
+<symbol>ButtonRelease</symbol>
+event that deactivates the grab,
+G is the grab_window for the grab,
+and P is the window the pointer is in,
+the X server does the following:
+<!-- .RS -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates
+<symbol>EnterNotify</symbol>
+and
+<symbol>LeaveNotify</symbol>
+events (see <link linkend='Normal_EntryExit_Events'>section 10.6.1</link>)
+with the mode members of the
+<type>XEnterWindowEvent</type>
+and
+<type>XLeaveWindowEvent</type>
+structures set to
+<symbol>NotifyUngrab</symbol>.
+These events are generated as if the pointer were to suddenly warp from
+some position in G to its current position in P.
+However, the pointer does not warp, and the X server uses the
+current pointer position as both the
+initial and final positions for the events.
+<!-- .RE -->
+ </para>
+ </listitem>
+</itemizedlist>
+</sect2>
+</sect1>
+<sect1 id="Input_Focus_Events">
+<title>Input Focus Events</title>
+<!-- .XS -->
+<!-- (SN Input Focus Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Events</primary><secondary>FocusIn</secondary></indexterm>
+<indexterm><primary>Events</primary><secondary>FocusOut</secondary></indexterm>
+This section describes the processing that occurs for the input focus events
+<symbol>FocusIn</symbol>
+and
+<symbol>FocusOut</symbol>.
+<indexterm significance="preferred"><primary>FocusIn</primary></indexterm>
+<indexterm significance="preferred"><primary>FocusOut</primary></indexterm>
+The X server can report
+<symbol>FocusIn</symbol>
+or
+<symbol>FocusOut</symbol>
+events to clients wanting information about when the input focus changes.
+The keyboard is always attached to some window
+(typically, the root window or a top-level window),
+which is called the focus window.
+The focus window and the position of the pointer determine the window that
+receives keyboard input.
+Clients may need to know when the input focus changes
+to control highlighting of areas on the screen.
+</para>
+<para>
+<!-- .LP -->
+To receive
+<symbol>FocusIn</symbol>
+or
+<symbol>FocusOut</symbol>
+events, set the
+<symbol>FocusChangeMask</symbol>
+bit in the event-mask attribute of the window.
+</para>
+<para>
+<!-- .LP -->
+The structure for these event types contains:
+</para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XFocusChangeEvent</primary></indexterm>
+<indexterm significance="preferred"><primary>XFocusInEvent</primary></indexterm>
+<indexterm significance="preferred"><primary>XFocusOutEvent</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+ int type; /* FocusIn or FocusOut */
+ unsigned long serial; /* # of last request processed by server */
+ Bool send_event; /* true if this came from a SendEvent request */
+ Display *display; /* Display the event was read from */
+ Window window; /* window of event */
+ int mode; /* NotifyNormal, NotifyGrab, NotifyUngrab */
+ int detail;
+ /*
+ * NotifyAncestor, NotifyVirtual, NotifyInferior,
+ * NotifyNonlinear,NotifyNonlinearVirtual, NotifyPointer,
+ * NotifyPointerRoot, NotifyDetailNone
+ */
+} XFocusChangeEvent;
+typedef XFocusChangeEvent XFocusInEvent;
+typedef XFocusChangeEvent XFocusOutEvent;
+</literallayout>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The window member is set to the window on which the
+<symbol>FocusIn</symbol>
+or
+<symbol>FocusOut</symbol>
+event was generated.
+This is the window used by the X server to report the event.
+The mode member is set to indicate whether the focus events
+are normal focus events,
+focus events while grabbed,
+focus events
+when a grab activates, or focus events when a grab deactivates.
+The X server can set the mode member to
+<symbol>NotifyNormal</symbol>,
+<symbol>NotifyWhileGrabbed</symbol>,
+<symbol>NotifyGrab</symbol>,
+or
+<symbol>NotifyUngrab</symbol>.
+</para>
+<para>
+<!-- .LP -->
+All
+<symbol>FocusOut</symbol>
+events caused by a window unmap are generated after any
+<symbol>UnmapNotify</symbol>
+event; however, the X protocol does not constrain the ordering of
+<symbol>FocusOut</symbol>
+events with respect to
+generated
+<symbol>EnterNotify</symbol>,
+<symbol>LeaveNotify</symbol>,
+<symbol>VisibilityNotify</symbol>,
+and
+<symbol>Expose</symbol>
+events.
+</para>
+<para>
+<!-- .LP -->
+Depending on the event mode,
+the detail member is set to indicate the notify detail and can be
+<symbol>NotifyAncestor</symbol>,
+<symbol>NotifyVirtual</symbol>,
+<symbol>NotifyInferior</symbol>,
+<symbol>NotifyNonlinear</symbol>,
+<symbol>NotifyNonlinearVirtual</symbol>,
+<symbol>NotifyPointer</symbol>,
+<symbol>NotifyPointerRoot</symbol>,
+or
+<symbol>NotifyDetailNone</symbol>.
+</para>
+<sect2 id='Normal_Focus_Events_and_Focus_Events_While_Grabbed'>
+<title>Normal Focus Events and Focus Events While Grabbed</title>
+<!-- .XS -->
+<!-- (SN Normal Focus Events and Focus Events While Grabbed -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Normal focus events are identified by
+<type>XFocusInEvent</type>
+or
+<type>XFocusOutEvent</type>
+structures whose mode member is set to
+<symbol>NotifyNormal</symbol>.
+Focus events while grabbed are identified by
+<type>XFocusInEvent</type>
+or
+<type>XFocusOutEvent</type>
+structures whose mode member is set to
+<symbol>NotifyWhileGrabbed</symbol>.
+The X server processes normal focus and focus events while grabbed according to
+the following:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+When the focus moves from window A to window B, A is an inferior of B,
+and the pointer is in window P,
+the X server does the following:
+<!-- .RS -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates a
+<symbol>FocusOut</symbol>
+event on window A, with the detail member of the
+<type>XFocusOutEvent</type>
+structure set to
+<symbol>NotifyAncestor</symbol>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates a
+<symbol>FocusOut</symbol>
+event on each window between window A and window B, exclusive,
+with the detail member of each
+<type>XFocusOutEvent</type>
+structure set to
+<symbol>NotifyVirtual</symbol>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates a
+<symbol>FocusIn</symbol>
+event on window B, with the detail member of the
+<type>XFocusOutEvent</type>
+structure set to
+<symbol>NotifyInferior</symbol>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If window P is an inferior of window B
+but window P is not window A or an inferior or ancestor of window A,
+it generates a
+<symbol>FocusIn</symbol>
+event on each window below window B, down to and including window P,
+with the detail member of each
+<type>XFocusInEvent</type>
+structure set to
+<symbol>NotifyPointer</symbol>.
+<!-- .RE -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+When the focus moves from window A to window B, B is an inferior of A,
+and the pointer is in window P,
+the X server does the following:
+<!-- .RS -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If window P is an inferior of window A
+but P is not an inferior of window B or an ancestor of B,
+it generates a
+<symbol>FocusOut</symbol>
+event on each window from window P up to but not including window A,
+with the detail member of each
+<type>XFocusOutEvent</type>
+structure set to
+<symbol>NotifyPointer</symbol>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates a
+<symbol>FocusOut</symbol>
+event on window A,
+with the detail member of the
+<type>XFocusOutEvent</type>
+structure set to
+<symbol>NotifyInferior</symbol>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates a
+<symbol>FocusIn</symbol>
+event on each window between window A and window B, exclusive, with the
+detail member of each
+<type>XFocusInEvent</type>
+structure set to
+<symbol>NotifyVirtual</symbol>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates a
+<symbol>FocusIn</symbol>
+event on window B, with the detail member of the
+<type>XFocusInEvent</type>
+structure set to
+<symbol>NotifyAncestor</symbol>.
+<!-- .RE -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+When the focus moves from window A to window B,
+window C is their least common ancestor,
+and the pointer is in window P,
+the X server does the following:
+<!-- .RS -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If window P is an inferior of window A,
+it generates a
+<symbol>FocusOut</symbol>
+event on each window from window P up to but not including window A,
+with the detail member of the
+<type>XFocusOutEvent</type>
+structure set to
+<symbol>NotifyPointer</symbol>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates a
+<symbol>FocusOut</symbol>
+event on window A,
+with the detail member of the
+<type>XFocusOutEvent</type>
+structure set to
+<symbol>NotifyNonlinear</symbol>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates a
+<symbol>FocusOut</symbol>
+event on each window between window A and window C, exclusive,
+with the detail member of each
+<type>XFocusOutEvent</type>
+structure set to
+<symbol>NotifyNonlinearVirtual</symbol>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates a
+<symbol>FocusIn</symbol>
+event on each window between C and B, exclusive,
+with the detail member of each
+<type>XFocusInEvent</type>
+structure set to
+<symbol>NotifyNonlinearVirtual</symbol>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates a
+<symbol>FocusIn</symbol>
+event on window B, with the detail member of the
+<type>XFocusInEvent</type>
+structure set to
+<symbol>NotifyNonlinear</symbol>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If window P is an inferior of window B, it generates a
+<symbol>FocusIn</symbol>
+event on each window below window B down to and including window P,
+with the detail member of the
+<type>XFocusInEvent</type>
+structure set to
+<symbol>NotifyPointer</symbol>.
+<!-- .RE -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+When the focus moves from window A to window B on different screens
+and the pointer is in window P,
+the X server does the following:
+<!-- .RS -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If window P is an inferior of window A, it generates a
+<symbol>FocusOut</symbol>
+event on each window from window P up to but not including window A,
+with the detail member of each
+<type>XFocusOutEvent</type>
+structure set to
+<symbol>NotifyPointer</symbol>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates a
+<symbol>FocusOut</symbol>
+event on window A,
+with the detail member of the
+<type>XFocusOutEvent</type>
+structure set to
+<symbol>NotifyNonlinear</symbol>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If window A is not a root window,
+it generates a
+<symbol>FocusOut</symbol>
+event on each window above window A up to and including its root,
+with the detail member of each
+<type>XFocusOutEvent</type>
+structure set to
+<symbol>NotifyNonlinearVirtual</symbol>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If window B is not a root window,
+it generates a
+<symbol>FocusIn</symbol>
+event on each window from window B's root down to but not including
+window B, with the detail member of each
+<type>XFocusInEvent</type>
+structure set to
+<symbol>NotifyNonlinearVirtual</symbol>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates a
+<symbol>FocusIn</symbol>
+event on window B, with the detail member of each
+<type>XFocusInEvent</type>
+structure set to
+<symbol>NotifyNonlinear</symbol>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If window P is an inferior of window B, it generates a
+<symbol>FocusIn</symbol>
+event on each window below window B down to and including window P,
+with the detail member of each
+<type>XFocusInEvent</type>
+structure set to
+<symbol>NotifyPointer</symbol>.
+<!-- .RE -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+When the focus moves from window A to
+<symbol>PointerRoot</symbol>
+(events sent to the window under the pointer)
+or
+<symbol>None</symbol>
+(discard), and the pointer is in window P,
+the X server does the following:
+<!-- .RS -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If window P is an inferior of window A, it generates a
+<symbol>FocusOut</symbol>
+event on each window from window P up to but not including window A,
+with the detail member of each
+<type>XFocusOutEvent</type>
+structure set to
+<symbol>NotifyPointer</symbol>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates a
+<symbol>FocusOut</symbol>
+event on window A, with the detail member of the
+<type>XFocusOutEvent</type>
+structure set to
+<symbol>NotifyNonlinear</symbol>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If window A is not a root window,
+it generates a
+<symbol>FocusOut</symbol>
+event on each window above window A up to and including its root,
+with the detail member of each
+<type>XFocusOutEvent</type>
+structure set to
+<symbol>NotifyNonlinearVirtual</symbol>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates a
+<symbol>FocusIn</symbol>
+event on the root window of all screens, with the detail member of each
+<type>XFocusInEvent</type>
+structure set to
+<symbol>NotifyPointerRoot</symbol>
+(or
+<symbol>NotifyDetailNone</symbol>).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If the new focus is
+<symbol>PointerRoot</symbol>,
+it generates a
+<symbol>FocusIn</symbol>
+event on each window from window P's root down to and including window P,
+with the detail member of each
+<type>XFocusInEvent</type>
+structure set to
+<symbol>NotifyPointer</symbol>.
+<!-- .RE -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+When the focus moves from
+<symbol>PointerRoot</symbol>
+(events sent to the window under the pointer)
+or
+<symbol>None</symbol>
+to window A, and the pointer is in window P,
+the X server does the following:
+<!-- .RS -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If the old focus is
+<symbol>PointerRoot</symbol>,
+it generates a
+<symbol>FocusOut</symbol>
+event on each window from window P up to and including window P's root,
+with the detail member of each
+<type>XFocusOutEvent</type>
+structure set to
+<symbol>NotifyPointer</symbol>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates a
+<symbol>FocusOut</symbol>
+event on all root windows,
+with the detail member of each
+<type>XFocusOutEvent</type>
+structure set to
+<symbol>NotifyPointerRoot</symbol>
+(or
+<symbol>NotifyDetailNone</symbol>).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If window A is not a root window,
+it generates a
+<symbol>FocusIn</symbol>
+event on each window from window A's root down to but not including window A,
+with the detail member of each
+<type>XFocusInEvent</type>
+structure set to
+<symbol>NotifyNonlinearVirtual</symbol>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates a
+<symbol>FocusIn</symbol>
+event on window A,
+with the detail member of the
+<type>XFocusInEvent</type>
+structure set to
+<symbol>NotifyNonlinear</symbol>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If window P is an inferior of window A, it generates a
+<symbol>FocusIn</symbol>
+event on each window below window A down to and including window P,
+with the detail member of each
+<type>XFocusInEvent</type>
+structure set to
+<symbol>NotifyPointer</symbol>.
+<!-- .RE -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+When the focus moves from
+<symbol>PointerRoot</symbol>
+(events sent to the window under the pointer)
+to
+<symbol>None</symbol>
+(or vice versa), and the pointer is in window P,
+the X server does the following:
+<!-- .RS -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If the old focus is
+<symbol>PointerRoot</symbol>,
+it generates a
+<symbol>FocusOut</symbol>
+event on each window from window P up to and including window P's root,
+with the detail member of each
+<type>XFocusOutEvent</type>
+structure set to
+<symbol>NotifyPointer</symbol>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates a
+<symbol>FocusOut</symbol>
+event on all root windows,
+with the detail member of each
+<type>XFocusOutEvent</type>
+structure set to either
+<symbol>NotifyPointerRoot</symbol>
+or
+<symbol>NotifyDetailNone</symbol>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates a
+<symbol>FocusIn</symbol>
+event on all root windows,
+with the detail member of each
+<type>XFocusInEvent</type>
+structure set to
+<symbol>NotifyDetailNone</symbol>
+or
+<symbol>NotifyPointerRoot</symbol>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If the new focus is
+<symbol>PointerRoot</symbol>,
+it generates a
+<symbol>FocusIn</symbol>
+event on each window from window P's root down to and including window P,
+with the detail member of each
+<type>XFocusInEvent</type>
+structure set to
+<symbol>NotifyPointer</symbol>.
+<!-- .RE -->
+<!-- .\".SH 3 -->
+ </para>
+ </listitem>
+</itemizedlist>
+</sect2>
+<sect2 id="Focus_Events_Generated_by_Grabs">
+<title>Focus Events Generated by Grabs</title>
+<!-- .XS -->
+<!-- (SN Focus Events Generated by Grabs -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Focus events in which the keyboard grab activates
+are identified by
+<type>XFocusInEvent</type>
+or
+<type>XFocusOutEvent</type>
+structures whose mode member is set to
+<symbol>NotifyGrab</symbol>.
+Focus events in which the keyboard grab deactivates
+are identified by
+<type>XFocusInEvent</type>
+or
+<type>XFocusOutEvent</type>
+structures whose mode member is set to
+<symbol>NotifyUngrab</symbol>
+(see
+<xref linkend='XGrabKeyboard' xrefstyle='select: title'/>).
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+When a keyboard grab activates before generating any actual
+<symbol>KeyPress</symbol>
+event that activates the grab,
+G is the grab_window, and F is the current focus,
+the X server does the following:
+<!-- .RS -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates
+<symbol>FocusIn</symbol>
+and
+<symbol>FocusOut</symbol>
+events, with the mode members of the
+<type>XFocusInEvent</type>
+and
+<type>XFocusOutEvent</type>
+structures set to
+<symbol>NotifyGrab</symbol>.
+These events are generated
+as if the focus were to change from
+F to G.
+<!-- .RE -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+When a keyboard grab deactivates after generating any actual
+<symbol>KeyRelease</symbol>
+event that deactivates the grab,
+G is the grab_window, and F is the current focus,
+the X server does the following:
+<!-- .RS -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It generates
+<symbol>FocusIn</symbol>
+and
+<symbol>FocusOut</symbol>
+events, with the mode members of the
+<type>XFocusInEvent</type>
+and
+<type>XFocusOutEvent</type>
+structures set to
+<symbol>NotifyUngrab</symbol>.
+These events are generated
+as if the focus were to change from
+G to F.
+<!-- .RE -->
+ </para>
+ </listitem>
+</itemizedlist>
+</sect2>
+</sect1>
+<sect1 id="Key_Map_State_Notification_Events">
+<title>Key Map State Notification Events</title>
+<!-- .XS -->
+<!-- (SN Key Map State Notification Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Events</primary><secondary>KeymapNotify</secondary></indexterm>
+<indexterm significance="preferred"><primary>KeymapNotify</primary></indexterm>
+The X server can report
+<symbol>KeymapNotify</symbol>
+events to clients that want information about changes in their keyboard state.
+</para>
+<para>
+<!-- .LP -->
+To receive
+<symbol>KeymapNotify</symbol>
+events, set the
+<symbol>KeymapStateMask</symbol>
+bit in the event-mask attribute of the window.
+The X server generates this event immediately after every
+<symbol>EnterNotify</symbol>
+and
+<symbol>FocusIn</symbol>
+event.
+</para>
+<para>
+<!-- .LP -->
+The structure for this event type contains:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XKeymapEvent</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+/* generated on EnterWindow and FocusIn when KeymapState selected */
+typedef struct {
+ int type; /* KeymapNotify */
+ unsigned long serial; /* # of last request processed by server */
+ Bool send_event; /* true if this came from a SendEvent request */
+ Display *display; /* Display the event was read from */
+ Window window;
+ char key_vector[32];
+} XKeymapEvent;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The window member is not used but is present to aid some toolkits.
+The key_vector member is set to the bit vector of the keyboard.
+Each bit set to 1 indicates that the corresponding key
+is currently pressed.
+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>
+</sect1>
+<sect1 id="Exposure_Events">
+<title>Exposure Events</title>
+<!-- .XS -->
+<!-- (SN Exposure Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The X protocol does not guarantee to preserve the contents of window
+regions when
+the windows are obscured or reconfigured.
+Some implementations may preserve the contents of windows.
+Other implementations are free to destroy the contents of windows
+when exposed.
+X expects client applications to assume the responsibility for
+restoring the contents of an exposed window region.
+(An exposed window region describes a formerly obscured window whose
+region becomes visible.)
+Therefore, the X server sends
+<symbol>Expose</symbol>
+events describing the window and the region of the window that has been exposed.
+A naive client application usually redraws the entire window.
+A more sophisticated client application redraws only the exposed region.
+</para>
+<sect2 id="Expose_Events">
+<title>Expose Events</title>
+<!-- .XS -->
+<!-- (SN Expose Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Events</primary><secondary>Expose</secondary></indexterm>
+<indexterm significance="preferred"><primary>Expose</primary></indexterm>
+The X server can report
+<symbol>Expose</symbol>
+events to clients wanting information about when the contents of window regions
+have been lost.
+The circumstances in which the X server generates
+<symbol>Expose</symbol>
+events are not as definite as those for other events.
+However, the X server never generates
+<symbol>Expose</symbol>
+events on windows whose class you specified as
+<symbol>InputOnly</symbol>.
+The X server can generate
+<symbol>Expose</symbol>
+events when no valid contents are available for regions of a window
+and either the regions are visible,
+the regions are viewable and the server is (perhaps newly) maintaining
+backing store on the window,
+or the window is not viewable but the server is (perhaps newly) honoring the
+window's backing-store attribute of
+<symbol>Always</symbol>
+or
+<symbol>WhenMapped</symbol>.
+The regions decompose into an (arbitrary) set of rectangles,
+and an
+<symbol>Expose</symbol>
+event is generated for each rectangle.
+For any given window,
+the X server guarantees to report contiguously
+all of the regions exposed by some action that causes
+<symbol>Expose</symbol>
+events, such as raising a window.
+</para>
+<para>
+<!-- .LP -->
+To receive
+<symbol>Expose</symbol>
+events, set the
+<symbol>ExposureMask</symbol>
+bit in the event-mask attribute of the window.
+</para>
+<para>
+<!-- .LP -->
+The structure for this event type contains:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XExposeEvent</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+ int type; /* Expose */
+ unsigned long serial; /* # of last request processed by server */
+ Bool send_event; /* true if this came from a SendEvent request */
+ Display *display; /* Display the event was read from */
+ Window window;
+ int x, y;
+ int width, height;
+ int count; /* if nonzero, at least this many more */
+} XExposeEvent;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The window member is set to the exposed (damaged) window.
+The x and y members are set to the coordinates relative to the window's origin
+and indicate the upper-left corner of the rectangle.
+The width and height members are set to the size (extent) of the rectangle.
+The count member is set to the number of
+<symbol>Expose</symbol>
+events that are to follow.
+If count is zero, no more
+<symbol>Expose</symbol>
+events follow for this window.
+However, if count is nonzero, at least that number of
+<symbol>Expose</symbol>
+events (and possibly more) follow for this window.
+Simple applications that do not want to optimize redisplay by distinguishing
+between subareas of its window can just ignore all
+<symbol>Expose</symbol>
+events with nonzero counts and perform full redisplays
+on events with zero counts.
+</para>
+</sect2>
+<sect2 id="GraphicsExpose_and_NoExpose_Events">
+<title>GraphicsExpose and NoExpose Events</title>
+<!-- .XS -->
+<!-- (SN GraphicsExpose and NoExpose Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Events</primary><secondary>GraphicsExpose</secondary></indexterm>
+<indexterm><primary>Events</primary><secondary>NoExpose</secondary></indexterm>
+<indexterm significance="preferred"><primary>GraphicsExpose</primary></indexterm>
+The X server can report
+<symbol>GraphicsExpose</symbol>
+events to clients wanting information about when a destination region could not
+be computed during certain graphics requests:
+<xref linkend='XCopyArea' xrefstyle='select: title'/>
+or
+<xref linkend='XCopyPlane' xrefstyle='select: title'/>.
+The X server generates this event whenever a destination region could not be
+computed because of an obscured or out-of-bounds source region.
+In addition, the X server guarantees to report contiguously all of the regions exposed by
+some graphics request
+(for example, copying an area of a drawable to a destination
+drawable).
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>NoExpose</primary></indexterm>
+The X server generates a
+<symbol>NoExpose</symbol>
+event whenever a graphics request that might
+produce a
+<symbol>GraphicsExpose</symbol>
+event does not produce any.
+In other words, the client is really asking for a
+<symbol>GraphicsExpose</symbol>
+event but instead receives a
+<symbol>NoExpose</symbol>
+event.
+</para>
+<para>
+<!-- .LP -->
+To receive
+<symbol>GraphicsExpose</symbol>
+or
+<symbol>NoExpose</symbol>
+events, you must first set the graphics-exposure
+attribute of the graphics context to
+<symbol>True</symbol>.
+You also can set the graphics-expose attribute when creating a graphics
+context using
+<xref linkend='XCreateGC' xrefstyle='select: title'/>
+or by calling
+<xref linkend='XSetGraphicsExposures' xrefstyle='select: title'/>.
+</para>
+<para>
+<!-- .LP -->
+The structures for these event types contain:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XGraphicsExposeEvent</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+ int type; /* GraphicsExpose */
+ unsigned long serial; /* # of last request processed by server */
+ Bool send_event; /* true if this came from a SendEvent request */
+ Display *display; /* Display the event was read from */
+ Drawable drawable;
+ int x, y;
+ int width, height;
+ int count; /* if nonzero, at least this many more */
+ int major_code; /* core is CopyArea or CopyPlane */
+ int minor_code; /* not defined in the core */
+} XGraphicsExposeEvent;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XNoExposeEvent</primary></indexterm>
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+ int type; /* NoExpose */
+ unsigned long serial; /* # of last request processed by server */
+ Bool send_event; /* true if this came from a SendEvent request */
+ Display *display; /* Display the event was read from */
+ Drawable drawable;
+ int major_code; /* core is CopyArea or CopyPlane */
+ int minor_code; /* not defined in the core */
+} XNoExposeEvent;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+Both structures have these common members: drawable, major_code, and minor_code.
+The drawable member is set to the drawable of the destination region on
+which the graphics request was to be performed.
+The major_code member is set to the graphics request initiated by the client
+and can be either
+<symbol>X_CopyArea</symbol>
+or
+<symbol>X_CopyPlane</symbol>.
+If it is
+<symbol>X_CopyArea</symbol>,
+a call to
+<xref linkend='XCopyArea' xrefstyle='select: title'/>
+initiated the request.
+If it is
+<symbol>X_CopyPlane</symbol>,
+a call to
+<xref linkend='XCopyPlane' xrefstyle='select: title'/>
+initiated the request.
+These constants are defined in
+<filename class="headerfile"><X11/Xproto.h></filename>.
+<indexterm type="file"><primary><filename class="headerfile">X11/Xproto.h</filename></primary></indexterm>
+<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/Xproto.h></filename></secondary></indexterm>
+<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/Xproto.h></filename></secondary></indexterm>
+The minor_code member,
+like the major_code member,
+indicates which graphics request was initiated by
+the client.
+However, the minor_code member is not defined by the core
+X protocol and will be zero in these cases,
+although it may be used by an extension.
+</para>
+<para>
+<!-- .LP -->
+The
+<structname>XGraphicsExposeEvent</structname>
+structure has these additional members: x, y, width, height, and count.
+The x and y members are set to the coordinates relative to the drawable's origin
+and indicate the upper-left corner of the rectangle.
+The width and height members are set to the size (extent) of the rectangle.
+The count member is set to the number of
+<symbol>GraphicsExpose</symbol>
+events to follow.
+If count is zero, no more
+<symbol>GraphicsExpose</symbol>
+events follow for this window.
+However, if count is nonzero, at least that number of
+<symbol>GraphicsExpose</symbol>
+events (and possibly more) are to follow for this window.
+</para>
+</sect2>
+</sect1>
+<sect1 id='Window_State_Change_Events'>
+<title>Window State Change Events</title>
+<!-- .XS -->
+<!-- (SN Window State Change Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The following sections discuss:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+<symbol>CirculateNotify</symbol>
+events
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<symbol>ConfigureNotify</symbol>
+events
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<symbol>CreateNotify</symbol>
+events
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<symbol>DestroyNotify</symbol>
+events
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<symbol>GravityNotify</symbol>
+events
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<symbol>MapNotify</symbol>
+events
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<symbol>MappingNotify</symbol>
+events
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<symbol>ReparentNotify</symbol>
+events
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<symbol>UnmapNotify</symbol>
+events
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<symbol>VisibilityNotify</symbol>
+events
+<!-- .\" .SH 3 -->
+ </para>
+ </listitem>
+</itemizedlist>
+<sect2 id="CirculateNotify_Events">
+<title>CirculateNotify Events</title>
+<!-- .XS -->
+<!-- (SN CirculateNotify Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Events</primary><secondary>CirculateNotify</secondary></indexterm>
+<indexterm significance="preferred"><primary>CirculateNotify</primary></indexterm>
+The X server can report
+<symbol>CirculateNotify</symbol>
+events to clients wanting information about when a window changes
+its position in the stack.
+The X server generates this event type whenever a window is actually restacked
+as a result of a client application calling
+<xref linkend='XCirculateSubwindows' xrefstyle='select: title'/>,
+<xref linkend='XCirculateSubwindowsUp' xrefstyle='select: title'/>,
+or
+<xref linkend='XCirculateSubwindowsDown' xrefstyle='select: title'/>.
+</para>
+<para>
+<!-- .LP -->
+To receive
+<symbol>CirculateNotify</symbol>
+events, set the
+<symbol>StructureNotifyMask</symbol>
+bit in the event-mask attribute of the window
+or the
+<symbol>SubstructureNotifyMask</symbol>
+bit in the event-mask attribute of the parent window
+(in which case, circulating any child generates an event).
+</para>
+<para>
+<!-- .LP -->
+The structure for this event type contains:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XCirculateEvent</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+ int type; /* CirculateNotify */
+ unsigned long serial; /* # of last request processed by server */
+ Bool send_event; /* true if this came from a SendEvent request */
+ Display *display; /* Display the event was read from */
+ Window event;
+ Window window;
+ int place; /* PlaceOnTop, PlaceOnBottom */
+} XCirculateEvent;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The event member is set either to the restacked window or to its parent,
+depending on whether
+<systemitem class="event">StructureNotify</systemitem>
+or
+<systemitem class="event">SubstructureNotify</systemitem>
+was selected.
+The window member is set to the window that was restacked.
+The place member is set to the window's position after the restack occurs and
+is either
+<symbol>PlaceOnTop</symbol>
+or
+<symbol>PlaceOnBottom</symbol>.
+If it is
+<symbol>PlaceOnTop</symbol>,
+the window is now on top of all siblings.
+If it is
+<symbol>PlaceOnBottom</symbol>,
+the window is now below all siblings.
+</para>
+</sect2>
+<sect2 id="ConfigureNotify_Events">
+<title>ConfigureNotify Events</title>
+<!-- .XS -->
+<!-- (SN ConfigureNotify Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Events</primary><secondary>ConfigureNotify</secondary></indexterm>
+<indexterm significance="preferred"><primary>ConfigureNotify</primary></indexterm>
+The X server can report
+<symbol>ConfigureNotify</symbol>
+events to clients wanting information about actual changes to a window's
+state, such as size, position, border, and stacking order.
+The X server generates this event type whenever one of the following configure
+window requests made by a client application actually completes:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+A window's size, position, border, and/or stacking order is reconfigured
+by calling
+<xref linkend='XConfigureWindow' xrefstyle='select: title'/>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The window's position in the stacking order is changed by calling
+<xref linkend='XLowerWindow' xrefstyle='select: title'/>,
+<xref linkend='XRaiseWindow' xrefstyle='select: title'/>,
+or
+<xref linkend='XRestackWindows' xrefstyle='select: title'/>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+A window is moved by calling
+<xref linkend='XMoveWindow' xrefstyle='select: title'/>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+A window's size is changed by calling
+<xref linkend='XResizeWindow' xrefstyle='select: title'/>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+A window's size and location is changed by calling
+<xref linkend='XMoveResizeWindow' xrefstyle='select: title'/>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+A window is mapped and its position in the stacking order is changed
+by calling
+<xref linkend='XMapRaised' xrefstyle='select: title'/>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+A window's border width is changed by calling
+<xref linkend='XSetWindowBorderWidth' xrefstyle='select: title'/>.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+To receive
+<symbol>ConfigureNotify</symbol>
+events, set the
+<symbol>StructureNotifyMask</symbol>
+bit in the event-mask attribute of the window or the
+<symbol>SubstructureNotifyMask</symbol>
+bit in the event-mask attribute of the parent window
+(in which case, configuring any child generates an event).
+</para>
+<para>
+<!-- .LP -->
+The structure for this event type contains:
+</para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XConfigureEvent</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+ int type; /* ConfigureNotify */
+ unsigned long serial; /* # of last request processed by server */
+ Bool send_event; /* true if this came from a SendEvent request */
+ Display *display; /* Display the event was read from */
+ Window event;
+ Window window;
+ int x, y;
+ int width, height;
+ int border_width;
+ Window above;
+ Bool override_redirect;
+} XConfigureEvent;
+</literallayout>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The event member is set either to the reconfigured window or to its parent,
+depending on whether
+<systemitem class="event">StructureNotify</systemitem>
+or
+<systemitem class="event">SubstructureNotify</systemitem>
+was selected.
+The window member is set to the window whose size, position,
+border, and/or stacking
+order was changed.
+</para>
+<para>
+<!-- .LP -->
+The x and y members are set to the coordinates relative to the parent window's
+origin and indicate the position of the upper-left outside corner of the window.
+The width and height members are set to the inside size of the window,
+not including
+the border.
+The border_width member is set to the width of the window's border, in pixels.
+</para>
+<para>
+<!-- .LP -->
+The above member is set to the sibling window and is used
+for stacking operations.
+If the X server sets this member to
+<symbol>None</symbol>,
+the window whose state was changed is on the bottom of the stack
+with respect to sibling windows.
+However, if this member is set to a sibling window,
+the window whose state was changed is placed on top of this sibling window.
+</para>
+<para>
+<!-- .LP -->
+The override_redirect member is set to the override-redirect attribute of the
+window.
+Window manager clients normally should ignore this window if the
+override_redirect member
+is
+<symbol>True</symbol>.
+</para>
+</sect2>
+<sect2 id="CreateNotify_Events">
+<title>CreateNotify Events</title>
+<!-- .XS -->
+<!-- (SN CreateNotify Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Events</primary><secondary>CreateNotify</secondary></indexterm>
+<indexterm significance="preferred"><primary>CreateNotify</primary></indexterm>
+The X server can report
+<symbol>CreateNotify</symbol>
+events to clients wanting information about creation of windows.
+The X server generates this event whenever a client
+application creates a window by calling
+<xref linkend='XCreateWindow' xrefstyle='select: title'/>
+or
+<xref linkend='XCreateSimpleWindow' xrefstyle='select: title'/>.
+</para>
+<para>
+<!-- .LP -->
+To receive
+<symbol>CreateNotify</symbol>
+events, set the
+<symbol>SubstructureNotifyMask</symbol>
+bit in the event-mask attribute of the window.
+Creating any children then generates an event.
+</para>
+<para>
+<!-- .LP -->
+The structure for the event type contains:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XCreateWindowEvent</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+ int type; /* CreateNotify */
+ unsigned long serial; /* # of last request processed by server */
+ Bool send_event; /* true if this came from a SendEvent request */
+ Display *display; /* Display the event was read from */
+ Window parent; /* parent of the window */
+ Window window; /* window id of window created */
+ int x, y; /* window location */
+ int width, height; /* size of window */
+ int border_width; /* border width */
+ Bool override_redirect; /* creation should be overridden */
+} XCreateWindowEvent;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The parent member is set to the created window's parent.
+The window member specifies the created window.
+The x and y members are set to the created window's coordinates relative
+to the parent window's origin and indicate the position of the upper-left
+outside corner of the created window.
+The width and height members are set to the inside size of the created window
+(not including the border) and are always nonzero.
+The border_width member is set to the width of the created window's border, in pixels.
+The override_redirect member is set to the override-redirect attribute of the
+window.
+Window manager clients normally should ignore this window
+if the override_redirect member is
+<symbol>True</symbol>.
+</para>
+</sect2>
+<sect2 id="DestroyNotify_Events">
+<title>DestroyNotify Events</title>
+<!-- .XS -->
+<!-- (SN DestroyNotify Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Events</primary><secondary>DestroyNotify</secondary></indexterm>
+<indexterm significance="preferred"><primary>DestroyNotify</primary></indexterm>
+The X server can report
+<symbol>DestroyNotify</symbol>
+events to clients wanting information about which windows are destroyed.
+The X server generates this event whenever a client application destroys a
+window by calling
+<xref linkend='XDestroyWindow' xrefstyle='select: title'/>
+or
+<xref linkend='XDestroySubwindows' xrefstyle='select: title'/>.
+</para>
+<para>
+<!-- .LP -->
+The ordering of the
+<symbol>DestroyNotify</symbol>
+events is such that for any given window,
+<symbol>DestroyNotify</symbol>
+is generated on all inferiors of the window
+before being generated on the window itself.
+The X protocol does not constrain the ordering among
+siblings and across subhierarchies.
+</para>
+<para>
+<!-- .LP -->
+To receive
+<symbol>DestroyNotify</symbol>
+events, set the
+<symbol>StructureNotifyMask</symbol>
+bit in the event-mask attribute of the window or the
+<symbol>SubstructureNotifyMask</symbol>
+bit in the event-mask attribute of the parent window
+(in which case, destroying any child generates an event).
+</para>
+<para>
+<!-- .LP -->
+The structure for this event type contains:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XDestroyWindowEvent</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+ int type; /* DestroyNotify */
+ unsigned long serial; /* # of last request processed by server */
+ Bool send_event; /* true if this came from a SendEvent request */
+ Display *display; /* Display the event was read from */
+ Window event;
+ Window window;
+} XDestroyWindowEvent;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The event member is set either to the destroyed window or to its parent,
+depending on whether
+<systemitem class="event">StructureNotify</systemitem>
+or
+<systemitem class="event">SubstructureNotify</systemitem>
+was selected.
+The window member is set to the window that is destroyed.
+</para>
+</sect2>
+<sect2 id="GravityNotify_Events">
+<title>GravityNotify Events</title>
+<!-- .XS -->
+<!-- (SN GravityNotify Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Events</primary><secondary>GravityNotify</secondary></indexterm>
+<indexterm significance="preferred"><primary>GravityNotify</primary></indexterm>
+The X server can report
+<symbol>GravityNotify</symbol>
+events to clients wanting information about when a window is moved because of a
+change in the size of its parent.
+The X server generates this event whenever a client
+application actually moves a child window as a result of resizing its parent by calling
+<xref linkend='XConfigureWindow' xrefstyle='select: title'/>,
+<xref linkend='XMoveResizeWindow' xrefstyle='select: title'/>,
+or
+<xref linkend='XResizeWindow' xrefstyle='select: title'/>.
+</para>
+<para>
+<!-- .LP -->
+To receive
+<symbol>GravityNotify</symbol>
+events, set the
+<symbol>StructureNotifyMask</symbol>
+bit in the event-mask attribute of the window or the
+<symbol>SubstructureNotifyMask</symbol>
+bit in the event-mask attribute of the parent window
+(in which case, any child that is moved because its parent has been resized
+generates an event).
+</para>
+<para>
+<!-- .LP -->
+The structure for this event type contains:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XGravityEvent</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+ int type; /* GravityNotify */
+ unsigned long serial; /* # of last request processed by server */
+ Bool send_event; /* true if this came from a SendEvent request */
+ Display *display; /* Display the event was read from */
+ Window event;
+ Window window;
+ int x, y;
+} XGravityEvent;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The event member is set either to the window that was moved or to its parent,
+depending on whether
+<systemitem class="event">StructureNotify</systemitem>
+or
+<systemitem class="event">SubstructureNotify</systemitem>
+was selected.
+The window member is set to the child window that was moved.
+The x and y members are set to the coordinates relative to the
+new parent window's origin
+and indicate the position of the upper-left outside corner of the
+window.
+</para>
+</sect2>
+<sect2 id="MapNotify_Events">
+<title>MapNotify Events</title>
+<!-- .XS -->
+<!-- (SN MapNotify Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Events</primary><secondary>MapNotify</secondary></indexterm>
+<indexterm significance="preferred"><primary>MapNotify</primary></indexterm>
+The X server can report
+<symbol>MapNotify</symbol>
+events to clients wanting information about which windows are mapped.
+The X server generates this event type whenever a client application changes the
+window's state from unmapped to mapped by calling
+<xref linkend='XMapWindow' xrefstyle='select: title'/>,
+<xref linkend='XMapRaised' xrefstyle='select: title'/>,
+<xref linkend='XMapSubwindows' xrefstyle='select: title'/>,
+<xref linkend='XReparentWindow' xrefstyle='select: title'/>,
+or as a result of save-set processing.
+</para>
+<para>
+<!-- .LP -->
+To receive
+<symbol>MapNotify</symbol>
+events, set the
+<symbol>StructureNotifyMask</symbol>
+bit in the event-mask attribute of the window or the
+<symbol>SubstructureNotifyMask</symbol>
+bit in the event-mask attribute of the parent window
+(in which case, mapping any child generates an event).
+</para>
+<para>
+<!-- .LP -->
+The structure for this event type contains:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XMapEvent</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+ int type; /* MapNotify */
+ unsigned long serial; /* # of last request processed by server */
+ Bool send_event; /* true if this came from a SendEvent request */
+ Display *display; /* Display the event was read from */
+ Window event;
+ Window window;
+ Bool override_redirect; /* boolean, is override set... */
+} XMapEvent;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The event member is set either to the window that was mapped or to its parent,
+depending on whether
+<systemitem class="event">StructureNotify</systemitem>
+or
+<systemitem class="event">SubstructureNotify</systemitem>
+was selected.
+The window member is set to the window that was mapped.
+The override_redirect member is set to the override-redirect attribute
+of the window.
+Window manager clients normally should ignore this window
+if the override-redirect attribute is
+<symbol>True</symbol>,
+because these events usually are generated from pop-ups,
+which override structure control.
+</para>
+</sect2>
+<sect2 id="MappingNotify_Events">
+<title>MappingNotify Events</title>
+<!-- .XS -->
+<!-- (SN MappingNotify Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Events</primary><secondary>MappingNotify</secondary></indexterm>
+<indexterm significance="preferred"><primary>MappingNotify</primary></indexterm>
+The X server reports
+<symbol>MappingNotify</symbol>
+events to all clients.
+There is no mechanism to express disinterest in this event.
+The X server generates this event type whenever a client application
+successfully calls:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+<xref linkend='XSetModifierMapping' xrefstyle='select: title'/>
+to indicate which KeyCodes are to be used as modifiers
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XChangeKeyboardMapping' xrefstyle='select: title'/>
+to change the keyboard mapping
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<xref linkend='XSetPointerMapping' xrefstyle='select: title'/>
+to set the pointer mapping
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+The structure for this event type contains:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XMappingEvent</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+ int type; /* MappingNotify */
+ unsigned long serial; /* # of last request processed by server */
+ Bool send_event; /* true if this came from a SendEvent request */
+ Display *display; /* Display the event was read from */
+ Window window; /* unused */
+ int request; /* one of MappingModifier, MappingKeyboard,
+ MappingPointer */
+ int first_keycode; /* first keycode */
+ int count; /* defines range of change w. first_keycode*/
+} XMappingEvent;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The request member is set to indicate the kind of mapping change that occurred
+and can be
+<symbol>MappingModifier</symbol>,
+<symbol>MappingKeyboard</symbol>,
+or
+<symbol>MappingPointer</symbol>.
+If it is
+<symbol>MappingModifier</symbol>,
+the modifier mapping was changed.
+If it is
+<symbol>MappingKeyboard</symbol>,
+the keyboard mapping was changed.
+If it is
+<symbol>MappingPointer</symbol>,
+the pointer button mapping was changed.
+The first_keycode and count members are set only
+if the request member was set to
+<symbol>MappingKeyboard</symbol>.
+The number in first_keycode represents the first number in the range
+of the altered mapping,
+and count represents the number of keycodes altered.
+</para>
+<para>
+<!-- .LP -->
+To update the client application's knowledge of the keyboard,
+you should call
+<xref linkend='XRefreshKeyboardMapping' xrefstyle='select: title'/>.
+</para>
+</sect2>
+<sect2 id="ReparentNotify_Events">
+<title>ReparentNotify Events</title>
+<!-- .XS -->
+<!-- (SN ReparentNotify Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Events</primary><secondary>ReparentNotify</secondary></indexterm>
+<indexterm significance="preferred"><primary>ReparentNotify</primary></indexterm>
+The X server can report
+<symbol>ReparentNotify</symbol>
+events to clients wanting information about changing a window's parent.
+The X server generates this event whenever a client
+application calls
+<xref linkend='XReparentWindow' xrefstyle='select: title'/>
+and the window is actually reparented.
+</para>
+<para>
+<!-- .LP -->
+To receive
+<symbol>ReparentNotify</symbol>
+events, set the
+<symbol>StructureNotifyMask</symbol>
+bit in the event-mask attribute of the window or the
+<symbol>SubstructureNotifyMask</symbol>
+bit in the event-mask attribute of either the old or the new parent window
+(in which case, reparenting any child generates an event).
+</para>
+<para>
+<!-- .LP -->
+The structure for this event type contains:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XReparentEvent</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+ int type; /* ReparentNotify */
+ unsigned long serial; /* # of last request processed by server */
+ Bool send_event; /* true if this came from a SendEvent request */
+ Display *display; /* Display the event was read from */
+ Window event;
+ Window window;
+ Window parent;
+ int x, y;
+ Bool override_redirect;
+} XReparentEvent;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The event member is set either to the reparented window
+or to the old or the new parent, depending on whether
+<systemitem class="event">StructureNotify</systemitem>
+or
+<systemitem class="event">SubstructureNotify</systemitem>
+was selected.
+The window member is set to the window that was reparented.
+The parent member is set to the new parent window.
+The x and y members are set to the reparented window's coordinates relative
+to the new parent window's
+origin and define the upper-left outer corner of the reparented window.
+The override_redirect member is set to the override-redirect attribute of the
+window specified by the window member.
+Window manager clients normally should ignore this window
+if the override_redirect member is
+<symbol>True</symbol>.
+</para>
+</sect2>
+<sect2 id="UnmapNotify_Events">
+<title>UnmapNotify Events</title>
+<!-- .XS -->
+<!-- (SN UnmapNotify Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Events</primary><secondary>UnmapNotify</secondary></indexterm>
+<indexterm significance="preferred"><primary>UnmapNotify</primary></indexterm>
+The X server can report
+<symbol>UnmapNotify</symbol>
+events to clients wanting information about which windows are unmapped.
+The X server generates this event type whenever a client application changes the
+window's state from mapped to unmapped.
+</para>
+<para>
+<!-- .LP -->
+To receive
+<symbol>UnmapNotify</symbol>
+events, set the
+<symbol>StructureNotifyMask</symbol>
+bit in the event-mask attribute of the window or the
+<symbol>SubstructureNotifyMask</symbol>
+bit in the event-mask attribute of the parent window
+(in which case, unmapping any child window generates an event).
+</para>
+<para>
+<!-- .LP -->
+The structure for this event type contains:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XUnmapEvent</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+ int type; /* UnmapNotify */
+ unsigned long serial; /* # of last request processed by server */
+ Bool send_event; /* true if this came from a SendEvent request */
+ Display *display; /* Display the event was read from */
+ Window event;
+ Window window;
+ Bool from_configure;
+} XUnmapEvent;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The event member is set either to the unmapped window or to its parent,
+depending on whether
+<systemitem class="event">StructureNotify</systemitem>
+or
+<systemitem class="event">SubstructureNotify</systemitem>
+was selected.
+This is the window used by the X server to report the event.
+The window member is set to the window that was unmapped.
+The from_configure member is set to
+<symbol>True</symbol>
+if the event was generated as a result of a resizing of the window's parent when
+the window itself had a win_gravity of
+<symbol>UnmapGravity</symbol>.
+</para>
+</sect2>
+<sect2 id="VisibilityNotify_Events">
+<title>VisibilityNotify Events</title>
+<!-- .XS -->
+<!-- (SN VisibilityNotify Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Events</primary><secondary>VisibilityNotify</secondary></indexterm>
+<indexterm significance="preferred"><primary>VisibilityNotify</primary></indexterm>
+The X server can report
+<symbol>VisibilityNotify</symbol>
+events to clients wanting any change in the visibility of the specified window.
+A region of a window is visible if someone looking at the screen can
+actually see it.
+The X server generates this event whenever the visibility changes state.
+However, this event is never generated for windows whose class is
+<symbol>InputOnly</symbol>.
+</para>
+<para>
+<!-- .LP -->
+All
+<symbol>VisibilityNotify</symbol>
+events caused by a hierarchy change are generated
+after any hierarchy event
+(<symbol>UnmapNotify</symbol>,
+<symbol>MapNotify</symbol>,
+<symbol>ConfigureNotify</symbol>,
+<symbol>GravityNotify</symbol>,
+<symbol>CirculateNotify</symbol>)
+caused by that change. Any
+<symbol>VisibilityNotify</symbol>
+event on a given window is generated before any
+<symbol>Expose</symbol>
+events on that window, but it is not required that all
+<symbol>VisibilityNotify</symbol>
+events on all windows be generated before all
+<symbol>Expose</symbol>
+events on all windows.
+The X protocol does not constrain the ordering of
+<symbol>VisibilityNotify</symbol>
+events with
+respect to
+<symbol>FocusOut</symbol>,
+<symbol>EnterNotify</symbol>,
+and
+<symbol>LeaveNotify</symbol>
+events.
+</para>
+<para>
+<!-- .LP -->
+To receive
+<symbol>VisibilityNotify</symbol>
+events, set the
+<symbol>VisibilityChangeMask</symbol>
+bit in the event-mask attribute of the window.
+</para>
+<para>
+<!-- .LP -->
+The structure for this event type contains:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XVisibilityEvent</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+ int type; /* VisibilityNotify */
+ unsigned long serial; /* # of last request processed by server */
+ Bool send_event; /* true if this came from a SendEvent request */
+ Display *display; /* Display the event was read from */
+ Window window;
+ int state;
+} XVisibilityEvent;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The window member is set to the window whose visibility state changes.
+The state member is set to the state of the window's visibility and can be
+<symbol>VisibilityUnobscured</symbol>,
+<symbol>VisibilityPartiallyObscured</symbol>,
+or
+<symbol>VisibilityFullyObscured</symbol>.
+The X server ignores all of a window's subwindows
+when determining the visibility state of the window and processes
+<symbol>VisibilityNotify</symbol>
+events according to the following:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+When the window changes state from partially obscured, fully obscured,
+or not viewable to viewable and completely unobscured,
+the X server generates the event with the state member of the
+<structname>XVisibilityEvent</structname>
+structure set to
+<symbol>VisibilityUnobscured</symbol>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+When the window changes state from viewable and completely unobscured or
+not viewable to viewable and partially obscured,
+the X server generates the event with the state member of the
+<structname>XVisibilityEvent</structname>
+structure set to
+<symbol>VisibilityPartiallyObscured</symbol>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+When the window changes state from viewable and completely unobscured,
+viewable and partially obscured, or not viewable to viewable and
+fully obscured,
+the X server generates the event with the state member of the
+<structname>XVisibilityEvent</structname>
+structure set to
+<symbol>VisibilityFullyObscured</symbol>.
+ </para>
+ </listitem>
+</itemizedlist>
+</sect2>
+</sect1>
+<sect1 id="Structure_Control_Events">
+<title>Structure Control Events</title>
+<!-- .XS -->
+<!-- (SN Structure Control Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+This section discusses:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+<symbol>CirculateRequest</symbol>
+events
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<symbol>ConfigureRequest</symbol>
+events
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<symbol>MapRequest</symbol>
+events
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<symbol>ResizeRequest</symbol>
+events
+ </para>
+ </listitem>
+</itemizedlist>
+<sect2 id="CirculateRequest_Events">
+<title>CirculateRequest Events</title>
+<!-- .XS -->
+<!-- (SN CirculateRequest Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Events</primary><secondary>CirculateRequest</secondary></indexterm>
+<indexterm significance="preferred"><primary>CirculateRequest</primary></indexterm>
+The X server can report
+<symbol>CirculateRequest</symbol>
+events to clients wanting information about
+when another client initiates a circulate window request
+on a specified window.
+The X server generates this event type whenever a client initiates a circulate
+window request on a window and a subwindow actually needs to be restacked.
+The client initiates a circulate window request on the window by calling
+<xref linkend='XCirculateSubwindows' xrefstyle='select: title'/>,
+<xref linkend='XCirculateSubwindowsUp' xrefstyle='select: title'/>,
+or
+<xref linkend='XCirculateSubwindowsDown' xrefstyle='select: title'/>.
+</para>
+<para>
+<!-- .LP -->
+To receive
+<symbol>CirculateRequest</symbol>
+events, set the
+<symbol>SubstructureRedirectMask</symbol>
+in the event-mask attribute of the window.
+Then, in the future,
+the circulate window request for the specified window is not executed,
+and thus, any subwindow's position in the stack is not changed.
+For example, suppose a client application calls
+<xref linkend='XCirculateSubwindowsUp' xrefstyle='select: title'/>
+to raise a subwindow to the top of the stack.
+If you had selected
+<symbol>SubstructureRedirectMask</symbol>
+on the window, the X server reports to you a
+<symbol>CirculateRequest</symbol>
+event and does not raise the subwindow to the top of the stack.
+</para>
+<para>
+<!-- .LP -->
+The structure for this event type contains:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XCirculateRequestEvent</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+ int type; /* CirculateRequest */
+ unsigned long serial; /* # of last request processed by server */
+ Bool send_event; /* true if this came from a SendEvent request */
+ Display *display; /* Display the event was read from */
+ Window parent;
+ Window window;
+ int place; /* PlaceOnTop, PlaceOnBottom */
+} XCirculateRequestEvent;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The parent member is set to the parent window.
+The window member is set to the subwindow to be restacked.
+The place member is set to what the new position in the stacking order should be
+and is either
+<symbol>PlaceOnTop</symbol>
+or
+<symbol>PlaceOnBottom</symbol>.
+If it is
+<symbol>PlaceOnTop</symbol>,
+the subwindow should be on top of all siblings.
+If it is
+<symbol>PlaceOnBottom</symbol>,
+the subwindow should be below all siblings.
+</para>
+</sect2>
+<sect2 id="ConfigureRequest_Events">
+<title>ConfigureRequest Events</title>
+<!-- .XS -->
+<!-- (SN ConfigureRequest Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Events</primary><secondary>ConfigureRequest</secondary></indexterm>
+<indexterm significance="preferred"><primary>ConfigureRequest</primary></indexterm>
+The X server can report
+<symbol>ConfigureRequest</symbol>
+events to clients wanting information about when a different client initiates
+a configure window request on any child of a specified window.
+The configure window request attempts to
+reconfigure a window's size, position, border, and stacking order.
+The X server generates this event whenever a different client initiates
+a configure window request on a window by calling
+<xref linkend='XConfigureWindow' xrefstyle='select: title'/>,
+<xref linkend='XLowerWindow' xrefstyle='select: title'/>,
+<xref linkend='XRaiseWindow' xrefstyle='select: title'/>,
+<xref linkend='XMapRaised' xrefstyle='select: title'/>,
+<xref linkend='XMoveResizeWindow' xrefstyle='select: title'/>,
+<xref linkend='XMoveWindow' xrefstyle='select: title'/>,
+<xref linkend='XResizeWindow' xrefstyle='select: title'/>,
+<xref linkend='XRestackWindows' xrefstyle='select: title'/>,
+or
+<xref linkend='XSetWindowBorderWidth' xrefstyle='select: title'/>.
+</para>
+<para>
+<!-- .LP -->
+To receive
+<symbol>ConfigureRequest</symbol>
+events, set the
+<symbol>SubstructureRedirectMask</symbol>
+bit in the event-mask attribute of the window.
+<symbol>ConfigureRequest</symbol>
+events are generated when a
+<systemitem>ConfigureWindow</systemitem>
+protocol request is issued on a child window by another client.
+For example, suppose a client application calls
+<xref linkend='XLowerWindow' xrefstyle='select: title'/>
+to lower a window.
+If you had selected
+<symbol>SubstructureRedirectMask</symbol>
+on the parent window and if the override-redirect attribute
+of the window is set to
+<symbol>False</symbol>,
+the X server reports a
+<symbol>ConfigureRequest</symbol>
+event to you and does not lower the specified window.
+</para>
+<para>
+<!-- .LP -->
+The structure for this event type contains:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XConfigureRequestEvent</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+ int type; /* ConfigureRequest */
+ unsigned long serial; /* # of last request processed by server */
+ Bool send_event; /* true if this came from a SendEvent request */
+ Display *display; /* Display the event was read from */
+ Window parent;
+ Window window;
+ int x, y;
+ int width, height;
+ int border_width;
+ Window above;
+ int detail; /* Above, Below, TopIf, BottomIf, Opposite */
+ unsigned long value_mask;
+} XConfigureRequestEvent;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The parent member is set to the parent window.
+The window member is set to the window whose size, position, border width,
+and/or stacking order is to be reconfigured.
+The value_mask member indicates which components were specified in the
+<systemitem>ConfigureWindow</systemitem>
+protocol request.
+The corresponding values are reported as given in the request.
+The remaining values are filled in from the current geometry of the window,
+except in the case of above (sibling) and detail (stack-mode),
+which are reported as
+<symbol>None</symbol>
+and
+<symbol>Above</symbol>,
+respectively, if they are not given in the request.
+</para>
+</sect2>
+<sect2 id="MapRequest_Events">
+<title>MapRequest Events</title>
+<!-- .XS -->
+<!-- (SN MapRequest Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Events</primary><secondary>MapRequest</secondary></indexterm>
+<indexterm significance="preferred"><primary>MapRequest</primary></indexterm>
+The X server can report
+<symbol>MapRequest</symbol>
+events to clients wanting information about a different client's desire
+to map windows.
+A window is considered mapped when a map window request completes.
+The X server generates this event whenever a different client initiates
+a map window request on an unmapped window whose override_redirect member
+is set to
+<symbol>False</symbol>.
+Clients initiate map window requests by calling
+<xref linkend='XMapWindow' xrefstyle='select: title'/>,
+<xref linkend='XMapRaised' xrefstyle='select: title'/>,
+or
+<xref linkend='XMapSubwindows' xrefstyle='select: title'/>.
+</para>
+<para>
+<!-- .LP -->
+To receive
+<symbol>MapRequest</symbol>
+events, set the
+<symbol>SubstructureRedirectMask</symbol>
+bit in the event-mask attribute of the window.
+This means another client's attempts to map a child window by calling one of
+the map window request functions is intercepted, and you are sent a
+<symbol>MapRequest</symbol>
+instead.
+For example, suppose a client application calls
+<xref linkend='XMapWindow' xrefstyle='select: title'/>
+to map a window.
+If you (usually a window manager) had selected
+<symbol>SubstructureRedirectMask</symbol>
+on the parent window and if the override-redirect attribute
+of the window is set to
+<symbol>False</symbol>,
+the X server reports a
+<symbol>MapRequest</symbol>
+event to you
+and does not map the specified window.
+Thus, this event gives your window manager client the ability
+to control the placement of subwindows.
+</para>
+<para>
+<!-- .LP -->
+The structure for this event type contains:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XMapRequestEvent</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+ int type; /* MapRequest */
+ unsigned long serial; /* # of last request processed by server */
+ Bool send_event; /* true if this came from a SendEvent request */
+ Display *display; /* Display the event was read from */
+ Window parent;
+ Window window;
+} XMapRequestEvent;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The parent member is set to the parent window.
+The window member is set to the window to be mapped.
+</para>
+</sect2>
+<sect2 id="ResizeRequest_Events">
+<title>ResizeRequest Events</title>
+<!-- .XS -->
+<!-- (SN ResizeRequest Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Events</primary><secondary>ResizeRequest</secondary></indexterm>
+<indexterm significance="preferred"><primary>ResizeRequest</primary></indexterm>
+The X server can report
+<symbol>ResizeRequest</symbol>
+events to clients wanting information about another client's attempts to change the
+size of a window.
+The X server generates this event whenever some other client attempts to change
+the size of the specified window by calling
+<xref linkend='XConfigureWindow' xrefstyle='select: title'/>,
+<xref linkend='XResizeWindow' xrefstyle='select: title'/>,
+or
+<xref linkend='XMoveResizeWindow' xrefstyle='select: title'/>.
+</para>
+<para>
+<!-- .LP -->
+To receive
+<symbol>ResizeRequest</symbol>
+events, set the
+<symbol>ResizeRedirect</symbol>
+bit in the event-mask attribute of the window.
+Any attempts to change the size by other clients are then redirected.
+</para>
+<para>
+<!-- .LP -->
+The structure for this event type contains:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XResizeRequestEvent</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+ int type; /* ResizeRequest */
+ unsigned long serial; /* # of last request processed by server */
+ Bool send_event; /* true if this came from a SendEvent request */
+ Display *display; /* Display the event was read from */
+ Window window;
+ int width, height;
+} XResizeRequestEvent;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The window member is set to the window whose size another
+client attempted to change.
+The width and height members are set to the inside size of the window,
+excluding the border.
+</para>
+</sect2>
+</sect1>
+<sect1 id="Colormap_State_Change_Events">
+<title>Colormap State Change Events</title>
+<!-- .XS -->
+<!-- (SN Colormap State Change Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Events</primary><secondary>ColormapNotify</secondary></indexterm>
+<indexterm significance="preferred"><primary>ColormapNotify</primary></indexterm>
+The X server can report
+<symbol>ColormapNotify</symbol>
+events to clients wanting information about when the colormap changes
+and when a colormap is installed or uninstalled.
+The X server generates this event type whenever a client application:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Changes the colormap member of the
+<structname>XSetWindowAttributes</structname>
+structure by
+calling
+<xref linkend='XChangeWindowAttributes' xrefstyle='select: title'/>,
+<xref linkend='XFreeColormap' xrefstyle='select: title'/>,
+or
+<xref linkend='XSetWindowColormap' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Installs or uninstalls the colormap by calling
+<xref linkend='XInstallColormap' xrefstyle='select: title'/>
+or
+<xref linkend='XUninstallColormap' xrefstyle='select: title'/>
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+To receive
+<symbol>ColormapNotify</symbol>
+events, set the
+<symbol>ColormapChangeMask</symbol>
+bit in the event-mask attribute of the window.
+</para>
+<para>
+<!-- .LP -->
+The structure for this event type contains:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XColormapEvent</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+ int type; /* ColormapNotify */
+ unsigned long serial; /* # of last request processed by server */
+ Bool send_event; /* true if this came from a SendEvent request */
+ Display *display; /* Display the event was read from */
+ Window window;
+ Colormap colormap; /* colormap or None */
+ Bool new;
+ int state; /* ColormapInstalled, ColormapUninstalled */
+} XColormapEvent;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The window member is set to the window whose associated
+colormap is changed, installed, or uninstalled.
+For a colormap that is changed, installed, or uninstalled,
+the colormap member is set to the colormap associated with the window.
+For a colormap that is changed by a call to
+<xref linkend='XFreeColormap' xrefstyle='select: title'/>,
+the colormap member is set to
+<symbol>None</symbol>.
+The new member is set to indicate whether the colormap
+for the specified window was changed or installed or uninstalled
+and can be
+<symbol>True</symbol>
+or
+<symbol>False</symbol>.
+If it is
+<symbol>True</symbol>,
+the colormap was changed.
+If it is
+<symbol>False</symbol>,
+the colormap was installed or uninstalled.
+The state member is always set to indicate whether the colormap is installed or
+uninstalled and can be
+<symbol>ColormapInstalled</symbol>
+or
+<symbol>ColormapUninstalled</symbol>.
+</para>
+</sect1>
+<sect1 id="Client_Communication_Events">
+<title>Client Communication Events</title>
+<!-- .XS -->
+<!-- (SN Client Communication Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+This section discusses:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+<symbol>ClientMessage</symbol>
+events
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<symbol>PropertyNotify</symbol>
+events
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<symbol>SelectionClear</symbol>
+events
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<symbol>SelectionNotify</symbol>
+events
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<symbol>SelectionRequest</symbol>
+events
+ </para>
+ </listitem>
+</itemizedlist>
+<sect2 id="ClientMessage_Events">
+<title>ClientMessage Events</title>
+<!-- .XS -->
+<!-- (SN ClientMessage Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Events</primary><secondary>ClientMessage</secondary></indexterm>
+<indexterm significance="preferred"><primary>ClientMessage</primary></indexterm>
+The X server generates
+<symbol>ClientMessage</symbol>
+events only when a client calls the function
+<xref linkend='XSendEvent' xrefstyle='select: title'/>.
+</para>
+<para>
+<!-- .LP -->
+The structure for this event type contains:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XClientMessageEvent</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 1i 3i -->
+<!-- .ta .5i 1i 3i -->
+typedef struct {
+ int type; /* ClientMessage */
+ unsigned long serial; /* # of last request processed by server */
+ Bool send_event; /* true if this came from a SendEvent request */
+ Display *display; /* Display the event was read from */
+ Window window;
+ Atom message_type;
+ int format;
+ union {
+ char b[20];
+ short s[10];
+ long l[5];
+ } data;
+} XClientMessageEvent;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The message_type member is set to an atom that indicates how the data
+should be interpreted by the receiving client.
+The format member is set to 8, 16, or 32 and specifies whether the data
+should be viewed as a list of bytes, shorts, or longs.
+The data member is a union that contains the members b, s, and l.
+The b, s, and l members represent data of twenty 8-bit values,
+ten 16-bit values, and five 32-bit values.
+Particular message types might not make use of all these values.
+The X server places no interpretation on the values in the window,
+message_type, or data members.
+</para>
+</sect2>
+<sect2 id="PropertyNotify_Events">
+<title>PropertyNotify Events</title>
+<!-- .XS -->
+<!-- (SN PropertyNotify Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Events</primary><secondary>PropertyNotify</secondary></indexterm>
+<indexterm significance="preferred"><primary>PropertyNotify</primary></indexterm>
+The X server can report
+<symbol>PropertyNotify</symbol>
+events to clients wanting information about property changes
+for a specified window.
+</para>
+<para>
+<!-- .LP -->
+To receive
+<symbol>PropertyNotify</symbol>
+events, set the
+<symbol>PropertyChangeMask</symbol>
+bit in the event-mask attribute of the window.
+</para>
+<para>
+<!-- .LP -->
+The structure for this event type contains:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XPropertyEvent</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+ int type; /* PropertyNotify */
+ unsigned long serial; /* # of last request processed by server */
+ Bool send_event; /* true if this came from a SendEvent request */
+ Display *display; /* Display the event was read from */
+ Window window;
+ Atom atom;
+ Time time;
+ int state; /* PropertyNewValue or PropertyDelete */
+} XPropertyEvent;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The window member is set to the window whose associated
+property was changed.
+The atom member is set to the property's atom and indicates which
+property was changed or desired.
+The time member is set to the server time when the property was changed.
+The state member is set to indicate whether the property was changed
+to a new value or deleted and can be
+<symbol>PropertyNewValue</symbol>
+or
+<symbol>PropertyDelete</symbol>.
+The state member is set to
+<symbol>PropertyNewValue</symbol>
+when a property of the window is changed using
+<xref linkend='XChangeProperty' xrefstyle='select: title'/>
+or
+<xref linkend='XRotateWindowProperties' xrefstyle='select: title'/>
+(even when adding zero-length data using
+<xref linkend='XChangeProperty' xrefstyle='select: title'/>)
+and when replacing all or part of a property with identical data using
+<xref linkend='XChangeProperty' xrefstyle='select: title'/>
+or
+<xref linkend='XRotateWindowProperties' xrefstyle='select: title'/>.
+The state member is set to
+<symbol>PropertyDelete</symbol>
+when a property of the window is deleted using
+<xref linkend='XDeleteProperty' xrefstyle='select: title'/>
+or, if the delete argument is
+<symbol>True</symbol>,
+<xref linkend='XGetWindowProperty' xrefstyle='select: title'/>.
+</para>
+</sect2>
+<sect2 id="SelectionClear_Events">
+<title>SelectionClear Events</title>
+<!-- .XS -->
+<!-- (SN SelectionClear Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm ><primary>Events</primary><secondary>SelectionClear</secondary></indexterm>
+<indexterm significance="preferred"><primary>SelectionClear</primary></indexterm>
+The X server reports
+<symbol>SelectionClear</symbol>
+events to the client losing ownership of a selection.
+The X server generates this event type when another client
+asserts ownership of the selection by calling
+<xref linkend='XSetSelectionOwner' xrefstyle='select: title'/>.
+</para>
+<para>
+<!-- .LP -->
+The structure for this event type contains:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XSelectionClearEvent</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+ int type; /* SelectionClear */
+ unsigned long serial; /* # of last request processed by server */
+ Bool send_event; /* true if this came from a SendEvent request */
+ Display *display; /* Display the event was read from */
+ Window window;
+ Atom selection;
+ Time time;
+} XSelectionClearEvent;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The selection member is set to the selection atom.
+The time member is set to the last change time recorded for the
+selection.
+The window member is the window that was specified by the current owner
+(the owner losing the selection) in its
+<xref linkend='XSetSelectionOwner' xrefstyle='select: title'/>
+call.
+</para>
+</sect2>
+<sect2 id="SelectionRequest_Events">
+<title>SelectionRequest Events</title>
+<!-- .XS -->
+<!-- (SN SelectionRequest Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Events</primary><secondary>SelectionRequest</secondary></indexterm>
+<indexterm significance="preferred"><primary>SelectionRequest</primary></indexterm>
+The X server reports
+<symbol>SelectionRequest</symbol>
+events to the owner of a selection.
+The X server generates this event whenever a client
+requests a selection conversion by calling
+<xref linkend='XConvertSelection' xrefstyle='select: title'/>
+for the owned selection.
+</para>
+<para>
+<!-- .LP -->
+The structure for this event type contains:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XSelectionRequestEvent</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+ int type; /* SelectionRequest */
+ unsigned long serial; /* # of last request processed by server */
+ Bool send_event; /* true if this came from a SendEvent request */
+ Display *display; /* Display the event was read from */
+ Window owner;
+ Window requestor;
+ Atom selection;
+ Atom target;
+ Atom property;
+ Time time;
+} XSelectionRequestEvent;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The owner member is set to the window
+that was specified by the current owner in its
+<xref linkend='XSetSelectionOwner' xrefstyle='select: title'/>
+call.
+The requestor member is set to the window requesting the selection.
+The selection member is set to the atom that names the selection.
+For example, PRIMARY is used to indicate the primary selection.
+The target member is set to the atom that indicates the type
+the selection is desired in.
+The property member can be a property name or
+<symbol>None</symbol>.
+The time member is set to the timestamp or
+<symbol>CurrentTime</symbol>
+value from the
+<systemitem>ConvertSelection</systemitem>
+request.
+</para>
+<para>
+<!-- .LP -->
+The owner should convert the selection based on the specified target type
+and send a
+<symbol>SelectionNotify</symbol>
+event back to the requestor.
+A complete specification for using selections is given in the X Consortium
+standard <citetitle>Inter-Client Communication Conventions Manual</citetitle>.
+</para>
+</sect2>
+<sect2 id="SelectionNotify_Events">
+<title>SelectionNotify Events</title>
+<!-- .XS -->
+<!-- (SN SelectionNotify Events -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Events</primary><secondary>SelectionNotify</secondary></indexterm>
+<indexterm significance="preferred"><primary>SelectionNotify</primary></indexterm>
+This event is generated by the X server in response to a
+<systemitem>ConvertSelection</systemitem>
+protocol request when there is no owner for the selection.
+When there is an owner, it should be generated by the owner
+of the selection by using
+<xref linkend='XSendEvent' xrefstyle='select: title'/>.
+The owner of a selection should send this event to a requestor when a selection
+has been converted and stored as a property
+or when a selection conversion could
+not be performed (which is indicated by setting the property member to
+<symbol>None</symbol>).
+</para>
+<para>
+<!-- .LP -->
+If
+<symbol>None</symbol>
+is specified as the property in the
+<systemitem>ConvertSelection</systemitem>
+protocol request, the owner should choose a property name,
+store the result as that property on the requestor window,
+and then send a
+<symbol>SelectionNotify</symbol>
+giving that actual property name.
+</para>
+<para>
+<!-- .LP -->
+The structure for this event type contains:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XSelectionEvent</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+ int type; /* SelectionNotify */
+ unsigned long serial; /* # of last request processed by server */
+ Bool send_event; /* true if this came from a SendEvent request */
+ Display *display; /* Display the event was read from */
+ Window requestor;
+ Atom selection;
+ Atom target;
+ Atom property; /* atom or None */
+ Time time;
+} XSelectionEvent;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The requestor member is set to the window associated with
+the requestor of the selection.
+The selection member is set to the atom that indicates the selection.
+For example, PRIMARY is used for the primary selection.
+The target member is set to the atom that indicates the converted type.
+For example, PIXMAP is used for a pixmap.
+The property member is set to the atom that indicates which
+property the result was stored on.
+If the conversion failed,
+the property member is set to
+<symbol>None</symbol>.
+The time member is set to the time the conversion took place and
+can be a timestamp or
+<symbol>CurrentTime</symbol>.
+<!-- .bp -->
+
+
+</para>
+</sect2>
+</sect1>
+</chapter>
Index: create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/libX11/CH12.xml
===================================================================
--- create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/libX11/CH12.xml (nonexistent)
+++ create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/libX11/CH12.xml (revision 5)
@@ -0,0 +1,3946 @@
+<?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
+<xref linkend='XAllowEvents' xrefstyle='select: title'/>).
+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
+<xref linkend='XGrabPointer' xrefstyle='select: title'/>
+and
+<xref linkend='XGrabKeyboard' xrefstyle='select: title'/>).
+<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
+<xref linkend='XGrabPointer' xrefstyle='select: title'/>.
+</para>
+<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>unsigned int <parameter>event_mask</parameter></paramdef>
+ <paramdef>int <parameter>pointer_mode</parameter></paramdef>
+ <paramdef>int <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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XGrabPointer' xrefstyle='select: title'/>
+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.
+<xref linkend='XGrabPointer' xrefstyle='select: title'/>
+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
+<xref linkend='XAllowEvents' xrefstyle='select: title'/>
+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
+<xref linkend='XAllowEvents' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XGrabPointer' xrefstyle='select: title'/>
+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,
+<xref linkend='XGrabPointer' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XGrabPointer' xrefstyle='select: title'/>
+can generate
+<errorname>BadCursor</errorname>,
+<errorname>BadValue</errorname>,
+and
+<errorname>BadWindow</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To ungrab the pointer, use
+<xref linkend='XUngrabPointer' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XUngrabPointer' xrefstyle='select: title'/>
+function releases the pointer and any queued events
+if this client has actively grabbed the pointer from
+<xref linkend='XGrabPointer' xrefstyle='select: title'/>,
+<xref linkend='XGrabButton' xrefstyle='select: title'/>,
+or from a normal button press.
+<xref linkend='XUngrabPointer' xrefstyle='select: title'/>
+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
+<xref linkend='XChangeActivePointerGrab' xrefstyle='select: title'/>.
+</para>
+<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>unsigned int <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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XChangeActivePointerGrab' xrefstyle='select: title'/>
+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
+<xref linkend='XGrabButton' xrefstyle='select: title'/>.
+The interpretation of event_mask and cursor is the same as described in
+<xref linkend='XGrabPointer' xrefstyle='select: title'/>.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XChangeActivePointerGrab' xrefstyle='select: title'/>
+can generate
+<errorname>BadCursor</errorname>
+and
+<errorname>BadValue</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To grab a pointer button, use
+<xref linkend='XGrabButton' xrefstyle='select: title'/>.
+</para>
+<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>unsigned int <parameter>button</parameter></paramdef>
+ <paramdef>unsigned int <parameter>modifiers</parameter></paramdef>
+ <paramdef>Window <parameter>grab_window</parameter></paramdef>
+ <paramdef>Bool <parameter>owner_events</parameter></paramdef>
+ <paramdef>unsigned int <parameter>event_mask</parameter></paramdef>
+ <paramdef>int <parameter>pointer_mode</parameter></paramdef>
+ <paramdef>int <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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>button</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the pointer button that is to be grabbed 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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XGrabButton' xrefstyle='select: title'/>
+function establishes a passive grab.
+In the future,
+the pointer is actively grabbed (as for
+<xref linkend='XGrabPointer' xrefstyle='select: title'/>),
+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
+<xref linkend='XGrabPointer' xrefstyle='select: title'/>.
+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
+<xref linkend='XGrabButton' xrefstyle='select: title'/>
+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.
+<xref linkend='XGrabButton' xrefstyle='select: title'/>
+has no effect on an active grab.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XGrabButton' xrefstyle='select: title'/>
+can generate
+<errorname>BadCursor</errorname>,
+<errorname>BadValue</errorname>,
+and
+<errorname>BadWindow</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To ungrab a pointer button, use
+<xref linkend='XUngrabButton' xrefstyle='select: title'/>.
+</para>
+<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>unsigned int <parameter>button</parameter></paramdef>
+ <paramdef>unsigned int <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'>button</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the pointer button that is to be released 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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XUngrabButton' xrefstyle='select: title'/>
+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.
+<xref linkend='XUngrabButton' xrefstyle='select: title'/>
+has no effect on an active grab.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XUngrabButton' xrefstyle='select: title'/>
+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
+<xref linkend='XGrabKeyboard' xrefstyle='select: title'/>.
+</para>
+<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>int <parameter>pointer_mode</parameter></paramdef>
+ <paramdef>int <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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XGrabKeyboard' xrefstyle='select: title'/>
+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.
+<xref linkend='XGrabKeyboard' xrefstyle='select: title'/>
+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
+<xref linkend='XAllowEvents' xrefstyle='select: title'/>
+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
+<xref linkend='XAllowEvents' xrefstyle='select: title'/>
+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,
+<xref linkend='XGrabKeyboard' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XGrabKeyboard' xrefstyle='select: title'/>
+can generate
+<errorname>BadValue</errorname>
+and
+<errorname>BadWindow</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To ungrab the keyboard, use
+<xref linkend='XUngrabKeyboard' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XUngrabKeyboard' xrefstyle='select: title'/>
+function
+releases the keyboard and any queued events if this client has it actively grabbed from
+either
+<xref linkend='XGrabKeyboard' xrefstyle='select: title'/>
+or
+<xref linkend='XGrabKey' xrefstyle='select: title'/>.
+<xref linkend='XUngrabKeyboard' xrefstyle='select: title'/>
+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
+<xref linkend='XGrabKey' xrefstyle='select: title'/>.
+</para>
+<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>unsigned int <parameter>modifiers</parameter></paramdef>
+ <paramdef>Window <parameter>grab_window</parameter></paramdef>
+ <paramdef>Bool <parameter>owner_events</parameter></paramdef>
+ <paramdef>int <parameter>pointer_mode</parameter></paramdef>
+ <paramdef>int <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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XGrabKey' xrefstyle='select: title'/>
+function establishes a passive grab on the keyboard.
+In the future,
+the keyboard is actively grabbed (as for
+<xref linkend='XGrabKeyboard' xrefstyle='select: title'/>),
+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
+<xref linkend='XGrabKeyboard' xrefstyle='select: title'/>.
+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
+<xref linkend='XGrabKey' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XGrabKey' xrefstyle='select: title'/>
+can generate
+<errorname>BadAccess</errorname>,
+<errorname>BadValue</errorname>,
+and
+<errorname>BadWindow</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To ungrab a key, use
+<xref linkend='XUngrabKey' xrefstyle='select: title'/>.
+</para>
+<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>unsigned int <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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XUngrabKey' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XUngrabKey' xrefstyle='select: title'/>
+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
+<xref linkend='XAllowEvents' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XAllowEvents' xrefstyle='select: title'/>
+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 frame='none'>
+ <?dbfo keep-together="always" ?>
+ <tgroup cols='2' align='left' colsep='0' rowsep='0'>
+ <colspec colname='c1' colwidth='1.0*'/>
+ <colspec colname='c2' colwidth='4.0*'/>
+ <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
+ <xref linkend='XGrabButton' xrefstyle='select: title'/>
+ or from a previous
+ <xref linkend='XAllowEvents' xrefstyle='select: title'/>
+ with mode
+ <symbol>SyncPointer</symbol>
+ but not from an
+ <xref linkend='XGrabPointer' xrefstyle='select: title'/>),
+ 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
+ <xref linkend='XGrabKey' xrefstyle='select: title'/>
+ or from a previous
+ <xref linkend='XAllowEvents' xrefstyle='select: title'/>
+ with mode
+ <symbol>SyncKeyboard</symbol>
+ but not from an
+ <xref linkend='XGrabKeyboard' xrefstyle='select: title'/>),
+ 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
+<xref linkend='XAllowEvents' xrefstyle='select: title'/>
+releases both.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XAllowEvents' xrefstyle='select: title'/>
+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
+<xref linkend='XWarpPointer' xrefstyle='select: title'/>.
+</para>
+<indexterm significance="preferred"><primary>XWarpPointer</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='XWarpPointer'>
+<funcprototype>
+ <funcdef><function>XWarpPointer</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>Window <parameter>src_w</parameter></paramdef>
+ <paramdef>Window <parameter>dest_w</parameter></paramdef>
+ <paramdef>int <parameter>src_x</parameter></paramdef>
+ <paramdef>int <parameter>src_y</parameter></paramdef>
+ <paramdef>unsigned int <parameter>src_width</parameter></paramdef>
+ <paramdef>unsigned int <parameter>src_height</parameter></paramdef>
+ <paramdef>int <parameter>dest_x</parameter></paramdef>
+ <paramdef>int <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>
+<!-- .LP -->
+<!-- .eM -->
+If dest_w is
+<symbol>None</symbol>,
+<xref linkend='XWarpPointer' xrefstyle='select: title'/>
+moves the pointer by the offsets (dest_x, dest_y) relative to the current
+position of the pointer.
+If dest_w is a window,
+<xref linkend='XWarpPointer' xrefstyle='select: title'/>
+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
+<xref linkend='XWarpPointer' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XWarpPointer' xrefstyle='select: title'/>
+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
+<citetitle>Inter-Client Communication Conventions Manual</citetitle>
+for input focus policy.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set the input focus, use
+<xref linkend='XSetInputFocus' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XSetInputFocus' xrefstyle='select: title'/>
+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).
+<xref linkend='XSetInputFocus' xrefstyle='select: title'/>
+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
+<xref linkend='XSetInputFocus' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XSetInputFocus' xrefstyle='select: title'/>
+can generate
+<errorname>BadMatch</errorname>,
+<errorname>BadValue</errorname>,
+and
+<errorname>BadWindow</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain the current input focus, use
+<xref linkend='XGetInputFocus' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XGetInputFocus' xrefstyle='select: title'/>
+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
+<xref linkend='XChangeKeyboardControl' xrefstyle='select: title'/>
+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<<0)
+#define KBBellPitch (1L<<1)
+#define KBBellDuration (1L<<2)
+#define KBLed (1L<<3)
+#define KBLedMode (1L<<4)
+#define KBKey (1L<<5)
+#define KBAutoRepeatMode (1L<<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 -->
+</para>
+<indexterm significance="preferred"><primary>XChangeKeyboardControl</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='XChangeKeyboardControl'>
+<funcprototype>
+ <funcdef><function>XChangeKeyboardControl</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>unsigned long <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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XChangeKeyboardControl' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XChangeKeyboardControl' xrefstyle='select: title'/>
+can generate
+<errorname>BadMatch</errorname>
+and
+<errorname>BadValue</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain the current control values for the keyboard, use
+<xref linkend='XGetKeyboardControl' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XGetKeyboardControl' xrefstyle='select: title'/>
+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
+<xref linkend='XAutoRepeatOn' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XAutoRepeatOn' xrefstyle='select: title'/>
+function turns on auto-repeat for the keyboard on the specified display.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To turn off keyboard auto-repeat, use
+<xref linkend='XAutoRepeatOff' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XAutoRepeatOff' xrefstyle='select: title'/>
+function turns off auto-repeat for the keyboard on the specified display.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To ring the bell, use
+<xref linkend='XBell' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XBell' xrefstyle='select: title'/>
+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
+<xref linkend='XChangeKeyboardControl' xrefstyle='select: title'/>.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XBell' xrefstyle='select: title'/>
+can generate a
+<errorname>BadValue</errorname>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain a bit vector that describes the state of the keyboard, use
+<xref linkend='XQueryKeymap' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XQueryKeymap' xrefstyle='select: title'/>
+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
+<xref linkend='XSetPointerMapping' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XSetPointerMapping' xrefstyle='select: title'/>
+function sets the mapping of the pointer.
+If it succeeds, the X server generates a
+<symbol>MappingNotify</symbol>
+event, and
+<xref linkend='XSetPointerMapping' xrefstyle='select: title'/>
+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
+<xref linkend='XGetPointerMapping' xrefstyle='select: title'/>
+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,
+<xref linkend='XSetPointerMapping' xrefstyle='select: title'/>
+returns
+<symbol>MappingBusy</symbol>,
+and the mapping is not changed.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XSetPointerMapping' xrefstyle='select: title'/>
+can generate a
+<errorname>BadValue</errorname>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To get the pointer mapping, use
+<xref linkend='XGetPointerMapping' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XGetPointerMapping' xrefstyle='select: title'/>
+function returns the current mapping of the pointer.
+Pointer buttons are numbered starting from one.
+<xref linkend='XGetPointerMapping' xrefstyle='select: title'/>
+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
+<xref linkend='XChangePointerControl' xrefstyle='select: title'/>.
+</para>
+<indexterm significance="preferred"><primary>XChangePointerControl</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='XChangePointerControl'>
+<funcprototype>
+ <funcdef><function>XChangePointerControl</function></funcdef>
+ <paramdef>Display *<parameter>display</parameter></paramdef>
+ <paramdef>Bool <parameter>do_accel</parameter></paramdef>
+ <paramdef>Bool <parameter>do_threshold</parameter></paramdef>
+ <paramdef>int <parameter>accel_numerator</parameter></paramdef>
+ <paramdef>int <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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XChangePointerControl' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XChangePointerControl' xrefstyle='select: title'/>
+can generate a
+<errorname>BadValue</errorname>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To get the current pointer parameters, use
+<xref linkend='XGetPointerControl' xrefstyle='select: title'/>.
+</para>
+<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 *<parameter>accel_numerator_return</parameter></paramdef>
+ <paramdef>int *<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XGetPointerControl' xrefstyle='select: title'/>
+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"><X11/keysymdef.h></filename>.
+<indexterm type="file"><primary><filename class="headerfile">X11/keysymdef.h</filename></primary></indexterm>
+<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/keysymdef.h></filename></secondary></indexterm>
+<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/keysymdef.h></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"><X11/keysym.h></filename>,
+<indexterm type="file"><primary><filename class="headerfile">X11/keysym.h</filename></primary></indexterm>
+<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/keysym.h></filename></secondary></indexterm>
+<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/keysym.h></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
+<xref linkend='XDisplayKeycodes' xrefstyle='select: title'/>.
+</para>
+<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 *<parameter>min_keycodes_return</parameter></paramdef>
+ <paramdef>int *<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XDisplayKeycodes' xrefstyle='select: title'/>
+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
+<xref linkend='XGetKeyboardMapping' xrefstyle='select: title'/>.
+</para>
+<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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>first_keycode</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the first KeyCode that is to be returned.
+ </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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XGetKeyboardMapping' xrefstyle='select: title'/>
+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
+<xref linkend='XDisplayKeycodes' xrefstyle='select: title'/>,
+or a
+<errorname>BadValue</errorname>
+error results.
+In addition, the following expression must be less than or equal
+to max_keycode as returned by
+<xref linkend='XDisplayKeycodes' xrefstyle='select: title'/>:
+</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
+<xref linkend='XGetKeyboardMapping' xrefstyle='select: title'/>,
+use
+<xref linkend='XFree' xrefstyle='select: title'/>.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XGetKeyboardMapping' xrefstyle='select: title'/>
+can generate a
+<errorname>BadValue</errorname>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To change the keyboard mapping, use
+<xref linkend='XChangeKeyboardMapping' xrefstyle='select: title'/>.
+</para>
+<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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>first_keycode</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the first KeyCode that is to be changed.
+ </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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XChangeKeyboardMapping' xrefstyle='select: title'/>
+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
+<xref linkend='XDisplayKeycodes' xrefstyle='select: title'/>,
+or a
+<errorname>BadValue</errorname>
+error results.
+In addition, the following expression must be less than or equal to
+max_keycode as returned by
+<xref linkend='XDisplayKeycodes' xrefstyle='select: title'/>,
+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.
+<xref linkend='XChangeKeyboardMapping' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XChangeKeyboardMapping' xrefstyle='select: title'/>
+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
+<xref linkend='XNewModifiermap' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XNewModifiermap' xrefstyle='select: title'/>
+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
+<xref linkend='XInsertModifiermapEntry' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XInsertModifiermapEntry' xrefstyle='select: title'/>
+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
+<xref linkend='XDeleteModifiermapEntry' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XDeleteModifiermapEntry' xrefstyle='select: title'/>
+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
+<xref linkend='XFreeModifiermap' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XFreeModifiermap' xrefstyle='select: title'/>
+function frees the specified
+<structname>XModifierKeymap</structname>
+structure.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set the KeyCodes to be used as modifiers, use
+<xref linkend='XSetModifierMapping' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XSetModifierMapping' xrefstyle='select: title'/>
+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
+<xref linkend='XSetModifierMapping' xrefstyle='select: title'/>
+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,
+<xref linkend='XSetModifierMapping' xrefstyle='select: title'/>
+returns
+<symbol>MappingBusy</symbol>,
+and none of the modifiers is changed.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XSetModifierMapping' xrefstyle='select: title'/>
+can generate
+<errorname>BadAlloc</errorname>
+and
+<errorname>BadValue</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain the KeyCodes used as modifiers, use
+<xref linkend='XGetModifierMapping' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XGetModifierMapping' xrefstyle='select: title'/>
+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
+<xref linkend='XFreeModifiermap' xrefstyle='select: title'/>.
+If only zero values appear in the set for any modifier,
+that modifier is disabled.
+<!-- .bp -->
+
+
+</para>
+</sect1>
+</chapter>
Index: create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/libX11/CH14.xml
===================================================================
--- create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/libX11/CH14.xml (nonexistent)
+++ create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/libX11/CH14.xml (revision 5)
@@ -0,0 +1,5237 @@
+<?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 <citetitle>Inter-Client Communication Conventions Manual</citetitle>,
+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 <citetitle>Inter-Client Communication Conventions Manual</citetitle>.
+</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 <X11/Xatom.h>
+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 <link linkend="Properties_and_Atoms">section 4.3</link>.
+</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 <link linkend="Selections">4.5</link> and
+<link linkend="Using_Cut_Buffers">16.6</link>). 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 frame='topbot'>
+ <?dbfo keep-together="always" ?>
+ <tgroup cols='4' align='left' colsep='0' rowsep='0'>
+ <colspec colname='c1' colwidth='3.0*'/>
+ <colspec colname='c2' colwidth='2.3*'/>
+ <colspec colname='c3' colwidth='0.9*'/>
+ <colspec colname='c4' colwidth='2.7*'/>
+ <thead>
+ <row rowsep='1'>
+ <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
+<link linkend='Window_Functions'>chapter 3</link>
+to manipulate your application's subwindows.
+</para>
+<para>
+<!-- .LP -->
+To request that a top-level window be iconified, use
+<xref linkend='XIconifyWindow' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XIconifyWindow' xrefstyle='select: title'/>
+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
+<citetitle>Inter-Client Communication Conventions Manual</citetitle>)
+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,
+<xref linkend='XIconifyWindow' xrefstyle='select: title'/>
+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
+<xref linkend='XWithdrawWindow' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XWithdrawWindow' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XWithdrawWindow' xrefstyle='select: title'/>
+can generate a
+<errorname>BadWindow</errorname>
+error.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To request that a top-level window be reconfigured, use
+<xref linkend='XReconfigureWMWindow' xrefstyle='select: title'/>.
+</para>
+<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>unsigned int <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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XReconfigureWMWindow' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XReconfigureWMWindow' xrefstyle='select: title'/>
+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
+<xref linkend='XmbTextListToTextProperty' xrefstyle='select: title'/>
+or
+<xref linkend='XwcTextListToTextProperty' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XmbTextListToTextProperty' xrefstyle='select: title'/>
+and
+<xref linkend='XwcTextListToTextProperty' xrefstyle='select: title'/>
+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
+<xref linkend='XFree' xrefstyle='select: title'/>.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To obtain a list of text strings from an
+<structname>XTextProperty</structname>
+structure, use
+<xref linkend='XmbTextPropertyToTextList' xrefstyle='select: title'/>
+or
+<xref linkend='XwcTextPropertyToTextList' xrefstyle='select: title'/>.
+</para>
+<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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>count_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the number of strings.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XmbTextPropertyToTextList' xrefstyle='select: title'/>
+and
+<xref linkend='XwcTextPropertyToTextList' xrefstyle='select: title'/>
+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,
+<xref linkend='XmbTextPropertyToTextList' xrefstyle='select: title'/>
+and
+<xref linkend='XwcTextPropertyToTextList' xrefstyle='select: title'/>
+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,
+<xref linkend='XmbTextPropertyToTextList' xrefstyle='select: title'/>
+and
+<xref linkend='XwcTextPropertyToTextList' xrefstyle='select: title'/>
+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,
+<xref linkend='XmbTextPropertyToTextList' xrefstyle='select: title'/>
+and
+<xref linkend='XwcTextPropertyToTextList' xrefstyle='select: title'/>
+return
+<symbol>Success</symbol>.
+</para>
+<para>
+<!-- .LP -->
+To free the storage for the list and its contents returned by
+<xref linkend='XmbTextPropertyToTextList' xrefstyle='select: title'/>,
+use
+<xref linkend='XFreeStringList' xrefstyle='select: title'/>.
+To free the storage for the list and its contents returned by
+<xref linkend='XwcTextPropertyToTextList' xrefstyle='select: title'/>,
+use
+<xref linkend='XwcFreeStringList' xrefstyle='select: title'/>.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To free the in-memory data associated with the specified
+wide character string list, use
+<xref linkend='XwcFreeStringList' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XwcFreeStringList' xrefstyle='select: title'/>
+function frees memory allocated by
+<xref linkend='XwcTextPropertyToTextList' xrefstyle='select: title'/>.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To obtain the default string for text conversion in the current locale,
+use</para>
+
+<funcsynopsis id='XDefaultString'>
+<funcprototype>
+ <funcdef>char *<function>XDefaultString</function></funcdef>
+ <void />
+</funcprototype>
+</funcsynopsis>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XDefaultString</function>
+function returns the default string used by Xlib for text conversion
+(for example, in
+<xref linkend='XmbTextPropertyToTextList' xrefstyle='select: title'/>).
+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
+<xref linkend='XCreateFontSet' xrefstyle='select: title'/>
+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
+<xref linkend='XStringListToTextProperty' xrefstyle='select: title'/>.
+</para>
+<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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>count</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of strings.
+ </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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XStringListToTextProperty' xrefstyle='select: title'/>
+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,
+<xref linkend='XStringListToTextProperty' xrefstyle='select: title'/>
+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
+<xref linkend='XFree' xrefstyle='select: title'/>.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To obtain a list of strings from a specified
+<structname>XTextProperty</structname>
+structure in the STRING encoding, use
+<xref linkend='XTextPropertyToStringList' xrefstyle='select: title'/>.
+</para>
+<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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>count_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the number of strings.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XTextPropertyToStringList' xrefstyle='select: title'/>
+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,
+<xref linkend='XTextPropertyToStringList' xrefstyle='select: title'/>
+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
+<xref linkend='XFreeStringList' xrefstyle='select: title'/>.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To free the in-memory data associated with the specified string list, use
+<xref linkend='XFreeStringList' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XFreeStringList' xrefstyle='select: title'/>
+function releases memory allocated by
+<xref linkend='XmbTextPropertyToTextList' xrefstyle='select: title'/>
+and
+<xref linkend='XTextPropertyToStringList' xrefstyle='select: title'/>
+and the missing charset list allocated by
+<xref linkend='XCreateFontSet' xrefstyle='select: title'/>.
+</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
+<link linkend="Setting_and_Reading_the_WM_NAME_Property">14.1.4</link>,
+<link linkend="Setting_and_Reading_the_WM_ICON_NAME_Property">14.1.5</link>,
+<link linkend="Setting_and_Reading_the_WM_COMMAND_Property">14.2.1</link>, and
+<link linkend="Setting_and_Reading_the_WM_CLIENT_MACHINE_Property">14.2.2</link>,
+respectively.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To set one of a window's text properties, use
+<xref linkend='XSetTextProperty' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XSetTextProperty' xrefstyle='select: title'/>
+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,
+<xref linkend='XSetTextProperty' xrefstyle='select: title'/>
+sets it for the specified window.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XSetTextProperty' xrefstyle='select: title'/>
+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
+<xref linkend='XGetTextProperty' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XGetTextProperty' xrefstyle='select: title'/>
+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,
+<xref linkend='XGetTextProperty' xrefstyle='select: title'/>
+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,
+<xref linkend='XGetTextProperty' xrefstyle='select: title'/>
+returns a nonzero status;
+otherwise, it returns a zero status.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XGetTextProperty' xrefstyle='select: title'/>
+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
+<xref linkend='XSetWMName' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XSetWMName' xrefstyle='select: title'/>
+convenience function calls
+<xref linkend='XSetTextProperty' xrefstyle='select: title'/>
+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
+<xref linkend='XGetWMName' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XGetWMName' xrefstyle='select: title'/>
+convenience function calls
+<xref linkend='XGetTextProperty' xrefstyle='select: title'/>
+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
+<xref linkend='XSetWMName' xrefstyle='select: title'/>
+and
+<xref linkend='XGetWMName' xrefstyle='select: title'/>,
+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
+<xref linkend='XStoreName' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XStoreName' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XStoreName' xrefstyle='select: title'/>
+can generate
+<errorname>BadAlloc</errorname>
+and
+<errorname>BadWindow</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To get the name of a window, use
+<xref linkend='XFetchName' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XFetchName' xrefstyle='select: title'/>
+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,
+<xref linkend='XFetchName' xrefstyle='select: title'/>
+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
+<xref linkend='XFree' xrefstyle='select: title'/>.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XFetchName' xrefstyle='select: title'/>
+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
+<xref linkend='XSetWMIconName' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XSetWMIconName' xrefstyle='select: title'/>
+convenience function calls
+<xref linkend='XSetTextProperty' xrefstyle='select: title'/>
+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
+<xref linkend='XGetWMIconName' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XGetWMIconName' xrefstyle='select: title'/>
+convenience function calls
+<xref linkend='XGetTextProperty' xrefstyle='select: title'/>
+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
+<xref linkend='XSetWMIconName' xrefstyle='select: title'/>
+and
+<xref linkend='XGetWMIconName' xrefstyle='select: title'/>,
+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
+<xref linkend='XSetIconName' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+If the string is not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+<xref linkend='XSetIconName' xrefstyle='select: title'/>
+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
+<xref linkend='XGetIconName' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XGetIconName' xrefstyle='select: title'/>
+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,
+<xref linkend='XGetIconName' xrefstyle='select: title'/>
+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
+<xref linkend='XFree' xrefstyle='select: title'/>.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XGetIconName' xrefstyle='select: title'/>
+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"><X11/Xutil.h></filename>
+<indexterm type="file"><primary><filename class="headerfile">X11/Xutil.h</filename></primary></indexterm>
+<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/Xutil.h></filename></secondary></indexterm>
+<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/Xutil.h></filename></secondary></indexterm>
+header file.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To allocate an
+<structname>XWMHints</structname>
+structure, use
+<function>XAllocWMHints</function>.
+</para>
+
+<funcsynopsis id='XAllocWMHints'>
+<funcprototype>
+ <funcdef>XWMHints *<function>XAllocWMHints</function></funcdef>
+ <void />
+</funcprototype>
+</funcsynopsis>
+
+<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
+<xref linkend='XFree' xrefstyle='select: title'/>.
+</para>
+<para>
+<!-- .LP -->
+The
+<structname>XWMHints</structname>
+structure contains:
+</para>
+
+<literallayout class="monospaced">
+/* Window manager hints mask bits */
+
+#define InputHint (1L<<0)
+#define StateHint (1L<<1)
+#define IconPixmapHint (1L<<2)
+#define IconWindowHint (1L<<3)
+#define IconPositionHint (1L<<4)
+#define IconMaskHint (1L<<5)
+#define WindowGroupHint (1L<<6)
+#define UrgencyHint (1L<<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 3 /* 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
+<xref linkend='XSetWMHints' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XSetWMHints' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XSetWMHints' xrefstyle='select: title'/>
+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
+<xref linkend='XGetWMHints' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XGetWMHints' xrefstyle='select: title'/>
+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
+<xref linkend='XFree' xrefstyle='select: title'/>.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XGetWMHints' xrefstyle='select: title'/>
+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"><X11/Xutil.h></filename>
+<indexterm type="file"><primary><filename class="headerfile">X11/Xutil.h</filename></primary></indexterm>
+<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/Xutil.h></filename></secondary></indexterm>
+<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/Xutil.h></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>
+
+<funcsynopsis id='XAllocSizeHints'>
+<funcprototype>
+ <funcdef>XSizeHints *<function>XAllocSizeHints</function></funcdef>
+ <void />
+</funcprototype>
+</funcsynopsis>
+<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
+<xref linkend='XFree' xrefstyle='select: title'/>.
+</para>
+<para>
+<!-- .LP -->
+The
+<structname>XSizeHints</structname>
+structure contains:
+</para>
+
+
+<literallayout class="monospaced">
+/* Size hints mask bits */
+
+#define USPosition (1L<<0) /* user specified x,y */
+#define USSize (1L<<1) /* user specified width,height */
+#define PPosition (1L<<2) /* program specified position */
+#define PSize (1L<<3) /* program specified size */
+#define PMinSize (1L<<4) /* program specified minimum size */
+#define PMaxSize (1L<<5) /* program specified maximum size */
+#define PResizeInc (1L<<5) /* program specified resize increments */
+#define PAspect (1L<<6) /* program specified min and max aspect ratios */
+#define PBaseSize (1L<<8)
+#define PWinGravity (1L<<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
+<xref linkend='XSetWMNormalHints' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XSetWMNormalHints' xrefstyle='select: title'/>
+function replaces the size hints for the <property>WM_NORMAL_HINTS</property> property
+on the specified window.
+If the property does not already exist,
+<xref linkend='XSetWMNormalHints' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XSetWMNormalHints' xrefstyle='select: title'/>
+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
+<xref linkend='XGetWMNormalHints' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XGetWMNormalHints' xrefstyle='select: title'/>
+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,
+<xref linkend='XGetWMNormalHints' xrefstyle='select: title'/>
+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
+<xref linkend='XGetWMNormalHints' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XGetWMNormalHints' xrefstyle='select: title'/>
+can generate a
+<errorname>BadWindow</errorname>
+error.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To set a window's <property>WM_SIZE_HINTS</property> property, use
+<xref linkend='XSetWMSizeHints' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XSetWMSizeHints' xrefstyle='select: title'/>
+function replaces the size hints for the specified property
+on the named window.
+If the specified property does not already exist,
+<xref linkend='XSetWMSizeHints' xrefstyle='select: title'/>
+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
+<xref linkend='XSetWMNormalHints' xrefstyle='select: title'/>
+function.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XSetWMSizeHints' xrefstyle='select: title'/>
+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
+<xref linkend='XGetWMSizeHints' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XGetWMSizeHints' xrefstyle='select: title'/>
+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,
+<xref linkend='XGetWMSizeHints' xrefstyle='select: title'/>
+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
+<xref linkend='XGetWMNormalHints' xrefstyle='select: title'/>
+function.
+</para>
+<para>
+<!-- .LP -->
+If
+<xref linkend='XGetWMSizeHints' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XGetWMSizeHints' xrefstyle='select: title'/>
+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"><X11/Xutil.h></filename>
+<indexterm type="file"><primary><filename class="headerfile">X11/Xutil.h</filename></primary></indexterm>
+<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/Xutil.h></filename></secondary></indexterm>
+<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/Xutil.h></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>
+
+<funcsynopsis id='XAllocClassHint'>
+<funcprototype>
+ <funcdef>XClassHint *<function>XAllocClassHint</function></funcdef>
+ <void />
+</funcprototype>
+</funcsynopsis>
+
+<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
+<xref linkend='XFree' xrefstyle='select: title'/>.
+</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
+<xref linkend='XSetClassHint' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XSetClassHint' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XSetClassHint' xrefstyle='select: title'/>
+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
+<xref linkend='XGetClassHint' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XGetClassHint' xrefstyle='select: title'/>
+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
+<xref linkend='XFree' xrefstyle='select: title'/>
+on each individually.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XGetClassHint' xrefstyle='select: title'/>
+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
+<xref linkend='XSetTransientForHint' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XSetTransientForHint' xrefstyle='select: title'/>
+function sets the <property>WM_TRANSIENT_FOR</property> property of the specified window to the
+specified prop_window.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XSetTransientForHint' xrefstyle='select: title'/>
+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
+<xref linkend='XGetTransientForHint' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XGetTransientForHint' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XGetTransientForHint' xrefstyle='select: title'/>
+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
+<xref linkend='XSetWMProtocols' xrefstyle='select: title'/>.
+</para>
+<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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>count</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of protocols in the list.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XSetWMProtocols' xrefstyle='select: title'/>
+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,
+<xref linkend='XSetWMProtocols' xrefstyle='select: title'/>
+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,
+<xref linkend='XSetWMProtocols' xrefstyle='select: title'/>
+returns a zero status.
+Otherwise, it returns a nonzero status.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XSetWMProtocols' xrefstyle='select: title'/>
+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
+<xref linkend='XGetWMProtocols' xrefstyle='select: title'/>.
+</para>
+<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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>count_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the number of protocols in the list.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XGetWMProtocols' xrefstyle='select: title'/>
+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,
+<xref linkend='XGetWMProtocols' xrefstyle='select: title'/>
+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
+<xref linkend='XFree' xrefstyle='select: title'/>.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XGetWMProtocols' xrefstyle='select: title'/>
+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
+<xref linkend='XSetWMColormapWindows' xrefstyle='select: title'/>.
+</para>
+<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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>count</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of windows in the list.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XSetWMColormapWindows' xrefstyle='select: title'/>
+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,
+<xref linkend='XSetWMColormapWindows' xrefstyle='select: title'/>
+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,
+<xref linkend='XSetWMColormapWindows' xrefstyle='select: title'/>
+returns a zero status.
+Otherwise, it returns a nonzero status.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XSetWMColormapWindows' xrefstyle='select: title'/>
+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
+<xref linkend='XGetWMColormapWindows' xrefstyle='select: title'/>.
+</para>
+<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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>count_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the number of windows in the list.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XGetWMColormapWindows' xrefstyle='select: title'/>
+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,
+<xref linkend='XGetWMColormapWindows' xrefstyle='select: title'/>
+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
+<xref linkend='XFree' xrefstyle='select: title'/>.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XGetWMColormapWindows' xrefstyle='select: title'/>
+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"><X11/Xutil.h></filename>
+<indexterm type="file"><primary><filename class="headerfile">X11/Xutil.h</filename></primary></indexterm>
+<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/Xutil.h></filename></secondary></indexterm>
+<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/Xutil.h></filename></secondary></indexterm>
+header file.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To allocate an
+<structname>XIconSize</structname>
+structure, use
+<function>XAllocIconSize</function>.
+</para>
+
+<funcsynopsis id='XAllocIconSize'>
+<funcprototype>
+ <funcdef>XIconSize *<function>XAllocIconSize</function></funcdef>
+ <void />
+</funcprototype>
+</funcsynopsis>
+
+<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
+<xref linkend='XFree' xrefstyle='select: title'/>.
+</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
+<xref linkend='XSetIconSizes' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XSetIconSizes' xrefstyle='select: title'/>
+function is used only by window managers to set the supported icon sizes.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XSetIconSizes' xrefstyle='select: title'/>
+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
+<xref linkend='XGetIconSizes' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XGetIconSizes' xrefstyle='select: title'/>
+function returns zero if a window manager has not set icon sizes;
+otherwise, it returns nonzero.
+<xref linkend='XGetIconSizes' xrefstyle='select: title'/>
+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
+<xref linkend='XSetWMHints' xrefstyle='select: title'/>
+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
+<xref linkend='XFree' xrefstyle='select: title'/>.
+</para>
+<para>
+<!-- .LP -->
+<xref linkend='XGetIconSizes' xrefstyle='select: title'/>
+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
+<xref linkend='XmbSetWMProperties' xrefstyle='select: title'/>
+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>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XmbSetWMProperties' xrefstyle='select: title'/>
+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,
+<xref linkend='XmbSetWMProperties' xrefstyle='select: title'/>
+sets the <property>WM_NAME</property> property.
+If the icon_name argument is non-NULL,
+<xref linkend='XmbSetWMProperties' xrefstyle='select: title'/>
+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,
+<xref linkend='XmbSetWMProperties' xrefstyle='select: title'/>
+calls
+<xref linkend='XSetWMNormalHints' xrefstyle='select: title'/>,
+which sets the <property>WM_NORMAL_HINTS</property> property
+(see <link linkend="Setting_and_Reading_the_WM_NORMAL_HINTS_Property">section 14.1.7</link>).
+If the wm_hints argument is non-NULL,
+<xref linkend='XmbSetWMProperties' xrefstyle='select: title'/>
+calls
+<xref linkend='XSetWMHints' xrefstyle='select: title'/>,
+which sets the <property>WM_HINTS</property> property
+(see <link linkend="Setting_and_Reading_the_WM_HINTS_Property">section 14.1.6</link>).
+</para>
+<para>
+<!-- .LP -->
+If the argv argument is non-NULL,
+<xref linkend='XmbSetWMProperties' xrefstyle='select: title'/>
+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
+<xref linkend='XSetWMClientMachine' xrefstyle='select: title'/>
+(see <link linkend="Setting_and_Reading_the_WM_CLIENT_MACHINE_Property">section 14.2.2</link>).
+</para>
+<para>
+<!-- .LP -->
+If the class_hints argument is non-NULL,
+<xref linkend='XmbSetWMProperties' xrefstyle='select: title'/>
+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,
+<xref linkend='XmbSetWMProperties' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XmbSetWMProperties' xrefstyle='select: title'/>
+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
+<xref linkend='XSetWMProperties' xrefstyle='select: title'/>.
+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>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XSetWMProperties' xrefstyle='select: title'/>
+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,
+<xref linkend='XSetWMProperties' xrefstyle='select: title'/>
+calls
+<xref linkend='XSetWMName' xrefstyle='select: title'/>,
+which, in turn, sets the <property>WM_NAME</property> property
+(see <link linkend="Setting_and_Reading_the_WM_NAME_Property">section 14.1.4</link>).
+If the icon_name argument is non-NULL,
+<xref linkend='XSetWMProperties' xrefstyle='select: title'/>
+calls
+<xref linkend='XSetWMIconName' xrefstyle='select: title'/>,
+which sets the <property>WM_ICON_NAME</property> property
+(see <link linkend="Setting_and_Reading_the_WM_ICON_NAME_Property">section 14.1.5</link>).
+If the argv argument is non-NULL,
+<xref linkend='XSetWMProperties' xrefstyle='select: title'/>
+calls
+<xref linkend='XSetCommand' xrefstyle='select: title'/>,
+which sets the <property>WM_COMMAND</property> property
+(see <link linkend="Setting_and_Reading_the_WM_COMMAND_Property">section 14.2.1</link>).
+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
+<xref linkend='XSetWMClientMachine' xrefstyle='select: title'/>
+(see <link linkend="Setting_and_Reading_the_WM_CLIENT_MACHINE_Property">section 14.2.2</link>).
+</para>
+<para>
+<!-- .LP -->
+If the normal_hints argument is non-NULL,
+<xref linkend='XSetWMProperties' xrefstyle='select: title'/>
+calls
+<xref linkend='XSetWMNormalHints' xrefstyle='select: title'/>,
+which sets the <property>WM_NORMAL_HINTS</property> property
+(see <link linkend="Setting_and_Reading_the_WM_NORMAL_HINTS_Property">section 14.1.7</link>).
+If the wm_hints argument is non-NULL,
+<xref linkend='XSetWMProperties' xrefstyle='select: title'/>
+calls
+<xref linkend='XSetWMHints' xrefstyle='select: title'/>,
+which sets the <property>WM_HINTS</property> property
+(see <link linkend="Setting_and_Reading_the_WM_HINTS_Property">section 14.1.6</link>).
+</para>
+<para>
+<!-- .LP -->
+If the class_hints argument is non-NULL,
+<xref linkend='XSetWMProperties' xrefstyle='select: title'/>
+calls
+<xref linkend='XSetClassHint' xrefstyle='select: title'/>,
+which sets the <property>WM_CLASS</property> property
+(see <link linkend="Setting_and_Reading_the_WM_CLASS_Property">section 14.1.8</link>).
+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 -->
+<xref linkend='XSetWMProperties' xrefstyle='select: title'/>
+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
+<xref linkend='XSetCommand' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XSetCommand' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XSetCommand' xrefstyle='select: title'/>
+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
+<xref linkend='XGetCommand' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XGetCommand' xrefstyle='select: title'/>
+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,
+<xref linkend='XGetCommand' xrefstyle='select: title'/>
+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
+<xref linkend='XFreeStringList' xrefstyle='select: title'/>.
+</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
+<xref linkend='XSetWMClientMachine' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XSetWMClientMachine' xrefstyle='select: title'/>
+convenience function calls
+<xref linkend='XSetTextProperty' xrefstyle='select: title'/>
+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
+<xref linkend='XGetWMClientMachine' xrefstyle='select: title'/>.
+</para>
+<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>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XGetWMClientMachine' xrefstyle='select: title'/>
+convenience function performs an
+<xref linkend='XGetTextProperty' xrefstyle='select: title'/>
+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>
+
+<funcsynopsis id='XAllocStandardColormap'>
+<funcprototype>
+ <funcdef>XStandardColormap *<function>XAllocStandardColormap</function></funcdef>
+ <void />
+</funcprototype>
+</funcsynopsis>
+
+<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
+<xref linkend='XFree' xrefstyle='select: title'/>.
+</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
+<xref linkend='XCreateColormap' xrefstyle='select: title'/>
+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
+<xref linkend='XAllocColorPlanes' xrefstyle='select: title'/>
+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) & 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) & 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
+<xref linkend='XKillClient' xrefstyle='select: title'/>
+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"><X11/Xatom.h></filename>
+<indexterm type="file"><primary><filename class="headerfile">X11/Xatom.h</filename></primary></indexterm>
+<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/Xatom.h></filename></secondary></indexterm>
+<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/Xatom.h></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
+<xref linkend='XSetRGBColormaps' xrefstyle='select: title'/>.
+</para>
+<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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>count</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of colormaps.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>property</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the property name.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XSetRGBColormaps' xrefstyle='select: title'/>
+function replaces the <acronym>RGB</acronym> colormap definition in the specified property
+on the named window.
+If the property does not already exist,
+<xref linkend='XSetRGBColormaps' xrefstyle='select: title'/>
+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
+<xref linkend='XSetRGBColormaps' xrefstyle='select: title'/>
+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
+<xref linkend='XStoreColors' xrefstyle='select: title'/>
+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
+<xref linkend='XSetCloseDownMode' xrefstyle='select: title'/>
+to make the resource permanent.
+<!-- .RE -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Ungrab the server.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+<xref linkend='XSetRGBColormaps' xrefstyle='select: title'/>
+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
+<xref linkend='XGetRGBColormaps' xrefstyle='select: title'/>.
+</para>
+<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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>count_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the number of colormaps.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>property</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the property name.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<xref linkend='XGetRGBColormaps' xrefstyle='select: title'/>
+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,
+<xref linkend='XGetRGBColormaps' xrefstyle='select: title'/>
+allocates and fills in space for the returned colormaps
+and returns a nonzero status.
+If the visualid is not present,
+<xref linkend='XGetRGBColormaps' xrefstyle='select: title'/>
+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
+<xref linkend='XGetRGBColormaps' xrefstyle='select: title'/>
+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 -->
+<xref linkend='XGetRGBColormaps' xrefstyle='select: title'/>
+can generate
+<errorname>BadAtom</errorname>
+and
+<errorname>BadWindow</errorname>
+errors.
+<!-- .bp -->
+
+</para>
+</sect2>
+</sect1>
+</chapter>
Index: create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/libX11/glossary.xml
===================================================================
--- create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/libX11/glossary.xml (nonexistent)
+++ create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/libX11/glossary.xml (revision 5)
@@ -0,0 +1,1754 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE glossary PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+<glossary id='glossary'>
+<title>Glossary</title>
+<glossentry id="glossary:Access_control_list">
+ <glossterm>Access control list</glossterm>
+<indexterm significance="preferred"><primary>Access control list</primary></indexterm>
+ <glossdef>
+ <para>
+X maintains a list of hosts from which client programs can be run.
+By default,
+only programs on the local host and hosts specified in an initial list read
+by the server can use the display.
+This access control list can be changed by clients on the local host.
+Some server implementations can also implement other authorization mechanisms
+in addition to or in place of this mechanism.
+The action of this mechanism can be conditional based on the authorization
+protocol name and data received by the server at connection setup.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Active_grab">
+ <glossterm>Active grab</glossterm>
+<indexterm significance="preferred"><primary>Active grab</primary></indexterm>
+ <glossdef>
+ <para>
+A grab is active when the pointer or keyboard is actually owned by the
+single grabbing client.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Ancestors">
+ <glossterm>Ancestors</glossterm>
+<indexterm significance="preferred"><primary>Ancestors</primary></indexterm>
+ <glossdef>
+ <para>
+If W is an inferior of A, then A is an ancestor of W.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Atom">
+ <glossterm>Atom</glossterm>
+<indexterm significance="preferred"><primary>Atom</primary></indexterm>
+ <glossdef>
+ <para>
+An atom is a unique ID corresponding to a string name.
+Atoms are used to identify properties, types, and selections.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Background">
+ <glossterm>Background</glossterm>
+<indexterm significance="preferred"><primary>Background</primary></indexterm>
+ <glossdef>
+ <para>
+An
+<symbol>InputOutput</symbol>
+window can have a background, which is defined as a pixmap.
+When regions of the window have their contents lost
+or invalidated,
+the server automatically tiles those regions with the background.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Backing_store">
+ <glossterm>Backing store</glossterm>
+<indexterm significance="preferred"><primary>Backing store</primary></indexterm>
+ <glossdef>
+ <para>
+When a server maintains the contents of a window,
+the pixels saved off-screen are known as a backing store.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Base_font_name">
+ <glossterm>Base font name</glossterm>
+<indexterm significance="preferred"><primary>Base font name</primary></indexterm>
+ <glossdef>
+ <para>
+A font name used to select a family of fonts whose members may be encoded
+in various charsets.
+The
+<structfield>CharSetRegistry</structfield>
+and
+<structfield>CharSetEncoding</structfield>
+fields of an <acronym>XLFD</acronym> name identify the charset of the font.
+A base font name may be a full <acronym>XLFD</acronym> name, with all fourteen '-' delimiters,
+or an abbreviated <acronym>XLFD</acronym> name containing only the first 12 fields of an <acronym>XLFD</acronym> name,
+up to but not including
+<structfield>CharSetRegistry</structfield>,
+with or without the thirteenth '-', or a non-<acronym>XLFD</acronym> name.
+Any <acronym>XLFD</acronym> fields may contain wild cards.
+</para>
+ <para>
+When creating an
+<type>XFontSet</type>,
+Xlib accepts from the client a list of one or more base font names
+which select one or more font families.
+They are combined with charset names obtained from the encoding of the locale
+to load the fonts required to render text.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Bit_gravity">
+ <glossterm>Bit gravity</glossterm>
+<indexterm significance="preferred"><primary>Bit</primary><secondary>gravity</secondary></indexterm>
+ <glossdef>
+ <para>
+When a window is resized,
+the contents of the window are not necessarily discarded.
+It is possible to request that the server relocate the previous contents
+to some region of the window (though no guarantees are made).
+This attraction of window contents for some location of
+a window is known as bit gravity.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Bit_plane">
+ <glossterm>Bit plane</glossterm>
+<indexterm significance="preferred"><primary>Bit</primary><secondary>plane</secondary></indexterm>
+ <glossdef>
+ <para>
+When a pixmap or window is thought of as a stack of bitmaps,
+each bitmap is called a bit plane or plane.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Bitmap">
+ <glossterm>Bitmap</glossterm>
+<indexterm significance="preferred"><primary>Bitmap</primary></indexterm>
+ <glossdef>
+ <para>
+A bitmap is a <glossterm linkend="glossary:Pixmap">pixmap</glossterm> of depth one.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Border">
+ <glossterm>Border</glossterm>
+<indexterm significance="preferred"><primary>Border</primary></indexterm>
+ <glossdef>
+ <para>
+An
+<symbol>InputOutput</symbol>
+window can have a border of equal thickness on all four sides of the window.
+The contents of the border are defined by a pixmap,
+and the server automatically maintains the contents of the border.
+Exposure events are never generated for border regions.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Button_grabbing">
+ <glossterm>Button grabbing</glossterm>
+<indexterm significance="preferred"><primary>Button</primary><secondary>grabbing</secondary></indexterm>
+ <glossdef>
+ <para>
+Buttons on the pointer can be passively grabbed by a client.
+When the button is pressed,
+the pointer is then actively grabbed by the client.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Byte_order">
+ <glossterm>Byte order</glossterm>
+<indexterm significance="preferred"><primary>Byte</primary><secondary>order</secondary></indexterm>
+ <glossdef>
+ <para>
+For image (pixmap/bitmap) data,
+the server defines the byte order,
+and clients with different native byte ordering must swap bytes as
+necessary.
+For all other parts of the protocol,
+the client defines the byte order,
+and the server swaps bytes as necessary.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Character">
+ <glossterm>Character</glossterm>
+<indexterm significance="preferred"><primary>Character</primary></indexterm>
+ <glossdef>
+ <para>
+A member of a set of elements used for the organization,
+control, or representation of text (ISO2022, as adapted by XPG3).
+Note that in ISO2022 terms, a character is not bound to a coded value
+until it is identified as part of a coded character set.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Character_glyph">
+ <glossterm>Character glyph</glossterm>
+<indexterm significance="preferred"><primary>Character glyph</primary></indexterm>
+ <glossdef>
+ <para>
+The abstract graphical symbol for a character.
+Character glyphs may or may not map one-to-one to font glyphs,
+and may be context-dependent, varying with the adjacent characters.
+Multiple characters may map to a single character glyph.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Character_set">
+ <glossterm>Character set</glossterm>
+<indexterm significance="preferred"><primary>Character set</primary></indexterm>
+ <glossdef>
+ <para>
+A collection of characters.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Charset">
+ <glossterm>Charset</glossterm>
+<indexterm significance="preferred"><primary>Charset</primary></indexterm>
+ <glossdef>
+ <para>
+An encoding with a uniform, state-independent mapping from characters
+to codepoints.
+A coded character set.
+</para>
+ <para>
+For display in X,
+there can be a direct mapping from a charset to one font,
+if the width of all characters in the charset is either one or two bytes.
+A text string encoded in an encoding such as Shift-JIS cannot be passed
+directly to the X server, because the text imaging requests accept only
+single-width charsets (either 8 or 16 bits).
+Charsets which meet these restrictions can serve as ``font charsets''.
+Font charsets strictly speaking map font indices to font glyphs,
+not characters to character glyphs.
+</para>
+ <para>
+Note that a single font charset is sometimes used as the encoding of a locale,
+for example, ISO8859-1.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Children">
+ <glossterm>Children</glossterm>
+<indexterm significance="preferred"><primary>Children</primary></indexterm>
+ <glossdef>
+ <para>
+The children of a window are its first-level subwindows.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Class">
+ <glossterm>Class</glossterm>
+<indexterm significance="preferred"><primary>Class</primary></indexterm>
+ <glossdef>
+ <para>
+Windows can be of different classes or types.
+See the entries for
+<glossterm linkend="glossary:InputOnly_window">InputOnly</glossterm>
+and
+<glossterm linkend="glossary:InputOutput_window">InputOutput</glossterm>
+windows for further information about valid window types.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Client">
+ <glossterm>Client</glossterm>
+<indexterm significance="preferred"><primary>Client</primary></indexterm>
+ <glossdef>
+ <para>
+An application program connects to the window system server by some
+interprocess communication (<acronym>IPC</acronym>) path, such as a <acronym>TCP</acronym> connection or a
+shared memory buffer.
+This program is referred to as a client of the window system server.
+More precisely,
+the client is the <acronym>IPC</acronym> path itself.
+A program with multiple paths open to the server is viewed as
+multiple clients by the protocol.
+Resource lifetimes are controlled by
+connection lifetimes, not by program lifetimes.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Clipping_region">
+ <glossterm>Clipping region</glossterm>
+<indexterm significance="preferred"><primary>Clipping region</primary></indexterm>
+ <glossdef>
+ <para>
+In a graphics context,
+a bitmap or list of rectangles can be specified
+to restrict output to a particular region of the window.
+The image defined by the bitmap or rectangles is called a clipping region.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Coded_character">
+ <glossterm>Coded character</glossterm>
+<indexterm significance="preferred"><primary>Coded character</primary></indexterm>
+ <glossdef>
+ <para>
+A character bound to a codepoint.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Coded_character_set">
+ <glossterm>Coded character set</glossterm>
+<indexterm significance="preferred"><primary>Coded character set</primary></indexterm>
+ <glossdef>
+ <para>
+A set of unambiguous rules that establishes a character set
+and the one-to-one relationship between each character of the set
+and its bit representation.
+(ISO2022, as adapted by XPG3)
+A definition of a one-to-one mapping of a set of characters to a set of
+codepoints.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Codepoint">
+ <glossterm>Codepoint</glossterm>
+<indexterm significance="preferred"><primary>Codepoint</primary></indexterm>
+ <glossdef>
+ <para>
+The coded representation of a single character in a coded character set.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Colormap">
+ <glossterm>Colormap</glossterm>
+<indexterm significance="preferred"><primary>Colormap</primary></indexterm>
+ <glossdef>
+ <para>
+A colormap consists of a set of entries defining color values.
+The colormap associated with a window is used to display the contents of
+the window; each pixel value indexes the colormap to produce an <acronym>RGB</acronym> value
+that drives the guns of a monitor.
+Depending on hardware limitations,
+one or more colormaps can be installed at one time so
+that windows associated with those maps display with true colors.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Connection">
+ <glossterm>Connection</glossterm>
+<indexterm significance="preferred"><primary>Connection</primary></indexterm>
+ <glossdef>
+ <para>
+The <acronym>IPC</acronym> path between the server and client program is known as a connection.
+A client program typically (but not necessarily) has one
+connection to the server over which requests and events are sent.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Containment">
+ <glossterm>Containment</glossterm>
+<indexterm significance="preferred"><primary>Containment</primary></indexterm>
+ <glossdef>
+ <para>
+A window contains the pointer if the window is viewable and the
+hotspot of the cursor is within a visible region of the window or a
+visible region of one of its inferiors.
+The border of the window is included as part of the window for containment.
+The pointer is in a window if the window contains the pointer
+but no inferior contains the pointer.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Coordinate_system">
+ <glossterm>Coordinate system</glossterm>
+<indexterm significance="preferred"><primary>Coordinate system</primary></indexterm>
+ <glossdef>
+ <para>
+The coordinate system has X horizontal and Y vertical,
+with the origin [0, 0] at the upper left.
+Coordinates are integral 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>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Cursor">
+ <glossterm>Cursor</glossterm>
+<indexterm significance="preferred"><primary>Cursor</primary></indexterm>
+ <glossdef>
+ <para>
+A cursor is the visible shape of the pointer on a screen.
+It consists of a hotspot, a source bitmap, a shape bitmap,
+and a pair of colors.
+The cursor defined for a window controls the visible
+appearance when the pointer is in that window.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Depth">
+ <glossterm>Depth</glossterm>
+<indexterm significance="preferred"><primary>Depth</primary></indexterm>
+ <glossdef>
+ <para>
+The depth of a window or pixmap is the number of bits per pixel it has.
+The depth of a graphics context is the depth of the drawables it can be
+used in conjunction with graphics output.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Device">
+ <glossterm>Device</glossterm>
+<indexterm significance="preferred"><primary>Device</primary></indexterm>
+ <glossdef>
+ <para>
+Keyboards, mice, tablets, track-balls, button boxes, and so on are all
+collectively known as input devices.
+Pointers can have one or more buttons
+(the most common number is three).
+The core protocol only deals with two devices: the keyboard
+and the pointer.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:DirectColor">
+ <glossterm>DirectColor</glossterm>
+<indexterm significance="preferred"><primary>DirectColor</primary></indexterm>
+ <glossdef>
+ <para>
+<symbol>DirectColor</symbol>
+is a class of colormap in which a pixel value is decomposed into three
+separate subfields for indexing.
+The first subfield indexes an array to produce red intensity values.
+The second subfield indexes a second array to produce blue intensity values.
+The third subfield indexes a third array to produce green intensity values.
+The <acronym>RGB</acronym> (red, green, and blue) values in the colormap entry can be
+changed dynamically.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Display">
+ <glossterm>Display</glossterm>
+<indexterm significance="preferred"><primary>Display</primary></indexterm>
+<indexterm><primary>Display</primary><secondary>structure</secondary></indexterm>
+ <glossdef>
+ <para>
+A server, together with its screens and input devices, is called a display.
+The Xlib
+<type>Display</type>
+structure contains all information about the particular display and its screens
+as well as the state that Xlib needs to communicate with the display over a
+particular connection.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Drawable">
+ <glossterm>Drawable</glossterm>
+<indexterm significance="preferred"><primary>Drawable</primary></indexterm>
+ <glossdef>
+ <para>
+Both windows and pixmaps can be used as sources and destinations
+in graphics operations.
+These windows and pixmaps are collectively known as drawables.
+However, an
+<symbol>InputOnly</symbol>
+window cannot be used as a source or destination in a
+graphics operation.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Encoding">
+ <glossterm>Encoding</glossterm>
+<indexterm significance="preferred"><primary>Encoding</primary></indexterm>
+ <glossdef>
+ <para>
+A set of unambiguous rules that establishes a character set
+and a relationship between the characters and their representations.
+The character set does not have to be fixed to a finite pre-defined set of
+characters.
+The representations do not have to be of uniform length.
+Examples are an ISO2022 graphic set, a state-independent
+or state-dependent combination of graphic sets, possibly including control
+sets, and the X Compound Text encoding.
+</para>
+ <para>
+In X, encodings are identified by a string
+which appears as: the
+<structfield>CharSetRegistry</structfield>
+and
+<structfield>CharSetEncoding</structfield>
+components of an <acronym>XLFD</acronym>
+name; the name of a charset of the locale for which a font could not be
+found; or an atom which identifies the encoding of a text property or
+which names an encoding for a text selection target type.
+Encoding names should be composed of characters from the X Portable
+Character Set.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Escapement">
+ <glossterm>Escapement</glossterm>
+<indexterm significance="preferred"><primary>Escapement</primary></indexterm>
+ <glossdef>
+ <para>
+The escapement of a string is the distance in pixels in the
+primary draw direction from the drawing origin to the origin of the next
+character (that is, the one following the given string) to be drawn.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Event">
+ <glossterm>Event</glossterm>
+<indexterm significance="preferred"><primary>Event</primary></indexterm>
+ <glossdef>
+ <para>
+Clients are informed of information asynchronously by means of events.
+These events can be either asynchronously generated from devices or
+generated as side effects of client requests.
+Events are grouped into types.
+The server never sends an event to a client unless the
+client has specifically asked to be informed of that type of event.
+However, clients can force events to be sent to other clients.
+Events are typically reported relative to a window.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Event_mask">
+ <glossterm>Event mask</glossterm>
+<indexterm significance="preferred"><primary>Event</primary><secondary>mask</secondary></indexterm>
+ <glossdef>
+ <para>
+Events are requested relative to a window.
+The set of event types a client requests relative to a window is described
+by using an event mask.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Event_propagation">
+ <glossterm>Event propagation</glossterm>
+<indexterm significance="preferred"><primary>Event</primary><secondary>propagation</secondary></indexterm>
+ <glossdef>
+ <para>
+Device-related events propagate from the source window to ancestor
+windows until some client has expressed interest in handling that type
+of event or until the event is discarded explicitly.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Event_source">
+ <glossterm>Event source</glossterm>
+<indexterm significance="preferred"><primary>Event</primary><secondary>source</secondary></indexterm>
+ <glossdef>
+ <para>
+The deepest viewable window that the pointer is in is called
+the source of a device-related event.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Event_synchronization">
+ <glossterm>Event synchronization</glossterm>
+<indexterm significance="preferred"><primary>Event</primary><secondary>synchronization</secondary></indexterm>
+ <glossdef>
+ <para>
+There are certain race conditions possible when demultiplexing device
+events to clients (in particular, deciding where pointer and keyboard
+events should be sent when in the middle of window management
+operations).
+The event synchronization mechanism allows synchronous processing of
+device events.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Exposure_event">
+ <glossterm>Exposure event</glossterm>
+<indexterm significance="preferred"><primary>Event</primary><secondary>Exposure</secondary></indexterm>
+ <glossdef>
+ <para>
+Servers do not guarantee to preserve the contents of windows when
+windows are obscured or reconfigured.
+Exposure events are sent to clients to inform them when contents of regions
+of windows have been lost.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Extension">
+ <glossterm>Extension</glossterm>
+<indexterm significance="preferred"><primary>Extension</primary></indexterm>
+ <glossdef>
+ <para>
+Named extensions to the core protocol can be defined to extend the system.
+Extensions to output requests, resources, and event types are all possible
+and expected.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Font">
+ <glossterm>Font</glossterm>
+<indexterm significance="preferred"><primary>Font</primary></indexterm>
+ <glossdef>
+ <para>
+A font is an array of glyphs (typically characters).
+The protocol does no translation or interpretation of character sets.
+The client simply indicates values used to index the glyph array.
+A font contains additional metric information to determine interglyph
+and interline spacing.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Font_glyph">
+ <glossterm>Font glyph</glossterm>
+<indexterm significance="preferred"><primary>Font glyph</primary></indexterm>
+ <glossdef>
+ <para>
+The abstract graphical symbol for an index into a font.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Frozen_events">
+ <glossterm>Frozen events</glossterm>
+<indexterm significance="preferred"><primary>Frozen events</primary></indexterm>
+ <glossdef>
+ <para>
+Clients can freeze event processing during keyboard and pointer grabs.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:GC">
+ <glossterm>GC</glossterm>
+<indexterm significance="preferred"><primary>GC</primary></indexterm>
+ <glossdef>
+ <para>
+GC is an abbreviation for graphics context.
+See <glossterm linkend="glossary:Graphics_context">Graphics context</glossterm>.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Glyph">
+ <glossterm>Glyph</glossterm>
+<indexterm significance="preferred"><primary>Glyph</primary></indexterm>
+ <glossdef>
+ <para>
+An identified abstract graphical symbol independent of any actual image.
+(ISO/IEC/DIS 9541-1)
+An abstract visual representation of a graphic character,
+not bound to a codepoint.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Glyph_image">
+ <glossterm>Glyph image</glossterm>
+<indexterm significance="preferred"><primary>Glyph image</primary></indexterm>
+ <glossdef>
+ <para>
+An image of a glyph, as obtained from a glyph representation displayed
+on a presentation surface.
+(ISO/IEC/DIS 9541-1)
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Grab">
+ <glossterm>Grab</glossterm>
+<indexterm significance="preferred"><primary>Grab</primary></indexterm>
+ <glossdef>
+ <para>
+Keyboard keys, the keyboard, pointer buttons, the pointer,
+and the server can be grabbed for exclusive use by a client.
+In general,
+these facilities are not intended to be used by normal applications
+but are intended for various input and window managers to implement various
+styles of user interfaces.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Graphics_context">
+ <glossterm>Graphics context</glossterm>
+<indexterm significance="preferred"><primary>Graphics context</primary></indexterm>
+ <glossdef>
+ <para>
+Various information for graphics output is stored in a graphics
+context (<acronym>GC</acronym>), such as foreground pixel, background
+pixel, line width, clipping region, and so on.
+A graphics context can only
+be used with drawables that have the same root and the same depth as
+the graphics context.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Gravity">
+ <glossterm>Gravity</glossterm>
+<indexterm significance="preferred"><primary>Gravity</primary></indexterm>
+ <glossdef>
+ <para>
+The contents of windows and windows themselves have a gravity,
+which determines how the contents move when a window is resized.
+See <glossterm linkend="glossary:Bit_gravity">Bit gravity</glossterm> and
+<glossterm linkend="glossary:Window_gravity">Window gravity</glossterm>.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:GrayScale">
+ <glossterm>GrayScale</glossterm>
+<indexterm significance="preferred"><primary>GrayScale</primary></indexterm>
+ <glossdef>
+ <para>
+<symbol>GrayScale</symbol>
+can be viewed as a degenerate case of
+<glossterm linkend="glossary:PseudoColor"><symbol>PseudoColor</symbol></glossterm>,
+in which the red, green, and blue values in any given colormap entry
+are equal and thus, produce shades of gray.
+The gray values can be changed dynamically.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Host_Portable_Character_Encoding">
+ <glossterm>Host Portable Character Encoding</glossterm>
+<indexterm significance="preferred"><primary>Host Portable Character Encoding</primary></indexterm>
+ <glossdef>
+ <para>
+The encoding of the <glossterm linkend="glossary:X_Portable_Character_Set">X Portable Character Set</glossterm> on the host.
+The encoding itself is not defined by this standard,
+but the encoding must be the same in all locales supported by Xlib on the host.
+If a string is said to be in the Host Portable Character Encoding,
+then it only contains characters from the X Portable Character Set,
+in the host encoding.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Hotspot">
+ <glossterm>Hotspot</glossterm>
+<indexterm significance="preferred"><primary>Hotspot</primary></indexterm>
+ <glossdef>
+ <para>
+A cursor has an associated hotspot, which defines the point in the
+cursor corresponding to the coordinates reported for the pointer.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Identifier">
+ <glossterm>Identifier</glossterm>
+<indexterm significance="preferred"><primary>Identifier</primary></indexterm>
+ <glossdef>
+ <para>
+An identifier is a unique value associated with a resource
+that clients use to name that resource.
+The identifier can be used over any connection to name the resource.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Inferiors">
+ <glossterm>Inferiors</glossterm>
+<indexterm significance="preferred"><primary>Inferiors</primary></indexterm>
+ <glossdef>
+ <para>
+The inferiors of a window are all of the subwindows nested below it:
+the children, the children's children, and so on.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Input_focus">
+ <glossterm>Input focus</glossterm>
+<indexterm significance="preferred"><primary>Input</primary><secondary>focus</secondary></indexterm>
+ <glossdef>
+ <para>
+The input focus is usually a window defining the scope for processing
+of keyboard input.
+If a generated keyboard event usually would be reported to this window
+or one of its inferiors,
+the event is reported as usual.
+Otherwise, the event is reported with respect to the focus window.
+The input focus also can be set such that all keyboard events are discarded
+and such that the focus window is dynamically taken to be the root window
+of whatever screen the pointer is on at each keyboard event.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Input_manager">
+ <glossterm>Input manager</glossterm>
+<indexterm significance="preferred"><primary>Input</primary><secondary>manager</secondary></indexterm>
+ <glossdef>
+ <para>
+Control over keyboard input is typically provided by an input manager
+client, which usually is part of a window manager.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:InputOnly_window">
+ <glossterm>InputOnly window</glossterm>
+<indexterm significance="preferred"><primary>Window</primary><secondary>InputOnly</secondary></indexterm>
+ <glossdef>
+ <para>
+An
+<symbol>InputOnly</symbol>
+window is a window that cannot be used for graphics requests.
+<symbol>InputOnly</symbol>
+windows are invisible and are used to control such things as cursors,
+input event generation, and grabbing.
+<symbol>InputOnly</symbol>
+windows cannot have
+<symbol>InputOutput</symbol>
+windows as inferiors.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:InputOutput_window">
+ <glossterm>InputOutput window</glossterm>
+<indexterm significance="preferred"><primary>Window</primary><secondary>InputOutput</secondary></indexterm>
+ <glossdef>
+ <para>
+An
+<symbol>InputOutput</symbol>
+window is the normal kind of window that is used for both input and output.
+<symbol>InputOutput</symbol>
+windows can have both
+<symbol>InputOutput</symbol>
+and
+<symbol>InputOnly</symbol>
+windows as inferiors.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Internationalization">
+ <glossterm>Internationalization</glossterm>
+<indexterm significance="preferred"><primary>Internationalization</primary></indexterm>
+ <glossdef>
+ <para>
+The process of making software adaptable to the requirements
+of different native languages, local customs, and character string encodings.
+Making a computer program adaptable to different locales
+without program source modifications or recompilation.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:ISO2022">
+ <glossterm>ISO2022</glossterm>
+<indexterm significance="preferred"><primary>ISO2022</primary></indexterm>
+ <glossdef>
+ <para>
+ISO standard for code extension techniques for 7-bit and 8-bit coded
+character sets.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Key_grabbing">
+ <glossterm>Key grabbing</glossterm>
+<indexterm significance="preferred"><primary>Key</primary><secondary>grabbing</secondary></indexterm>
+ <glossdef>
+ <para>
+Keys on the keyboard can be passively grabbed by a client.
+When the key is pressed,
+the keyboard is then actively grabbed by the client.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Keyboard_grabbing">
+ <glossterm>Keyboard grabbing</glossterm>
+<indexterm significance="preferred"><primary>Keyboard</primary><secondary>grabbing</secondary></indexterm>
+ <glossdef>
+ <para>
+A client can actively grab control of the keyboard, and key events
+will be sent to that client rather than the client the events would
+normally have been sent to.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Keysym">
+ <glossterm>Keysym</glossterm>
+<indexterm significance="preferred"><primary>Keysym</primary></indexterm>
+ <glossdef>
+ <para>
+An encoding of a symbol on a keycap on a keyboard.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Latin-1">
+ <glossterm>Latin-1</glossterm>
+<indexterm significance="preferred"><primary>Latin-1</primary></indexterm>
+ <glossdef>
+ <para>
+The coded character set defined by the ISO8859-1 standard.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Latin_Portable_Character_Encoding">
+ <glossterm>Latin Portable Character Encoding</glossterm>
+<indexterm significance="preferred"><primary>Latin Portable Character Encoding</primary></indexterm>
+ <glossdef>
+ <para>
+The encoding of the X Portable Character Set using the Latin-1 codepoints
+plus ASCII control characters.
+If a string is said to be in the Latin Portable Character Encoding,
+then it only contains characters from the X Portable Character Set,
+not all of Latin-1.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Locale">
+ <glossterm>Locale</glossterm>
+<indexterm significance="preferred"><primary>Locale</primary></indexterm>
+ <glossdef>
+ <para>
+The international environment of a computer program defining the ``localized''
+behavior of that program at run-time.
+This information can be established from one or more sets of localization data.
+ANSI C defines locale-specific processing by C system library calls.
+See ANSI C and the X/Open Portability Guide specifications for more details.
+In this specification, on implementations that conform to the ANSI C library,
+the ``current locale'' is the current setting of the LC_CTYPE
+<function>setlocale</function>
+category.
+Associated with each locale is a text encoding. When text is processed
+in the context of a locale, the text must be in the encoding of the locale.
+The current locale affects Xlib in its:
+ <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>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Locale_name">
+ <glossterm>Locale name</glossterm>
+<indexterm significance="preferred"><primary>Locale name</primary></indexterm>
+ <glossdef>
+ <para>
+The identifier used to select the desired locale for the host C library
+and X library functions.
+On ANSI C library compliant systems,
+the locale argument to the
+<function>setlocale</function>
+function.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Localization">
+ <glossterm>Localization</glossterm>
+<indexterm significance="preferred"><primary>Localization</primary></indexterm>
+ <glossdef>
+ <para>
+The process of establishing information within a computer system specific
+to the operation of particular native languages, local customs
+and coded character sets.
+(XPG3)
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Mapped">
+ <glossterm>Mapped</glossterm>
+<indexterm significance="preferred"><primary>Mapped window</primary></indexterm>
+ <glossdef>
+ <para>
+A window is said to be mapped if a map call has been performed on it.
+Unmapped windows and their inferiors are never viewable or visible.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Modifier_keys">
+ <glossterm>Modifier keys</glossterm>
+<indexterm significance="preferred"><primary>Modifier keys</primary></indexterm>
+ <glossdef>
+ <para>
+Shift, Control, Meta, Super, Hyper, Alt, Compose, Apple, CapsLock,
+ShiftLock, and similar keys are called modifier keys.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Monochrome">
+ <glossterm>Monochrome</glossterm>
+<indexterm significance="preferred"><primary>Monochrome</primary></indexterm>
+ <glossdef>
+ <para>
+Monochrome is a special case of
+<glossterm linkend="glossary:StaticGray"><symbol>StaticGray</symbol></glossterm>
+in which there are only two colormap entries.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Multibyte">
+ <glossterm>Multibyte</glossterm>
+<indexterm significance="preferred"><primary>Multibyte</primary></indexterm>
+ <glossdef>
+ <para>
+A character whose codepoint is stored in more than one byte;
+any encoding which can contain multibyte characters;
+text in a multibyte encoding.
+The ``<type>char *</type>'' null-terminated string datatype in ANSI C.
+Note that references in this document to multibyte strings
+imply only that the strings <emphasis remap='I'>may</emphasis> contain multibyte characters.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Obscure">
+ <glossterm>Obscure</glossterm>
+<indexterm significance="preferred"><primary>Obscure</primary></indexterm>
+ <glossdef>
+ <para>
+A window is obscured if some other window obscures it.
+A window can be partially obscured and so still have visible regions.
+Window A obscures window B if both are viewable
+<symbol>InputOutput</symbol>
+windows, if A is higher in the global stacking order,
+and if the rectangle defined by the outside
+edges of A intersects the rectangle defined by the outside edges of B.
+Note the distinction between obscures and occludes.
+Also note that window borders are included in the calculation.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Occlude">
+ <glossterm>Occlude</glossterm>
+<indexterm significance="preferred"><primary>Occlude</primary></indexterm>
+ <glossdef>
+ <para>
+A window is occluded if some other window occludes it.
+Window A occludes window B if both are mapped,
+if A is higher in the global stacking order,
+and if the rectangle defined by the outside edges of A intersects the rectangle defined
+by the outside edges of B.
+Note the distinction between occludes and obscures.
+Also note that window borders are included in the calculation
+and that
+<symbol>InputOnly</symbol>
+windows never obscure other windows but can occlude other windows.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Padding">
+ <glossterm>Padding</glossterm>
+<indexterm significance="preferred"><primary>Padding</primary></indexterm>
+ <glossdef>
+ <para>
+Some padding bytes are inserted in the data stream to maintain
+alignment of the protocol requests on natural boundaries.
+This increases ease of portability to some machine architectures.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Parent_window">
+ <glossterm>Parent window</glossterm>
+<indexterm significance="preferred"><primary>Window</primary><secondary>parent</secondary></indexterm>
+ <glossdef>
+ <para>
+If C is a child of P, then P is the parent of C.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Passive_grab">
+ <glossterm>Passive grab</glossterm>
+<indexterm significance="preferred"><primary>Passive grab</primary></indexterm>
+ <glossdef>
+ <para>
+Grabbing a key or button is a passive grab.
+The grab activates when the key or button is actually pressed.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Pixel_value">
+ <glossterm>Pixel value</glossterm>
+<indexterm significance="preferred"><primary>Pixel value</primary></indexterm>
+ <glossdef>
+ <para>
+A pixel is an N-bit value,
+where N is the number of bit planes used in a particular window or pixmap
+(that is, is the depth of the window or pixmap).
+A pixel in a window indexes a colormap to derive an actual color to be
+displayed.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Pixmap">
+ <glossterm>Pixmap</glossterm>
+<indexterm significance="preferred"><primary>Pixmap</primary></indexterm>
+ <glossdef>
+ <para>
+A pixmap is a three-dimensional array of bits.
+A pixmap is normally thought of as a two-dimensional array of pixels,
+where each pixel can be a value from 0 to 2<superscript>N</superscript>-1,
+and where N is the depth (z axis) of the pixmap.
+A pixmap can also be thought of as a stack of N bitmaps.
+A pixmap can only be used on the screen that it was created in.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Plane">
+ <glossterm>Plane</glossterm>
+<indexterm significance="preferred"><primary>Plane</primary></indexterm>
+ <glossdef>
+ <para>
+When a pixmap or window is thought of as a stack of bitmaps, each
+bitmap is called a plane or bit plane.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Plane_mask">
+ <glossterm>Plane mask</glossterm>
+<indexterm significance="preferred"><primary>Plane</primary><secondary>mask</secondary></indexterm>
+ <glossdef>
+ <para>
+Graphics operations can be restricted to only affect a subset of bit
+planes of a destination.
+A plane mask is a bit mask describing which planes are to be modified.
+The plane mask is stored in a graphics context.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Pointer">
+ <glossterm>Pointer</glossterm>
+<indexterm significance="preferred"><primary>Pointer</primary></indexterm>
+ <glossdef>
+ <para>
+The pointer is the pointing device currently attached to the cursor
+and tracked on the screens.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Pointer_grabbing">
+ <glossterm>Pointer grabbing</glossterm>
+<indexterm significance="preferred"><primary>Pointer</primary><secondary>grabbing</secondary></indexterm>
+ <glossdef>
+ <para>
+A client can actively grab control of the pointer.
+Then button and motion events will be sent to that client
+rather than the client the events would normally have been sent to.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Pointing_device">
+ <glossterm>Pointing device</glossterm>
+<indexterm significance="preferred"><primary>Pointing device</primary></indexterm>
+ <glossdef>
+ <para>
+A pointing device is typically a mouse, tablet, or some other
+device with effective dimensional motion.
+The core protocol defines only one visible cursor,
+which tracks whatever pointing device is attached as the pointer.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:POSIX">
+ <glossterm><acronym>POSIX</acronym></glossterm>
+<indexterm significance="preferred"><primary><acronym>POSIX</acronym></primary></indexterm>
+ <glossdef>
+ <para>
+Portable Operating System Interface, ISO/IEC 9945-1 (IEEE Std 1003.1).
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:POSIX_Portable_Filename_Character_Set">
+ <glossterm><acronym>POSIX</acronym> Portable Filename Character Set</glossterm>
+<indexterm significance="preferred"><primary><acronym>POSIX</acronym> Portable Filename Character Set</primary></indexterm>
+ <glossdef>
+ <para>
+The set of 65 characters which can be used in naming files on a <acronym>POSIX</acronym>-compliant
+host that are correctly processed in all locales.
+The set is:
+</para>
+ <para>
+<!-- .Ds 0 -->
+a..z A..Z 0..9 ._-
+<!-- .De -->
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Property">
+ <glossterm>Property</glossterm>
+<indexterm significance="preferred"><primary>Property</primary></indexterm>
+ <glossdef>
+ <para>
+Windows can have associated properties that consist of a name, a type,
+a data format, and some data.
+The protocol places no interpretation on properties.
+They are intended as a general-purpose naming mechanism for clients.
+For example, clients might use properties to share information such as resize
+hints, program names, and icon formats with a window manager.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Property_list">
+ <glossterm>Property list</glossterm>
+<indexterm significance="preferred"><primary>Property list</primary></indexterm>
+ <glossdef>
+ <para>
+The property list of a window is the list of properties that have
+been defined for the window.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:PseudoColor">
+ <glossterm>PseudoColor</glossterm>
+<indexterm significance="preferred"><primary>PseudoColor</primary></indexterm>
+ <glossdef>
+ <para>
+<symbol>PseudoColor</symbol>
+is a class of colormap in which a pixel value indexes the colormap entry to
+produce an independent <acronym>RGB</acronym> value;
+that is, the colormap is viewed as an array of triples (<acronym>RGB</acronym> values).
+The <acronym>RGB</acronym> values can be changed dynamically.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Rectangle">
+ <glossterm>Rectangle</glossterm>
+<indexterm significance="preferred"><primary>Rectangle</primary></indexterm>
+ <glossdef>
+ <para>
+A rectangle specified by [x,y,w,h] has an infinitely thin
+outline path with corners at [x,y], [x+w,y], [x+w,y+h], and [x, y+h].
+When a rectangle is filled,
+the lower-right edges are not drawn.
+For example,
+if w=h=0,
+nothing would be drawn.
+For w=h=1,
+a single pixel would be drawn.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Redirecting_control">
+ <glossterm>Redirecting control</glossterm>
+<indexterm significance="preferred"><primary>Redirecting control</primary></indexterm>
+ <glossdef>
+ <para>
+Window managers (or client programs) may enforce window layout
+policy in various ways.
+When a client attempts to change the size or position of a window,
+the operation may be redirected to a specified client
+rather than the operation actually being performed.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Reply">
+ <glossterm>Reply</glossterm>
+<indexterm significance="preferred"><primary>Reply</primary></indexterm>
+ <glossdef>
+ <para>
+Information requested by a client program using the X protocol
+is sent back to the client with a reply.
+Both events and replies are multiplexed on the same connection.
+Most requests do not generate replies,
+but some requests generate multiple replies.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Request">
+ <glossterm>Request</glossterm>
+<indexterm significance="preferred"><primary>Request</primary></indexterm>
+ <glossdef>
+ <para>
+A command to the server is called a request.
+It is a single block of data sent over a connection.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Resource">
+ <glossterm>Resource</glossterm>
+<indexterm significance="preferred"><primary>Resource</primary></indexterm>
+ <glossdef>
+ <para>
+Windows, pixmaps, cursors, fonts, graphics contexts, and colormaps are
+known as resources.
+They all have unique identifiers associated with them for naming purposes.
+The lifetime of a resource usually is bounded by the lifetime of the
+connection over which the resource was created.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:RGB_values">
+ <glossterm><acronym>RGB</acronym> values</glossterm>
+<indexterm significance="preferred"><primary><acronym>RGB</acronym> values</primary></indexterm>
+ <glossdef>
+ <para>
+<acronym>RGB</acronym> values are the red, green, and blue intensity values that are used
+to define a color.
+These values are always represented as 16-bit, unsigned numbers, with 0
+the minimum intensity and 65535 the maximum intensity.
+The X server scales these values to match the display hardware.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Root">
+ <glossterm>Root</glossterm>
+<indexterm significance="preferred"><primary>Root</primary></indexterm>
+ <glossdef>
+ <para>
+The root of a pixmap or graphics context is the same as the root
+of whatever drawable was used when the pixmap or GC was created.
+The root of a window is the root window under which the window was created.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Root_window">
+ <glossterm>Root window</glossterm>
+<indexterm significance="preferred"><primary>Window</primary><secondary>root</secondary></indexterm>
+ <glossdef>
+ <para>
+Each screen has a root window covering it.
+The root window cannot be reconfigured or unmapped,
+but otherwise it acts as a full-fledged window.
+A root window has no parent.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Save_set">
+ <glossterm>Save set</glossterm>
+<indexterm significance="preferred"><primary>Save set</primary></indexterm>
+ <glossdef>
+ <para>
+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 that should be remapped
+if currently unmapped.
+Save sets are typically used by window managers to avoid
+lost windows if the manager should terminate abnormally.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Scanline">
+ <glossterm>Scanline</glossterm>
+<indexterm significance="preferred"><primary>Scanline</primary></indexterm>
+ <glossdef>
+ <para>
+A scanline is a list of pixel or bit values viewed as a horizontal
+row (all values having the same y coordinate) of an image, with the
+values ordered by increasing the x coordinate.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Scanline_order">
+ <glossterm>Scanline order</glossterm>
+<indexterm significance="preferred"><primary>Scanline</primary><secondary>order</secondary></indexterm>
+ <glossdef>
+ <para>
+An image represented in scanline order contains scanlines ordered by
+increasing the y coordinate.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Screen">
+ <glossterm>Screen</glossterm>
+<indexterm significance="preferred"><primary>Screen</primary></indexterm>
+<indexterm><primary>Screen</primary><secondary>structure</secondary></indexterm>
+<indexterm><primary>Display</primary><secondary>structure</secondary></indexterm>
+ <glossdef>
+ <para>
+A server can provide several independent screens,
+which typically have physically independent monitors.
+This would be the expected configuration when there is only a single keyboard
+and pointer shared among the screens.
+A
+<type>Screen</type>
+structure contains the information about that screen
+and is linked to the
+<type>Display</type>
+structure.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Selection">
+ <glossterm>Selection</glossterm>
+<indexterm significance="preferred"><primary>Selection</primary></indexterm>
+ <glossdef>
+ <para>
+A selection can be thought of as an indirect property with dynamic
+type.
+That is, rather than having the property stored in the X server,
+it is maintained by some client (the owner).
+A selection is global and is thought of as belonging to the user
+and being maintained by clients,
+rather than being private to a particular window subhierarchy
+or a particular set of clients.
+When a client asks for the contents of
+a selection, it specifies a selection target type,
+which can be used to control the transmitted representation of the contents.
+For example, if the selection is ``the last thing the user clicked on,''
+and that is currently an image, then the target type might specify
+whether the contents of the image should be sent in XY format or
+Z format.
+</para>
+ <para>
+The target type can also be used to control the class of
+contents transmitted; for example,
+asking for the ``looks'' (fonts, line
+spacing, indentation, and so forth) of a paragraph selection, rather than the
+text of the paragraph.
+The target type can also be used for other
+purposes.
+The protocol does not constrain the semantics.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Server">
+ <glossterm>Server</glossterm>
+<indexterm significance="preferred"><primary>Server</primary></indexterm>
+ <glossdef>
+ <para>
+The server, which is also referred to as the X server,
+provides the basic windowing mechanism.
+It handles <acronym>IPC</acronym> connections from clients,
+multiplexes graphics requests onto the screens,
+and demultiplexes input back to the appropriate clients.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Server_grabbing">
+ <glossterm>Server grabbing</glossterm>
+<indexterm significance="preferred"><primary>Server</primary><secondary>grabbing</secondary></indexterm>
+ <glossdef>
+ <para>
+The server can be grabbed by a single client for exclusive use.
+This prevents processing of any requests from other client connections until
+the grab is completed.
+This is typically only a transient state for such things as rubber-banding,
+pop-up menus, or executing requests indivisibly.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Shift_sequence">
+ <glossterm>Shift sequence</glossterm>
+<indexterm significance="preferred"><primary>Shift sequence</primary></indexterm>
+ <glossdef>
+ <para>
+ISO2022 defines control characters and escape sequences
+which temporarily (single shift) or permanently (locking shift) cause a
+different character set to be in effect (``invoking'' a character set).
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Sibling">
+ <glossterm>Sibling</glossterm>
+<indexterm significance="preferred"><primary>Sibling</primary></indexterm>
+ <glossdef>
+ <para>
+Children of the same parent window are known as sibling windows.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Stacking_order">
+ <glossterm>Stacking order</glossterm>
+<indexterm significance="preferred"><primary>Stacking order</primary></indexterm>
+ <glossdef>
+ <para>
+Sibling windows, similar to sheets of paper on a desk,
+can stack on top of each other.
+Windows above both obscure and occlude lower windows.
+The relationship between sibling windows is known as the stacking order.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:State-dependent_encoding">
+ <glossterm>State-dependent encoding</glossterm>
+<indexterm significance="preferred"><primary>State-dependent encoding</primary></indexterm>
+ <glossdef>
+ <para>
+An encoding in which an invocation of a charset can apply to multiple
+characters in sequence.
+A state-dependent encoding begins in an ``initial state''
+and enters other ``shift states'' when specific ``shift sequences''
+are encountered in the byte sequence.
+In ISO2022 terms,
+this means use of locking shifts, not single shifts.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:State-independent_encoding">
+ <glossterm>State-independent encoding</glossterm>
+<indexterm significance="preferred"><primary>State-independent encoding</primary></indexterm>
+ <glossdef>
+ <para>
+Any encoding in which the invocations of the charsets are fixed,
+or span only a single character.
+In ISO2022 terms,
+this means use of at most single shifts, not locking shifts.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:StaticColor">
+ <glossterm>StaticColor</glossterm>
+<indexterm significance="preferred"><primary>StaticColor</primary></indexterm>
+ <glossdef>
+ <para>
+<symbol>StaticColor</symbol>
+can be viewed as a degenerate case of
+<glossterm linkend="glossary:PseudoColor"><symbol>PseudoColor</symbol></glossterm>
+in which the <acronym>RGB</acronym> values are predefined and read-only.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:StaticGray">
+ <glossterm>StaticGray</glossterm>
+<indexterm significance="preferred"><primary>StaticGray</primary></indexterm>
+ <glossdef>
+ <para>
+<symbol>StaticGray</symbol>
+can be viewed as a degenerate case of
+<glossterm linkend="glossary:GrayScale"><symbol>GrayScale</symbol></glossterm>
+in which the gray values are predefined and read-only.
+The values are typically linear or near-linear increasing ramps.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Status">
+ <glossterm>Status</glossterm>
+<indexterm significance="preferred"><primary>Status</primary></indexterm>
+ <glossdef>
+ <para>
+Many Xlib functions return a success status.
+If the function does not succeed,
+however, its arguments are not disturbed.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Stipple">
+ <glossterm>Stipple</glossterm>
+<indexterm significance="preferred"><primary>Stipple</primary></indexterm>
+ <glossdef>
+ <para>
+A stipple pattern is a bitmap that is used to tile a region to serve
+as an additional clip mask for a fill operation with the foreground
+color.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:STRING_encoding">
+ <glossterm>STRING encoding</glossterm>
+ <glossdef>
+ <para>
+<glossterm linkend="glossary:Latin-1">Latin-1</glossterm>, plus tab and newline.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:String_Equivalence">
+ <glossterm>String Equivalence</glossterm>
+<indexterm significance="preferred"><primary>String Equivalence</primary></indexterm>
+ <glossdef>
+ <para>
+Two ISO Latin-1 STRING8 values are considered equal if they are the same
+length and if corresponding bytes are either equal or are equivalent as
+follows: decimal values 65 to 90 inclusive (characters ``A'' to ``Z'') are
+pairwise equivalent to decimal values 97 to 122 inclusive
+(characters ``a'' to ``z''), decimal values 192 to 214 inclusive
+(characters ``A grave'' to ``O diaeresis'') are pairwise equivalent to decimal
+values 224 to 246 inclusive (characters ``a grave'' to ``o diaeresis''),
+and decimal values 216 to 222 inclusive (characters ``O oblique'' to ``THORN'')
+are pairwise equivalent to decimal values 246 to 254 inclusive
+(characters ``o oblique'' to ``thorn'').
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Tile">
+ <glossterm>Tile</glossterm>
+<indexterm significance="preferred"><primary>Tile</primary></indexterm>
+ <glossdef>
+ <para>
+A pixmap can be replicated in two dimensions to tile a region.
+The pixmap itself is also known as a tile.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Timestamp">
+ <glossterm>Timestamp</glossterm>
+<indexterm significance="preferred"><primary>Timestamp</primary></indexterm>
+ <glossdef>
+ <para>
+A timestamp is a time value expressed in milliseconds.
+It is typically 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 earlier in time than T
+and half of the timestamp space as being later in time than T.
+One timestamp value, represented by the constant
+<symbol>CurrentTime</symbol>,
+is never generated by the server.
+This value is reserved for use in requests to represent the current server time.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:TrueColor">
+ <glossterm>TrueColor</glossterm>
+<indexterm significance="preferred"><primary>TrueColor</primary></indexterm>
+ <glossdef>
+ <para>
+<symbol>TrueColor</symbol>
+can be viewed as a degenerate case of
+<glossterm linkend="glossary:DirectColor"><symbol>DirectColor</symbol></glossterm>
+in which the subfields in the pixel value directly encode the corresponding <acronym>RGB</acronym>
+values.
+That is, the colormap has predefined read-only <acronym>RGB</acronym> values.
+The values are typically linear or near-linear increasing ramps.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Type">
+ <glossterm>Type</glossterm>
+<indexterm significance="preferred"><primary>Type</primary></indexterm>
+ <glossdef>
+ <para>
+A type is an arbitrary atom used to identify the interpretation of property
+data.
+Types are completely uninterpreted by the server.
+They are solely for the benefit of clients.
+X predefines type atoms for many frequently used types,
+and clients also can define new types.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Viewable">
+ <glossterm>Viewable</glossterm>
+<indexterm significance="preferred"><primary>Viewable</primary></indexterm>
+ <glossdef>
+ <para>
+A window is viewable if it and all of its ancestors are mapped.
+This does not imply that any portion of the window is actually visible.
+Graphics requests can be performed on a window when it is not
+viewable, but output will not be retained unless the server is maintaining
+backing store.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Visible">
+ <glossterm>Visible</glossterm>
+<indexterm significance="preferred"><primary>Visible</primary></indexterm>
+ <glossdef>
+ <para>
+A region of a window is visible if someone looking at the screen can
+actually see it; that is, the window is viewable and the region is not occluded
+by any other window.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Whitespace">
+ <glossterm>Whitespace</glossterm>
+<indexterm significance="preferred"><primary>Whitespace</primary></indexterm>
+ <glossdef>
+ <para>
+Any spacing character.
+On implementations that conform to the ANSI C library,
+whitespace is any character for which
+<function>isspace</function>
+returns true.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Window_gravity">
+ <glossterm>Window gravity</glossterm>
+<indexterm significance="preferred"><primary>Window</primary><secondary>gravity</secondary></indexterm>
+ <glossdef>
+ <para>
+When windows are resized,
+subwindows may be repositioned automatically relative to some position in the
+window.
+This attraction of a subwindow to some part of its parent is known
+as window gravity.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Window_manager">
+ <glossterm>Window manager</glossterm>
+<indexterm significance="preferred"><primary>Window</primary><secondary>manager</secondary></indexterm>
+ <glossdef>
+ <para>
+Manipulation of windows on the screen and much of the user interface
+(policy) is typically provided by a window manager client.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:X_Portable_Character_Set">
+ <glossterm>X Portable Character Set</glossterm>
+<indexterm significance="preferred"><primary>X Portable Character Set</primary></indexterm>
+ <glossdef>
+ <para>
+A basic set of 97 characters which are assumed to exist in all
+locales supported by Xlib. This set contains the following characters:
+ <literallayout>
+a..z A..Z 0..9
+!"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~
+<space>, <tab>, and <newline>
+ </literallayout>
+ </para>
+ <para>
+This is the left/lower half (also called the G0 set)
+of the graphic character set of ISO8859-1 plus <space>, <tab>, and <newline>.
+It is also the set of graphic characters in 7-bit ASCII plus the same
+three control characters.
+The actual encoding of these characters on the host is system dependent;
+see the <glossterm linkend="glossary:Host_Portable_Character_Encoding">Host Portable Character Encoding</glossterm>.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:XLFD">
+ <glossterm><acronym>XLFD</acronym></glossterm>
+<indexterm significance="preferred"><primary><acronym>XLFD</acronym></primary></indexterm>
+ <glossdef>
+ <para>
+The <citetitle>X Logical Font Description Conventions</citetitle>
+that define a standard syntax for structured font names.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:XY_format">
+ <glossterm>XY format</glossterm>
+<indexterm significance="preferred"><primary>XY format</primary></indexterm>
+ <glossdef>
+ <para>
+The data for a pixmap is said to be in XY format if it is organized as
+a set of bitmaps representing individual bit planes with the planes
+appearing from most-significant to least-significant bit order.
+ </para>
+ </glossdef>
+</glossentry>
+<glossentry id="glossary:Z_format">
+ <glossterm>Z format</glossterm>
+<indexterm significance="preferred"><primary>Z format</primary></indexterm>
+ <glossdef>
+ <para>
+The data for a pixmap is said to be in Z format if it is organized as
+a set of pixel values in scanline order.
+ </para>
+ </glossdef>
+</glossentry>
+
+<bibliography>
+<title>References</title>
+<biblioentry>
+<title>Draft Proposed Multibyte Extension of ANSI C, Draft 1.1</title>
+<date>November 30, 1989 SC22/C WG/SWG IPSJ/ITSCJ Japan</date>
+</biblioentry>
+
+<biblioentry>
+<title>ISO2022: Information processing - ISO 7-bit and 8-bit coded character
+sets - Code extension techniques.</title>
+</biblioentry>
+
+<biblioentry>
+<title>ISO8859-1: Information processing - 8-bit single-byte coded graphic
+character sets - Part 1: Latin alphabet No. 1.</title>
+</biblioentry>
+
+<biblioentry>
+<title><acronym>POSIX</acronym>: Information Technology - Portable Operating System Interface (<acronym>POSIX</acronym>) -
+Part 1: System Application Program Interface (API) [C Language],
+ISO/IEC 9945-1.</title>
+</biblioentry>
+
+<biblioentry>
+<title>Text of ISO/IEC/DIS 9541-1, Information Processing - Font Information
+Interchange - Part 1: Architecture.</title>
+</biblioentry>
+
+<biblioentry>
+<title>X/Open Portability Guide, Issue 3, December 1988 (XPG3), X/Open Company,
+Ltd, Prentice-Hall, Inc. 1989. ISBN 0-13-685835-8.
+(See especially Volume 3: XSI Supplementary Definitions.)</title>
+</biblioentry>
+</bibliography>
+
+</glossary>
Index: create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/libX11
===================================================================
--- create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/libX11 (nonexistent)
+++ create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/libX11 (revision 5)
Property changes on: create-1.8.3-docbook-patch/libX11-1.8.3-new/specs/libX11
___________________________________________________________________
Added: svn:ignore
## -0,0 +1,73 ##
+
+# install dir
+dist
+
+# Target build dirs
+.a1x-newlib
+.a2x-newlib
+.at91sam7s-newlib
+
+.build-machine
+
+.a1x-glibc
+.a2x-glibc
+.h3-glibc
+.h5-glibc
+.i586-glibc
+.i686-glibc
+.imx6-glibc
+.jz47xx-glibc
+.makefile
+.am335x-glibc
+.omap543x-glibc
+.p5600-glibc
+.power8-glibc
+.power8le-glibc
+.power9-glibc
+.power9le-glibc
+.m1000-glibc
+.riscv64-glibc
+.rk328x-glibc
+.rk33xx-glibc
+.rk339x-glibc
+.s8xx-glibc
+.s9xx-glibc
+.x86_64-glibc
+
+# Hidden files (each file)
+.makefile
+.dist
+.rootfs
+
+# src & hw requires
+.src_requires
+.src_requires_depend
+.requires
+.requires_depend
+
+# Tarballs
+*.gz
+*.bz2
+*.lz
+*.xz
+*.tgz
+*.txz
+
+# Signatures
+*.asc
+*.sig
+*.sign
+*.sha1sum
+
+# Patches
+*.patch
+
+# Descriptions
+*.dsc
+*.txt
+
+# Default linux config files
+*.defconfig
+
+# backup copies
+*~
Index: create-1.8.3-docbook-patch/libX11-1.8.3-new/specs
===================================================================
--- create-1.8.3-docbook-patch/libX11-1.8.3-new/specs (nonexistent)
+++ create-1.8.3-docbook-patch/libX11-1.8.3-new/specs (revision 5)
Property changes on: create-1.8.3-docbook-patch/libX11-1.8.3-new/specs
___________________________________________________________________
Added: svn:ignore
## -0,0 +1,73 ##
+
+# install dir
+dist
+
+# Target build dirs
+.a1x-newlib
+.a2x-newlib
+.at91sam7s-newlib
+
+.build-machine
+
+.a1x-glibc
+.a2x-glibc
+.h3-glibc
+.h5-glibc
+.i586-glibc
+.i686-glibc
+.imx6-glibc
+.jz47xx-glibc
+.makefile
+.am335x-glibc
+.omap543x-glibc
+.p5600-glibc
+.power8-glibc
+.power8le-glibc
+.power9-glibc
+.power9le-glibc
+.m1000-glibc
+.riscv64-glibc
+.rk328x-glibc
+.rk33xx-glibc
+.rk339x-glibc
+.s8xx-glibc
+.s9xx-glibc
+.x86_64-glibc
+
+# Hidden files (each file)
+.makefile
+.dist
+.rootfs
+
+# src & hw requires
+.src_requires
+.src_requires_depend
+.requires
+.requires_depend
+
+# Tarballs
+*.gz
+*.bz2
+*.lz
+*.xz
+*.tgz
+*.txz
+
+# Signatures
+*.asc
+*.sig
+*.sign
+*.sha1sum
+
+# Patches
+*.patch
+
+# Descriptions
+*.dsc
+*.txt
+
+# Default linux config files
+*.defconfig
+
+# backup copies
+*~
Index: create-1.8.3-docbook-patch/libX11-1.8.3-new
===================================================================
--- create-1.8.3-docbook-patch/libX11-1.8.3-new (nonexistent)
+++ create-1.8.3-docbook-patch/libX11-1.8.3-new (revision 5)
Property changes on: create-1.8.3-docbook-patch/libX11-1.8.3-new
___________________________________________________________________
Added: svn:ignore
## -0,0 +1,73 ##
+
+# install dir
+dist
+
+# Target build dirs
+.a1x-newlib
+.a2x-newlib
+.at91sam7s-newlib
+
+.build-machine
+
+.a1x-glibc
+.a2x-glibc
+.h3-glibc
+.h5-glibc
+.i586-glibc
+.i686-glibc
+.imx6-glibc
+.jz47xx-glibc
+.makefile
+.am335x-glibc
+.omap543x-glibc
+.p5600-glibc
+.power8-glibc
+.power8le-glibc
+.power9-glibc
+.power9le-glibc
+.m1000-glibc
+.riscv64-glibc
+.rk328x-glibc
+.rk33xx-glibc
+.rk339x-glibc
+.s8xx-glibc
+.s9xx-glibc
+.x86_64-glibc
+
+# Hidden files (each file)
+.makefile
+.dist
+.rootfs
+
+# src & hw requires
+.src_requires
+.src_requires_depend
+.requires
+.requires_depend
+
+# Tarballs
+*.gz
+*.bz2
+*.lz
+*.xz
+*.tgz
+*.txz
+
+# Signatures
+*.asc
+*.sig
+*.sign
+*.sha1sum
+
+# Patches
+*.patch
+
+# Descriptions
+*.dsc
+*.txt
+
+# Default linux config files
+*.defconfig
+
+# backup copies
+*~
Index: create-1.8.3-docbook-patch
===================================================================
--- create-1.8.3-docbook-patch (nonexistent)
+++ create-1.8.3-docbook-patch (revision 5)
Property changes on: create-1.8.3-docbook-patch
___________________________________________________________________
Added: svn:ignore
## -0,0 +1,73 ##
+
+# install dir
+dist
+
+# Target build dirs
+.a1x-newlib
+.a2x-newlib
+.at91sam7s-newlib
+
+.build-machine
+
+.a1x-glibc
+.a2x-glibc
+.h3-glibc
+.h5-glibc
+.i586-glibc
+.i686-glibc
+.imx6-glibc
+.jz47xx-glibc
+.makefile
+.am335x-glibc
+.omap543x-glibc
+.p5600-glibc
+.power8-glibc
+.power8le-glibc
+.power9-glibc
+.power9le-glibc
+.m1000-glibc
+.riscv64-glibc
+.rk328x-glibc
+.rk33xx-glibc
+.rk339x-glibc
+.s8xx-glibc
+.s9xx-glibc
+.x86_64-glibc
+
+# Hidden files (each file)
+.makefile
+.dist
+.rootfs
+
+# src & hw requires
+.src_requires
+.src_requires_depend
+.requires
+.requires_depend
+
+# Tarballs
+*.gz
+*.bz2
+*.lz
+*.xz
+*.tgz
+*.txz
+
+# Signatures
+*.asc
+*.sig
+*.sign
+*.sha1sum
+
+# Patches
+*.patch
+
+# Descriptions
+*.dsc
+*.txt
+
+# Default linux config files
+*.defconfig
+
+# backup copies
+*~
Index: patches/README
===================================================================
--- patches/README (nonexistent)
+++ patches/README (revision 5)
@@ -0,0 +1,6 @@
+
+/* begin *
+
+ TODO: Leave some comment here.
+
+ * end */
Index: patches
===================================================================
--- patches (nonexistent)
+++ patches (revision 5)
Property changes on: patches
___________________________________________________________________
Added: svn:ignore
## -0,0 +1,73 ##
+
+# install dir
+dist
+
+# Target build dirs
+.a1x-newlib
+.a2x-newlib
+.at91sam7s-newlib
+
+.build-machine
+
+.a1x-glibc
+.a2x-glibc
+.h3-glibc
+.h5-glibc
+.i586-glibc
+.i686-glibc
+.imx6-glibc
+.jz47xx-glibc
+.makefile
+.am335x-glibc
+.omap543x-glibc
+.p5600-glibc
+.power8-glibc
+.power8le-glibc
+.power9-glibc
+.power9le-glibc
+.m1000-glibc
+.riscv64-glibc
+.rk328x-glibc
+.rk33xx-glibc
+.rk339x-glibc
+.s8xx-glibc
+.s9xx-glibc
+.x86_64-glibc
+
+# Hidden files (each file)
+.makefile
+.dist
+.rootfs
+
+# src & hw requires
+.src_requires
+.src_requires_depend
+.requires
+.requires_depend
+
+# Tarballs
+*.gz
+*.bz2
+*.lz
+*.xz
+*.tgz
+*.txz
+
+# Signatures
+*.asc
+*.sig
+*.sign
+*.sha1sum
+
+# Patches
+*.patch
+
+# Descriptions
+*.dsc
+*.txt
+
+# Default linux config files
+*.defconfig
+
+# backup copies
+*~
Index: .
===================================================================
--- . (nonexistent)
+++ . (revision 5)
Property changes on: .
___________________________________________________________________
Added: svn:ignore
## -0,0 +1,73 ##
+
+# install dir
+dist
+
+# Target build dirs
+.a1x-newlib
+.a2x-newlib
+.at91sam7s-newlib
+
+.build-machine
+
+.a1x-glibc
+.a2x-glibc
+.h3-glibc
+.h5-glibc
+.i586-glibc
+.i686-glibc
+.imx6-glibc
+.jz47xx-glibc
+.makefile
+.am335x-glibc
+.omap543x-glibc
+.p5600-glibc
+.power8-glibc
+.power8le-glibc
+.power9-glibc
+.power9le-glibc
+.m1000-glibc
+.riscv64-glibc
+.rk328x-glibc
+.rk33xx-glibc
+.rk339x-glibc
+.s8xx-glibc
+.s9xx-glibc
+.x86_64-glibc
+
+# Hidden files (each file)
+.makefile
+.dist
+.rootfs
+
+# src & hw requires
+.src_requires
+.src_requires_depend
+.requires
+.requires_depend
+
+# Tarballs
+*.gz
+*.bz2
+*.lz
+*.xz
+*.tgz
+*.txz
+
+# Signatures
+*.asc
+*.sig
+*.sign
+*.sha1sum
+
+# Patches
+*.patch
+
+# Descriptions
+*.dsc
+*.txt
+
+# Default linux config files
+*.defconfig
+
+# backup copies
+*~
Radix cross Linux
The main Radix cross Linux repository contains the build scripts of packages, which have the most complete and common functionality for desktop machines
452 Commits
2 Branches
1 Tag