git update until 25 Mar 2011

xserver 
fontconfig
glproto
libXau
libXft
libXmu
libfontenc
libxcb
mesa
mkfontscale
pixman
randrproto
xkeyboard-config
xtrans
xwininfo

updated following packages:

xproto-7.0.21
xineramaproto-1.2.1
libXt-1.1.1
libxkbfile-1.0.7
libXpm-3.5.9
libXfont-1.4.3
libXaw-1.0.9
bdftopcf-1.0.3
encodings-1.0.4
fixesproto-5.0
font-adobe-100dpi-1.0.3
font-adobe-75dpi-1.0.3
font-adobe-utopia-100dpi-1.0.4
font-adobe-utopia-75dpi-1.0.4
font-adobe-utopia-type1-1.0.4
font-alias-1.0.3
font-arabic-misc-1.0.3
font-bh-100dpi-1.0.3
font-bh-75dpi-1.0.3
font-bh-lucidatypewriter-100dpi-1.0.3
font-bh-lucidatypewriter-75dpi-1.0.3
font-bh-ttf-1.0.3
font-bh-type1-1.0.3
font-bitstream-100dpi-1.0.3
font-bitstream-75dpi-1.0.3
font-bitstream-speedo-1.0.2
font-bitstream-type1-1.0.3
font-cronyx-cyrillic-1.0.3
font-cursor-misc-1.0.3
font-daewoo-misc-1.0.3
font-dec-misc-1.0.3
font-ibm-type1-1.0.3
font-isas-misc-1.0.3
font-jis-misc-1.0.3
font-micro-misc-1.0.3
font-misc-cyrillic-1.0.3
font-misc-ethiopic-1.0.3
font-misc-meltho-1.0.3
font-misc-misc-1.1.2
font-mutt-misc-1.0.3
font-schumacher-misc-1.1.2
font-screen-cyrillic-1.0.4
font-sony-misc-1.0.3
font-sun-misc-1.0.3
font-util-1.2.0
font-winitzki-cyrillic-1.0.3
font-xfree86-type1-1.0.4

1 files changed, 3566 insertions, 0 deletions

diff --git a/libXt/specs/CH11 b/libXt/specs/CH11
new file mode 100644
index 000000000..55b8d92f3
--- /dev/null
+++ b/libXt/specs/CH11
@@ -0,0 +1,3566 @@
+.\" $Xorg: CH11,v 1.3 2000/08/17 19:42:47 cpqbld Exp $
+.\" Copyright \(co 1985, 1986, 1987, 1988, 1991, 1994
+.\" X Consortium
+.\" 
+.\" 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:
+.\" 
+.\" The above copyright notice and this permission notice shall be included
+.\" in all copies or substantial portions of the Software.
+.\" 
+.\" 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.
+.\" 
+.\" 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.
+.\" 
+.\" Copyright \(co 1985, 1986, 1987, 1988, 1991, 1994
+.\" Digital Equipment Corporation, Maynard, Massachusetts.
+.\" 
+.\" Permission to use, copy, modify and distribute this documentation for any
+.\" purpose and without fee is hereby granted, provided that the above copyright
+.\" notice appears in all copies and that both that copyright notice and this
+.\" permission notice appear in supporting documentation, and that the name of
+.\" Digital not be used in in advertising or publicity pertaining
+.\" to distribution of the software without specific, written prior permission.
+.\" Digital makes no representations about the suitability of the
+.\" software described herein for any purpose.
+.\" It is provided ``as is'' without express or implied warranty.
+.\"
+\&
+.sp 1
+.ce 3
+\s+1\fBChapter 11\fP\s-1
+
+\s+1\fBUtility Functions\fP\s-1
+.sp 2
+.nr H1 11
+.nr H2 0
+.nr H3 0
+.nr H4 0
+.nr H5 0
+.LP
+.XS
+Chapter 11 \(em Utility Functions
+.XE
+The \*(xI provide a number of utility functions that you can use to
+.IP \(bu 5
+Determine the number of elements in an array.
+.IP \(bu 5
+Translate strings to widget instances.
+.IP \(bu 5
+Manage memory usage.
+.IP \(bu 5
+Share graphics contexts.
+.IP \(bu 5
+Manipulate selections.
+.IP \(bu 5
+Merge exposure events into a region.
+.IP \(bu 5
+Translate widget coordinates.
+.IP \(bu 5
+Locate a widget given a window id.
+.IP \(bu 5
+Handle errors.
+.IP \(bu 5
+Set the WM_COLORMAP_WINDOWS property.
+.IP \(bu 5
+Locate files by name with string substitutions.
+.IP \(bu 5
+Register callback functions for external agents.
+.IP \(bu 5
+Locate all the displays of an application context.
+
+.NH 2
+Determining the Number of Elements in an Array
+.XS
+\fB\*(SN Determining the Number of Elements in an Array\fP
+.XE
+.LP
+To determine the number of elements in a fixed-size array, use
+.PN XtNumber .
+.LP
+.IN "XtNumber" "" "@DEF@"
+.sM
+.FD 0
+Cardinal XtNumber(\fIarray\fP)
+.br
+      \fIArrayType array\fP;
+.FN
+.IP \fIarray\fP 1i
+Specifies a fixed-size array of arbitrary type.
+.LP
+.eM
+The
+.PN XtNumber
+macro returns the number of elements allocated to the array.
+
+.NH 2
+Translating Strings to Widget Instances
+.XS
+\fB\*(SN Translating Strings to Widget Instances\fP
+.XE
+.LP
+To translate a widget name to a widget instance, use
+.PN XtNameToWidget .
+.LP
+.IN "XtNameToWidget" "" "@DEF@"
+.sM
+.FD 0
+Widget XtNameToWidget(\fIreference\fP, \fInames\fP)
+.br
+      Widget \fIreference\fP;
+.br
+      String \fInames\fP;
+.FN
+.IP \fIreference\fP 1i
+Specifies the widget from which the search is to start.  \*(cI
+.IP \fInames\fP 1i
+Specifies the partially qualified name of the desired widget.
+.LP
+.eM
+The
+.PN XtNameToWidget
+function searches for a descendant of the \fIreference\fP
+widget whose name matches the specified names.  The \fInames\fP parameter
+specifies a simple object name or a series of simple object name
+components separated by periods or asterisks.
+.PN XtNameToWidget
+returns the descendant with the shortest name matching the specification
+according to the following rules, where child is either a pop-up child
+or a normal child if the widget's class is a subclass of
+Composite :
+.IP \(bu 5
+Enumerate the object subtree rooted at the reference widget in
+breadth-first order, qualifying the name of each object with the
+names of all its ancestors up to, but not including, the reference
+widget.  The ordering between children of a common parent is
+not defined.
+.IP \(bu 5
+Return the first object in the enumeration that matches the
+specified name, where each component of \fInames\fP matches exactly the
+corresponding component of the qualified object name and asterisk
+matches any series of components, including none.
+.IP \(bu 5
+If no match is found, return NULL.
+.LP
+Since breadth-first traversal is specified, the descendant with the
+shortest matching name (i.e., the fewest number of components), if any,
+will always be returned.  However, since the order of enumeration of
+children is undefined and since the \*(xI do not require that all
+children of a widget have unique names,
+.PN XtNameToWidget
+may return any
+child that matches if there are multiple objects in the subtree with
+the same name.  Consecutive separators (periods or asterisks)
+including at least one asterisk are treated as a single asterisk.
+Consecutive periods are treated as a single period.
+
+.NH 2
+Managing Memory Usage
+.XS
+\fB\*(SN Managing Memory Usage\fP
+.XE
+.LP
+The \*(xI memory management functions provide uniform checking for
+null pointers and error reporting on memory allocation errors.
+These functions are completely compatible with their standard C language 
+runtime counterparts
+.PN malloc ,
+.PN calloc ,
+.PN realloc ,
+and
+.PN free
+with the following added functionality:
+.IP \(bu 5
+.PN XtMalloc ,
+.PN XtCalloc ,
+and
+.PN XtRealloc
+give an error if there is not enough memory.
+.IP \(bu 5
+.PN XtFree
+simply returns if passed a NULL pointer.
+.IP \(bu 5
+.PN XtRealloc
+simply allocates new storage if passed a NULL pointer.
+.LP
+See the standard C library documentation on
+.PN malloc ,
+.PN calloc ,
+.PN realloc ,
+and
+.PN free
+for more information.
+.sp
+.LP
+To allocate storage, use
+.PN XtMalloc .
+.LP
+.IN "XtMalloc" "" "@DEF@"
+.sM
+.FD 0
+char *XtMalloc(\fIsize\fP)
+.br
+      Cardinal \fIsize\fP;
+.FN
+.IP \fIsize\fP 1i
+Specifies the number of bytes desired.
+.LP
+.eM
+The
+.PN XtMalloc
+function returns a pointer to a block of storage of at least 
+the specified \fIsize\fP bytes.
+If there is insufficient memory to allocate the new block,
+.PN XtMalloc
+calls
+.PN XtErrorMsg .
+.sp
+.LP
+To allocate and initialize an array, use
+.PN XtCalloc .
+.LP
+.IN "XtCalloc" "" "@DEF@"
+.sM
+.FD 0
+char *XtCalloc(\fInum\fP, \fIsize\fP)
+.br
+      Cardinal \fInum\fP;
+.br
+      Cardinal \fIsize\fP;
+.FN
+.IP \fInum\fP 1i
+Specifies the number of array elements to allocate.
+.IP \fIsize\fP 1i
+Specifies the size of each array element in bytes.
+.LP
+.eM
+The
+.PN XtCalloc
+function allocates space for the specified number of array elements 
+of the specified size and initializes the space to zero.
+If there is insufficient memory to allocate the new block,
+.PN XtCalloc
+calls
+.PN XtErrorMsg .
+.PN XtCalloc
+returns the address of the allocated storage.
+.sp
+.LP
+To change the size of an allocated block of storage, use
+.PN XtRealloc .
+.LP
+.IN "XtRealloc" "" "@DEF@"
+.sM
+.FD 0
+char *XtRealloc(\fIptr\fP, \fInum\fP)
+.br
+      char *\fIptr\fP;
+.br
+      Cardinal \fInum\fP;
+.FN
+.IP \fIptr\fP 1i
+Specifies a pointer to the old storage allocated with
+.PN XtMalloc ,
+.PN XtCalloc ,
+or
+.PN XtRealloc ,
+or NULL.
+.IP \fInum\fP 1i
+Specifies number of bytes desired in new storage.
+.LP
+.eM
+The
+.PN XtRealloc
+function changes the size of a block of storage, possibly moving it.
+Then it copies the old contents (or as much as will fit) into the new block
+and frees the old block.
+If there is insufficient memory to allocate the new block,
+.PN XtRealloc
+calls
+.PN XtErrorMsg .
+If \fIptr\fP is NULL,
+.PN XtRealloc
+simply calls
+.PN XtMalloc .
+.PN XtRealloc
+then returns the address of the new block.
+.sp
+.LP
+To free an allocated block of storage, use
+.PN XtFree .
+.LP
+.IN "XtFree" "" "@DEF@"
+.sM
+.FD 0
+void XtFree(\fIptr\fP)
+.br
+      char *\fIptr\fP;
+.FN
+.IP \fIptr\fP 1i
+Specifies a pointer to a block of storage allocated with
+.PN XtMalloc ,
+.PN XtCalloc ,
+or
+.PN XtRealloc ,
+or NULL.
+.LP
+.eM
+The
+.PN XtFree
+function returns storage, allowing it to be reused.
+If \fIptr\fP is NULL,
+.PN XtFree
+returns immediately.
+.sp
+.LP
+To allocate storage for a new instance of a type, use
+.PN XtNew .
+.LP
+.IN "XtNew" "" "@DEF@"
+.sM
+.FD 0
+\fItype\fP *XtNew(\fItype\fP)
+.br
+      \fItype t\fP;
+.FN
+.IP \fItype\fP 1i
+Specifies a previously declared type.
+.LP
+.eM
+.PN XtNew
+returns a pointer to the allocated storage.
+If there is insufficient memory to allocate the new block,
+.PN XtNew
+calls
+.PN XtErrorMsg .
+.PN XtNew
+is a convenience macro that calls
+.PN XtMalloc
+with the following arguments specified:
+.LP
+.Ds
+.TA .5i
+.ta .5i
+((type *) XtMalloc((unsigned) sizeof(type)))
+.De
+.LP
+The storage allocated by
+.PN XtNew
+should be freed using
+.PN XtFree .
+.sp
+.LP
+To copy an instance of a string, use
+.PN XtNewString .
+.LP
+.IN "XtNewString" "" "@DEF@"
+.sM
+.FD 0
+String XtNewString(\fIstring\fP)
+.br
+      String \fIstring\fP;
+.FN
+.IP \fIstring\fP 1i
+Specifies a previously declared string.
+.LP
+.eM
+.PN XtNewString
+returns a pointer to the allocated storage.
+If there is insufficient memory to allocate the new block,
+.PN XtNewString
+calls
+.PN XtErrorMsg .
+.PN XtNewString
+is a convenience macro that calls
+.PN XtMalloc
+with the following arguments specified:
+.LP
+.Ds 
+.TA .5i
+.ta .5i
+(strcpy(XtMalloc((unsigned)strlen(str) + 1), str))
+.De
+.LP
+The storage allocated by
+.PN XtNewString
+should be freed using
+.PN XtFree .
+
+.NH 2
+Sharing Graphics Contexts
+.XS
+\fB\*(SN Sharing Graphics Contexts\fP
+.XE
+.LP
+The \*(xI provide a mechanism whereby cooperating objects can share a
+graphics context (GC), thereby reducing both the number of GCs
+created and the total number of server calls in any given application.
+The mechanism is a simple caching scheme
+and allows for clients to declare both modifiable and nonmodifiable
+fields of the shared GCs.
+.LP
+To obtain a shareable GC with modifiable fields, use
+.PN XtAllocateGC .
+.LP
+.IN "XtAllocateGC" "" "@DEF@"
+.sM
+.FD 0
+GC XtAllocateGC(\fIwidget\fP, \fIdepth\fP, \fIvalue_mask\fP, \fIvalues\fP, \
+\fIdynamic_mask\fP, \fIunused_mask\fP)
+.br
+      Widget \fIobject\fP;
+.br
+      Cardinal \fIdepth\fP;
+.br
+      XtGCMask \fIvalue_mask\fP;
+.br
+      XGCValues *\fIvalues\fP;
+.br
+      XtGCMask \fIdynamic_mask\fP;
+.br
+      XtGCMask \fIunused_mask\fP;
+.FN
+.IP \fIobject\fP 1i
+Specifies an object, giving the screen for which the
+returned GC is valid.  \*(oI
+.IP \fIdepth\fP 1i
+Specifies the depth for which the returned GC is valid, or 0.
+.IP \fIvalue_mask\fP 1i
+Specifies fields of the GC that are initialized from \fIvalues\fP.
+.IP \fIvalues\fP 1i
+Specifies the values for the initialized fields.
+.IP \fIdynamic_mask\fP 1i
+Specifies fields of the GC that will be modified by the caller.
+.IP \fIunused_mask\fP 1i
+Specifies fields of the GC that will not be needed by the caller.
+.LP
+.eM
+The
+.PN XtAllocateGC
+function returns a shareable GC that may be
+modified by the client.  The \fIscreen\fP field of the specified
+widget or of the nearest widget ancestor of the specified
+object and the specified \fIdepth\fP argument supply
+the root and drawable depths for which the GC is to be
+valid.  If \fIdepth\fP is zero, the depth is taken from the
+\fIdepth\fP field of the specified widget or of the nearest
+widget ancestor of the specified object.
+.LP
+The \fIvalue_mask\fP argument specifies fields of the GC
+that are initialized with the respective member of the
+\fIvalues\fP structure.  The \fIdynamic_mask\fP argument specifies fields
+that the caller intends to modify during program execution.
+The caller must ensure that the corresponding GC field is set
+prior to each use of the GC.  The \fIunused_mask\fP argument
+specifies fields of the GC that are of no interest to the
+caller.  The caller may make no assumptions about the contents
+of any fields specified in \fIunused_mask\fP.  The caller may assume
+that at all times all fields not specified in either
+\fIdynamic_mask\fP or \fIunused_mask\fP have their default value if not
+specified in \fIvalue_mask\fP or the value specified by \fIvalues\fP.
+If a field is specified in both \fIvalue_mask\fP and \fIdynamic_mask\fP,
+the effect is as if it were specified only in \fIdynamic_mask\fP
+and then immediately set to the value in \fIvalues\fP.  If a field
+is set in \fIunused_mask\fP and also in either \fIvalue_mask\fP or
+\fIdynamic_mask\fP, the specification in \fIunused_mask\fP is ignored.
+.LP
+.PN XtAllocateGC
+tries to minimize the number of unique GCs
+created by comparing the arguments with those of previous
+calls and returning an existing GC when there are no
+conflicts.
+.PN XtAllocateGC
+may modify and return an existing GC if it was allocated with a
+nonzero \fIunused_mask\fP.
+.sp
+.LP
+To obtain a shareable GC with no modifiable fields, use
+.PN XtGetGC .
+.LP
+.IN "XtGetGC" "" "@DEF@"
+.sM
+.FD 0
+GC XtGetGC(\fIobject\fP, \fIvalue_mask\fP, \fIvalues\fP)
+.br
+      Widget \fIobject\fP;
+.br
+      XtGCMask \fIvalue_mask\fP;
+.br
+      XGCValues *\fIvalues\fP;
+.FN
+.IP \fIobject\fP 1i
+Specifies an object, giving the screen and depth for which the
+returned GC is valid.  \*(oI
+.IP \fIvalue_mask\fP 1i
+Specifies which fields of the \fIvalues\fP structure are specified.
+.IP \fIvalues\fP 1i
+Specifies the actual values for this GC.
+.LP
+.eM
+The
+.PN XtGetGC
+function returns a shareable, read-only GC.
+The parameters to this function are the same as those for
+.PN XCreateGC 
+except that an Object is passed instead of a Display.
+.PN XtGetGC
+is equivalent to
+.PN XtAllocateGC
+with \fIdepth\fP, \fIdynamic_mask\fP, and \fIunused_mask\fP all zero.
+.LP
+.PN XtGetGC
+shares only GCs in which all values in the GC returned by
+.PN XCreateGC
+are the same.
+In particular, it does not use the \fIvalue_mask\fP provided to
+determine which fields of the GC a widget considers relevant.
+The \fIvalue_mask\fP is used only to tell the server which fields should be
+filled in from \fIvalues\fP and which it should fill in with default values.
+.sp
+.LP
+To deallocate a shared GC when it is no longer needed, use
+.PN XtReleaseGC .
+.LP
+.IN "XtReleaseGC" "" "@DEF@"
+.sM
+.FD 0
+void XtReleaseGC(\fIobject\fP, \fIgc\fP)
+.br
+      Widget \fIobject\fP;
+.br
+      GC \fIgc\fP;
+.FN
+.IP \fIobject\fP 1i
+Specifies any object on the Display for which the GC was created.  \*(oI
+.IP \fIgc\fP 1i
+Specifies the shared GC obtained with either
+.PN XtAllocateGC
+or
+.PN XtGetGC .
+.LP
+.eM
+References to shareable GCs are counted and a free request is generated to the
+server when the last user of a given GC releases it.
+
+.NH 2
+Managing Selections
+.XS
+\*(SN Managing Selections
+.XE
+.LP
+Arbitrary widgets in multiple applications can communicate 
+with each other by means of the \*(xI global selection mechanism,
+which conforms to the specifications in the \fI\*(xC\fP.
+The \*(xI supply functions for providing and receiving selection data in
+one logical piece (atomic transfers)
+or in smaller logical segments (incremental transfers).
+.LP
+The incremental interface is provided for a selection owner or
+selection requestor that cannot or prefers not to pass the selection
+value to and from the \*(xI in a single call.  For instance,
+either an application that is running on a machine with limited memory
+may not be able to store the entire selection value in memory or a
+selection owner may already have the selection value available in
+discrete chunks, and it would be more efficient not to have to
+allocate additional storage to copy the pieces contiguously.  Any
+owner or requestor that prefers to deal with the selection value in
+segments can use the incremental interfaces to do so.
+The transfer between the selection owner or requestor and the \*(xI is not
+required to match the underlying
+transport protocol between the application and the X server;
+the \*(xI will break too large a selection 
+into smaller pieces for transport if necessary
+and will coalesce a selection transmitted incrementally if the value
+was requested atomically.
+
+.NH 3
+Setting and Getting the Selection Timeout Value
+.XS
+\fB\*(SN Setting and Getting the Selection Timeout Value\fP
+.XE
+.LP
+To set the \*(xI selection timeout, use
+.PN XtAppSetSelectionTimeout .
+.LP
+.IN "XtAppSetSelectionTimeout" "" "@DEF@"
+.sM
+.FD 0
+void XtAppSetSelectionTimeout(\fIapp_context\fP, \fItimeout\fP)
+.br
+    XtAppContext \fIapp_context\fP;
+.br
+    unsigned long \fItimeout\fP;
+.FN
+.IP \fIapp_context\fP 1i
+Specifies the application context.
+.IP \fItimeout\fP 1i
+Specifies the selection timeout in milliseconds.
+.eM
+.LP
+To get the current selection timeout value, use
+.PN XtAppGetSelectionTimeout .
+.LP
+.IN "XtAppGetSelectionTimeout" "" "@DEF@"
+.sM
+.FD 0
+unsigned long XtAppGetSelectionTimeout(\fIapp_context\fP)
+.br
+     XtAppContext \fIapp_context\fP;
+.FN
+.IP \fIapp_context\fP 1i
+Specifies the application context.
+.LP
+.eM
+The
+.PN XtAppGetSelectionTimeout
+function returns the current selection timeout value in milliseconds.
+The selection timeout is the time within which the two communicating 
+applications must respond to one another.
+The initial timeout value is set by the 
+selectionTimeout
+.IN "selectionTimeout"
+application resource as retrieved by
+.PN XtDisplayInitialize .
+If
+selectionTimeout
+is not specified,
+the default is five seconds.
+
+.NH 3
+Using Atomic Transfers
+.XS
+\*(SN Using Atomic Transfers
+.XE
+.LP
+When using atomic transfers, the owner will completely
+process one selection request at a time.
+The owner may consider each request individually,
+since there is no possibility for overlap
+between evaluation of two requests.
+
+.NH 4
+Atomic Transfer Procedures
+.XS
+\*(SN Atomic Transfer Procedures
+.XE
+.IN "Selections" "atomic"
+.LP
+The following procedures are used by the selection owner when
+providing selection data in a single unit.
+.LP
+The procedure pointer specified by the owner to supply the selection
+data to the \*(xI is of type
+.PN XtConvertSelectionProc .
+.LP
+.IN "XtConvertSelectionProc" "" "@DEF@"
+.sM
+.FD 0
+typedef Boolean (*XtConvertSelectionProc)(Widget, Atom*, Atom*, Atom*,
+.br
+                      XtPointer*, unsigned long*, int*);
+.br
+    Widget \fIw\fP;
+.br
+    Atom *\fIselection\fP;
+.br
+    Atom *\fItarget\fP;
+.br
+    Atom *\fItype_return\fP;
+.br
+    XtPointer *\fIvalue_return\fP;
+.br
+    unsigned long *\fIlength_return\fP;
+.br
+    int *\fIformat_return\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget that currently owns this selection.
+.IP \fIselection\fP 1i
+Specifies the atom naming the selection requested
+(for example,
+.PN XA_PRIMARY
+or 
+.PN XA_SECONDARY ).
+.IP \fItarget\fP 1i
+Specifies the target type of the selection that has been requested,
+which indicates the desired information about the selection 
+(for example, File Name, Text, Window).
+.IP \fItype_return\fP 1i
+Specifies a pointer to an atom into which the property type of the 
+converted value of the selection is to be stored.
+For instance, either File Name or Text might have property type 
+.PN XA_STRING .
+.IP \fIvalue_return\fP 1i
+Specifies a pointer into which a pointer to the converted value of the 
+selection is to be stored.
+The selection owner is responsible for allocating this storage.
+If the selection owner has provided an
+.PN XtSelectionDoneProc
+for the selection, 
+this storage is owned by the selection owner; 
+otherwise, it is owned by the \*(xI selection mechanism, 
+which frees it by calling
+.PN XtFree
+when it is done with it.
+.IP \fIlength_return\fP 1i
+Specifies a pointer into which the number of elements in \fIvalue_return\fP,
+each of size indicated by \fIformat_return\fP, is to be stored.
+.IP \fIformat_return\fP 1i
+Specifies a pointer into which the size in bits of the data elements 
+of the selection value is to be stored.
+.LP
+.eM
+This procedure is called by the \*(xI selection mechanism 
+to get the value of a selection as a given type 
+from the current selection owner.
+It returns 
+.PN True 
+if the owner successfully converted the selection to the target type or
+.PN False
+otherwise.
+If the procedure returns
+.PN False ,
+the values of the return arguments are undefined.
+Each
+.PN XtConvertSelectionProc
+should respond to target value
+.PN TARGETS 
+by returning a value containing the list of the targets
+into which it is
+prepared to convert the selection.
+The value returned in
+\fIformat_return\fP must be one of 8, 16, or 32 to allow the server to
+byte-swap the data if necessary.
+.LP
+.IN "Selections" "MULTIPLE"
+.IN "Selections" "TIMESTAMP"
+This procedure does not need to worry about responding to the
+MULTIPLE or the TIMESTAMP target values (see Section 2.6.2 in the \fI\*(xC\fP).
+A selection request with
+the MULTIPLE target type is transparently transformed into a
+series of calls to this procedure, one for each target type, and a
+selection request with the TIMESTAMP target value is answered
+automatically by the \*(xI using the time specified in the
+call to
+.PN XtOwnSelection
+or
+.PN XtOwnSelectionIncremental .
+.sp
+.LP
+To retrieve the
+.PN SelectionRequest
+event that triggered the
+.PN XtConvertSelectionProc
+procedure, use
+.PN XtGetSelectionRequest .
+.LP
+.IN "XtGetSelectionRequest" "" "@DEF@"
+.sM
+.FD 0
+XSelectionRequestEvent *XtGetSelectionRequest(\fIw\fP, \fIselection\fP, \
+\fIrequest_id\fP)
+.br
+      Widget \fIw\fP;
+.br
+      Atom \fIselection\fP;
+.br
+      XtRequestId \fIrequest_id\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget that currently owns this selection.  \*(cI
+.IP \fIselection\fP 1i
+Specifies the selection being processed.
+.IP \fIrequest_id\fP 1i
+Specifies the requestor id in the case of incremental
+selections, or NULL in the case of atomic transfers.
+.LP
+.eM
+.PN XtGetSelectionRequest
+may be called only from within an
+.PN XtConvertSelectionProc
+procedure and returns a pointer to the
+.PN SelectionRequest
+event that caused the conversion procedure to be invoked.
+\fIRequest_id\fP specifies a unique id for the individual request in the
+case that multiple incremental transfers are outstanding.  For atomic
+transfers, \fIrequest_id\fP must be specified as NULL.  If no
+.PN SelectionRequest
+event is being processed for the specified
+\fIwidget\fP, \fIselection\fP, and \fIrequest_id\fP,
+.PN XtGetSelectionRequest
+returns NULL.
+.sp
+.LP
+The procedure pointer specified by the owner when it desires
+notification upon losing ownership is of type
+.PN XtLoseSelectionProc .
+.LP
+.IN "XtLoseSelectionProc" "" "@DEF@"
+.sM
+.FD 0
+typedef void (*XtLoseSelectionProc)(Widget, Atom*);
+.br
+    Widget \fIw\fP;
+.br
+    Atom *\fIselection\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget that has lost selection ownership.
+.IP \fIselection\fP 1i
+Specifies the atom naming the selection.
+.LP
+.eM
+This procedure is called by the \*(xI selection mechanism
+to inform the specified widget that it has lost the given selection.
+Note that this procedure does not ask the widget to relinquish the 
+selection ownership; it is merely informative.
+.sp
+.LP
+The procedure pointer specified by the owner when it desires
+notification of receipt of the data or when it manages the storage
+containing the data is of type
+.PN XtSelectionDoneProc .
+.LP
+.IN "XtSelectionDoneProc" "" "@DEF@"
+.sM
+.FD 0
+typedef void (*XtSelectionDoneProc)(Widget, Atom*, Atom*);
+.br
+      Widget \fIw\fP;
+.br
+      Atom *\fIselection\fP;
+.br
+      Atom *\fItarget\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget that owns the converted selection.
+.IP \fIselection\fP 1i
+Specifies the atom naming the selection that was converted.
+.IP \fItarget\fP 1i
+Specifies the target type to which the conversion was done.
+.LP
+.eM
+This procedure is called by the \*(xI selection mechanism
+to inform the selection owner that a selection requestor has successfully
+retrieved a selection value.
+If the selection owner has registered an
+.PN XtSelectionDoneProc ,
+it should expect it to be called once for each conversion that it performs,
+after the converted value has been successfully transferred
+to the requestor.
+If the selection owner has registered an
+.PN XtSelectionDoneProc ,
+it also owns the storage containing the converted
+selection value.
+
+.NH 4
+Getting the Selection Value
+.XS
+\*(SN Getting the Selection Value
+.XE
+.LP
+The procedure pointer specified by the requestor to receive the
+selection data from the \*(xI is of type
+.PN XtSelectionCallbackProc .
+.LP
+.IN "XtSelectionCallbackProc" "" "@DEF@"
+.sM
+.FD 0
+typedef void (*XtSelectionCallbackProc)(Widget, XtPointer, Atom*, Atom*, \
+XtPointer, unsigned long*, int*);
+.br
+      Widget \fIw\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.br
+      Atom *\fIselection\fP;
+.br
+      Atom *\fItype\fP;
+.br
+      XtPointer \fIvalue\fP;
+.br
+      unsigned long *\fIlength\fP;
+.br
+      int *\fIformat\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget that requested the selection value.
+.IP \fIclient_data\fP 1i
+Specifies a value passed in by the widget when it requested the
+selection.
+.IP \fIselection\fP 1i
+Specifies the name of the selection that was requested.
+.IP \fItype\fP 1i
+Specifies the representation type of the selection value (for example,
+.PN XA_STRING ).
+Note that it is not the target that was requested (which the client
+must remember for itself), but the type that
+is used to represent the target.
+The special symbolic constant
+.PN XT_CONVERT_FAIL 
+is used to indicate that the selection conversion failed because the
+selection owner did not respond within the \*(xI selection timeout
+interval.
+.IP \fIvalue\fP 1i
+Specifies a pointer to the selection value.
+The requesting client owns this storage and is responsible for freeing it 
+by calling
+.PN XtFree
+when it is done with it.
+.IP \fIlength\fP 1i
+Specifies the number of elements in \fIvalue\fP.
+.IP \fIformat\fP 1i
+Specifies the size in bits of the data in each element of \fIvalue\fP.
+.LP
+.eM
+This procedure is called by the \*(xI selection mechanism to deliver the
+requested selection to the requestor.
+.LP
+If the
+.PN SelectionNotify
+event returns a property of
+.PN None ,
+meaning the conversion has been refused because there is no owner for the
+specified selection or the owner cannot convert the selection to the
+requested target for any reason, the procedure is called with a value
+of NULL and a length of zero.
+.sp
+.LP
+To obtain the selection value in a single logical unit, use
+.PN XtGetSelectionValue
+or
+.PN XtGetSelectionValues .
+.LP
+.IN "XtGetSelectionValue" "" "@DEF@"
+.sM
+.FD 0
+void XtGetSelectionValue(\fIw\fP, \fIselection\fP, \fItarget\fP, \
+\fIcallback\fP, \fIclient_data\fP, \fItime\fP)
+.br
+      Widget \fIw\fP;
+.br
+      Atom \fIselection\fP;
+.br
+      Atom \fItarget\fP;
+.br
+      XtSelectionCallbackProc \fIcallback\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.br
+      Time \fItime\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget making the request.  \*(cI
+.IP \fIselection\fP 1i
+Specifies the particular selection desired; for example,
+.PN XA_PRIMARY .
+.IP \fItarget\fP 1i
+Specifies the type of information needed about the selection.
+.IP \fIcallback\fP 1i
+Specifies the procedure to be called when the selection value
+has been obtained.
+Note that this is how the selection value is communicated back to the client.
+.IP \fIclient_data\fP 1i
+Specifies additional data to be passed to the specified procedure
+when it is called.
+.IP \fItime\fP 1i
+Specifies the timestamp that indicates when the selection request was
+initiated.
+This should be the timestamp of the event that triggered this request;
+the value 
+.PN CurrentTime 
+is not acceptable.
+.LP
+.eM
+The
+.PN XtGetSelectionValue
+function requests the value of the selection converted to 
+the target type. 
+The specified callback is called at some time after 
+.PN XtGetSelectionValue 
+is called, when the selection value is received from the X server.
+It may be called before or after 
+.PN XtGetSelectionValue 
+returns.
+For more information about \fIselection\fP, \fItarget\fP, and
+\fItime\fP, see Section 2.6 in the \fI\*(xC\fP.
+.sp
+.LP
+.IN "XtGetSelectionValues" "" "@DEF@"
+.sM
+.FD 0
+void XtGetSelectionValues(\fIw\fP, \fIselection\fP, \fItargets\fP, \
+\fIcount\fP, \fIcallback\fP, \fIclient_data\fP, \fItime\fP)
+.br
+      Widget \fIw\fP;
+.br
+      Atom \fIselection\fP;
+.br
+      Atom *\fItargets\fP;
+.br
+      int \fIcount\fP;
+.br
+      XtSelectionCallbackProc \fIcallback\fP;
+.br
+      XtPointer *\fIclient_data\fP;
+.br
+      Time \fItime\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget making the request.  \*(cI
+.IP \fIselection\fP 1i
+Specifies the particular selection desired (that is, primary or secondary).
+.IP \fItargets\fP 1i
+Specifies the types of information needed about the selection.
+.IP \fIcount\fP 1i
+Specifies the length of the \fItargets\fP and \fIclient_data\fP lists.
+.IP \fIcallback\fP 1i
+Specifies the callback procedure
+to be called with each selection value obtained.
+Note that this is how the selection values are communicated back to the
+client.
+.IP \fIclient_data\fP 1i
+Specifies a list of additional data values, one for each target type,
+that are passed to the callback procedure when it is called for that target.
+.IP \fItime\fP 1i
+Specifies the timestamp that indicates when the selection request was
+initiated.
+This should be the timestamp of the event that triggered this request;
+the value 
+.PN CurrentTime
+is not acceptable.
+.LP
+.eM
+The
+.PN XtGetSelectionValues
+function is similar to multiple calls to
+.PN XtGetSelectionValue 
+except that it guarantees that no other client can assert ownership
+between requests and therefore that all the conversions will refer to
+the same selection value.  The callback is invoked once for each
+target value with the corresponding client data.
+For more information about \fIselection\fP, \fItarget\fP, and
+\fItime\fP, see Section 2.6 in the \fI\*(xC\fP.
+
+.NH 4
+Setting the Selection Owner
+.XS
+\*(SN Setting the Selection Owner
+.XE
+.LP
+To set the selection owner and indicate that the selection value will
+be provided in one piece, use
+.PN XtOwnSelection .
+.LP
+.IN "XtOwnSelection" "" "@DEF@"
+.sM
+.FD 0
+Boolean XtOwnSelection(\fIw\fP, \fIselection\fP, \fItime\fP, \
+\fIconvert_proc\fP, \fIlose_selection\fP, \fIdone_proc\fP)
+.br
+      Widget \fIw\fP;
+.br
+      Atom \fIselection\fP;
+.br
+      Time \fItime\fP;
+.br
+      XtConvertSelectionProc \fIconvert_proc\fP;
+.br
+      XtLoseSelectionProc \fIlose_selection\fP;
+.br
+      XtSelectionDoneProc \fIdone_proc\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget that wishes to become the owner.  \*(cI
+.IP \fIselection\fP 1i
+Specifies the name of the selection (for example,
+.PN XA_PRIMARY ).
+.IP \fItime\fP 1i
+Specifies the timestamp that indicates when the ownership request was
+initiated.
+This should be the timestamp of the event that triggered ownership;
+the value
+.PN CurrentTime 
+is not acceptable.
+.IP \fIconvert_proc\fP 1i
+Specifies the procedure to be called whenever a client requests the 
+current value of the selection.
+.IP \fIlose_selection\fP 1i
+Specifies the procedure to be called whenever the widget has 
+lost selection ownership, or NULL if the owner is not interested in being 
+called back.
+.IP \fIdone_proc\fP 1i
+Specifies the procedure called 
+after the requestor has received the selection value, or NULL if the
+owner is not
+interested in being called back.
+.LP
+.eM
+The
+.PN XtOwnSelection
+function informs the \*(xI selection mechanism that a
+widget wishes to own a selection.
+It returns 
+.PN True 
+if the widget successfully becomes the owner and 
+.PN False
+otherwise.
+The widget may fail to become the owner if some other widget 
+has asserted ownership at a time later than this widget.
+The widget can lose selection ownership either 
+because some other widget asserted later ownership of the selection 
+or because the widget voluntarily gave up ownership of the selection.
+The lose_selection procedure is not called 
+if the widget fails to obtain selection ownership in the first place.
+.LP
+If a done_proc is specified, the client owns the storage allocated
+for passing the value to the \*(xI.  If \fIdone_proc\fP is NULL,
+the convert_proc must allocate storage using
+.PN XtMalloc ,
+.PN XtRealloc ,
+or
+.PN XtCalloc ,
+and the value specified is freed by the
+\*(xI when the transfer is complete.
+.sp
+.LP
+Usually, a selection owner maintains ownership indefinitely until some
+other widget requests ownership, at which time
+the \*(xI selection mechanism informs the previous owner that it
+has lost ownership of the selection.
+However, in response to some user actions 
+(for example, when a user deletes the information selected),
+the application may wish to explicitly inform the \*(xI
+by using
+.PN XtDisownSelection
+that it no longer is to be the selection owner.
+.LP
+.IN "XtDisownSelection" "" "@DEF@"
+.sM
+.FD 0
+void XtDisownSelection(\fIw\fP, \fIselection\fP, \fItime\fP)
+.br
+      Widget \fIw\fP;
+.br
+      Atom \fIselection\fP;
+.br
+      Time \fItime\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget that wishes to relinquish ownership.
+.IP \fIselection\fP 1i
+Specifies the atom naming the selection being given up.
+.IP \fItime\fP 1i
+Specifies the timestamp that indicates when the request to
+relinquish selection ownership was initiated.
+.LP
+.eM
+The
+.PN XtDisownSelection
+function informs the \*(xI selection mechanism that
+the specified widget is to lose ownership of the selection.
+If the widget does not currently own the selection, either 
+because it lost the selection 
+or because it never had the selection to begin with,
+.PN XtDisownSelection
+does nothing.
+.LP
+After a widget has called
+.PN XtDisownSelection ,
+its convert procedure is not called even if a request arrives later 
+with a timestamp during the period that this widget owned the selection.
+However, its done procedure is called if a conversion that started 
+before the call to
+.PN XtDisownSelection
+finishes after the call to
+.PN XtDisownSelection .
+
+.NH 3
+Using Incremental Transfers
+.XS
+\*(SN Using Incremental Transfers
+.XE
+.LP
+When using the incremental interface, an owner may have to process
+more than one selection request for the same selection, converted to
+the same target, at the same time.  The incremental functions take a
+\fIrequest_id\fP argument, which is an identifier that is guaranteed to be
+unique among all incremental requests that are active concurrently.
+.LP
+For example, consider the following:
+.IP \(bu 5
+Upon receiving a request for the selection value, the owner sends
+the first segment.
+.IP \(bu 5
+While waiting to be called to provide the next segment value but
+before sending it, the owner receives another request from a
+different requestor for the same selection value. 
+.IP \(bu 5
+To distinguish between the requests, the owner uses the request_id
+value.  This allows the owner to distinguish between the first
+requestor, which is asking for the second segment, and the second
+requestor, which is asking for the first segment. 
+
+.NH 4
+Incremental Transfer Procedures
+.XS
+\*(SN Incremental Transfer Procedures
+.XE
+.IN "Selections" "incremental"
+.LP
+The following procedures are used by selection owners who wish to
+provide the selection data in multiple segments.
+.LP
+The procedure pointer specified by the incremental owner to supply the
+selection data to the \*(xI is of type
+.PN XtConvertSelectionIncrProc .
+.LP
+.sM
+.Ds 0
+typedef XtPointer XtRequestId;
+.De
+.IN "XtRequestId" "" "@DEF@"
+.IN "XtConvertSelectionIncrProc" "" "@DEF@"
+.FD 0
+typedef Boolean (*XtConvertSelectionIncrProc)(Widget, Atom*, Atom*, \
+Atom*, XtPointer*,
+                               unsigned long*, int*, unsigned long*, \
+XtPointer, XtRequestId*);
+.br
+      Widget \fIw\fP;
+.br
+      Atom *\fIselection\fP;
+.br
+      Atom *\fItarget\fP;
+.br
+      Atom *\fItype_return\fP;
+.br
+      XtPointer *\fIvalue_return\fP;
+.br
+      unsigned long *\fIlength_return\fP;
+.br
+      int *\fIformat_return\fP;
+.br
+      unsigned long *\fImax_length\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.br
+      XtRequestId *\fIrequest_id\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget that currently owns this selection.
+.IP \fIselection\fP 1i
+Specifies the atom that names the selection requested.
+.IP \fItarget\fP 1i
+Specifies the type of information required about the selection.
+.IP \fItype_return\fP 1i
+Specifies a pointer to an atom into which the property
+type of the converted value of the selection is to be
+stored.
+.IP \fIvalue_return\fP 1i
+Specifies a pointer into which a pointer to the
+converted value of the selection is to be stored.
+The selection owner is responsible for allocating this storage.
+.IP \fIlength_return\fP 1i
+Specifies a pointer into which the number of elements
+in \fIvalue_return\fP, each of size indicated by
+\fIformat_return\fP, is to be stored.
+.IP \fIformat_return\fP 1i
+Specifies a pointer into which the size in bits of the
+data elements of the selection value is to be stored so that the
+server may byte-swap the data if necessary.
+.IP \fImax_length\fP 1i
+Specifies the maximum number of bytes which may be
+transferred at any one time.
+.IP \fIclient_data\fP 1i
+Specifies the value passed in by the widget when it
+took ownership of the selection.
+.IP \fIrequest_id\fP 1i
+Specifies an opaque identification for a specific request.
+.LP
+.eM
+This procedure is called repeatedly by the \*(xI selection mechanism to get
+the next incremental chunk of data from a selection owner who has
+called
+.PN XtOwnSelectionIncremental .
+It must return
+.PN True
+if the procedure has succeeded in converting the selection data or
+.PN False
+otherwise.
+On the first call with a particular request id, the owner must begin
+a new incremental transfer for the requested selection and target.  On
+subsequent calls with the same request id, the owner may assume that
+the previously supplied value is no longer needed by the \*(xI;
+that is, a fixed transfer area may be allocated and returned in \fIvalue_return\fP
+for each segment to be transferred.  This procedure should store a
+non-NULL value in \fIvalue_return\fP and zero in \fIlength_return\fP to indicate that the
+entire selection has been delivered.  After returning this final
+segment, the request id may be reused by the \*(xI to begin a
+new transfer.
+.LP
+To retrieve the
+.PN SelectionRequest
+event that triggered the selection conversion procedure, use
+.PN XtGetSelectionRequest ,
+described in Section 11.5.2.1.
+.sp
+.LP
+The procedure pointer specified by the incremental selection owner
+when it desires notification upon no longer having ownership is of
+type
+.PN XtLoseSelectionIncrProc .
+.LP
+.IN "XtLoseSelectionIncrProc" "" "@DEF@"
+.sM
+.FD 0
+typedef void (*XtLoseSelectionIncrProc)(Widget, Atom*, XtPointer);
+.br
+      Widget \fIw\fP;
+.br
+      Atom *\fIselection\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget that has lost the selection ownership.
+.IP \fIselection\fP 1i
+Specifies the atom that names the selection.
+.IP \fIclient_data\fP 1i
+Specifies the value passed in by the widget when it
+took ownership of the selection.
+.LP
+.eM
+This procedure, which is optional, is called by the \*(xI to
+inform the selection owner that it no longer owns the selection.
+.sp
+.LP
+The procedure pointer specified by the incremental selection owner
+when it desires notification of receipt of the data or when it manages
+the storage containing the data is of type
+.PN XtSelectionDoneIncrProc .
+.LP
+.IN "XtSelectionDoneIncrProc" "" "@DEF@"
+.sM
+.FD 0
+typedef void (*XtSelectionDoneIncrProc)(Widget, Atom*, Atom*, \
+XtRequestId*, XtPointer);
+.br
+      Widget \fIw\fP;
+.br
+      Atom *\fIselection\fP;
+.br
+      Atom *\fItarget\fP;
+.br
+      XtRequestId *\fIrequest_id\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget that owns the selection.
+.IP \fIselection\fP 1i
+Specifies the atom that names the selection being transferred.
+.IP \fItarget\fP 1i
+Specifies the target type to which the conversion was done.
+.IP \fIrequest_id\fP 1i
+Specifies an opaque identification for a specific request.
+.IP \fIclient_data\fP 1i
+Specified the value passed in by the widget when it
+took ownership of the selection.
+.LP
+.eM
+This procedure, which is optional, is called by the \*(xI after
+the requestor has retrieved the final (zero-length) segment of the
+incremental transfer to indicate that the entire transfer is complete.
+If this procedure is not specified, the \*(xI will free only the
+final value returned by the selection owner using
+.PN XtFree .
+.sp
+.LP
+The procedure pointer specified by the incremental selection owner to
+notify it if a transfer should be terminated prematurely is of type
+.PN XtCancelConvertSelectionProc .
+.LP
+.IN "XtCancelConvertSelectionProc" "" "@DEF@"
+.sM
+.FD 0
+typedef void (*XtCancelConvertSelectionProc)(Widget, Atom*, Atom*, \
+XtRequestId*, XtPointer);
+.br
+      Widget \fIw\fP;
+.br
+      Atom *\fIselection\fP;
+.br
+      Atom *\fItarget\fP;
+.br
+      XtRequestId *\fIrequest_id\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget that owns the selection.
+.IP \fIselection\fP 1i
+Specifies the atom that names the selection being transferred.
+.IP \fItarget\fP 1i
+Specifies the target type to which the conversion was done.
+.IP \fIrequest_id\fP 1i
+Specifies an opaque identification for a specific request.
+.IP \fIclient_data\fP 1i
+Specifies the value passed in by the widget when it took ownership of
+the selection.
+.LP
+.eM
+This procedure is called by the \*(xI when it has been determined
+by means of a timeout or other mechanism that any remaining segments
+of the selection no longer need to be transferred.  Upon receiving
+this callback, the selection request is considered complete and the
+owner can free the memory and any other resources that have been
+allocated for the transfer.
+
+.NH 4
+Getting the Selection Value Incrementally
+.XS
+\*(SN Getting the Selection Value Incrementally
+.XE
+.LP
+To obtain the value of the selection using incremental transfers, use
+.PN XtGetSelectionValueIncremental
+or
+.PN XtGetSelectionValuesIncremental .
+.LP
+.IN "XtGetSelectionValueIncremental" "" "@DEF@"
+.sM
+.FD 0
+void XtGetSelectionValueIncremental(\fIw\fP, \fIselection\fP, \fItarget\fP, \
+\fIselection_callback\fP, \fIclient_data\fP, \fItime\fP)
+.br
+      Widget \fIw\fP;
+.br
+      Atom \fIselection\fP;
+.br
+      Atom \fItarget\fP;
+.br
+      XtSelectionCallbackProc \fIselection_callback\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.br
+      Time \fItime\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget making the request.  \*(cI
+.IP \fIselection\fP 1i
+Specifies the particular selection desired.
+.IP \fItarget\fP 1i
+Specifies the type of information needed
+about the selection.
+.IP \fIselection_callback\fP 1i
+Specifies the callback procedure to be
+called to receive each data segment.
+.IP \fIclient_data\fP 1i
+Specifies client-specific data to be passed to
+the specified callback procedure when it is invoked.
+.IP \fItime\fP 1i
+Specifies the timestamp that indicates when the
+selection request was initiated.  This should be the
+timestamp of the event that triggered this request;
+the value
+.PN CurrentTime
+is not acceptable.
+.LP
+.eM
+The
+.PN XtGetSelectionValueIncremental
+function is similar to
+.PN XtGetSelectionValue
+except that the selection_callback procedure will
+be called repeatedly upon delivery of multiple segments of the
+selection value.  The end of the selection value is indicated when
+\fIselection_callback\fP is called with a non-NULL value of length zero,
+which must still be freed by the client.  If the
+transfer of the selection is aborted in the middle of a transfer
+(for example, because of a timeout), the selection_callback procedure is
+called with a type value equal to the symbolic constant
+.PN XT_CONVERT_FAIL
+so that the requestor can dispose
+of the partial selection value it has collected up until that point.
+Upon receiving
+.PN XT_CONVERT_FAIL ,
+the requesting client must determine
+for itself whether or not a partially completed data transfer is meaningful.
+For more information about \fIselection\fP, \fItarget\fP, and
+\fItime\fP, see Section 2.6 in the \fI\*(xC\fP.
+.LP
+.IN "XtGetSelectionValuesIncremental" "" "@DEF@"
+.sM
+.FD 0
+void XtGetSelectionValuesIncremental(\fIw\fP, \fIselection\fP, \fItargets\fP, \
+\fIcount\fP, \fIselection_callback\fP, \fIclient_data\fP, \fItime\fP)
+.br
+      Widget \fIw\fP;
+.br
+      Atom \fIselection\fP;
+.br
+      Atom *\fItargets\fP;
+.br
+      int \fIcount\fP;
+.br
+      XtSelectionCallbackProc \fIselection_callback\fP;
+.br
+      XtPointer *\fIclient_data\fP;
+.br
+      Time \fItime\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget making the request.  \*(cI
+.IP \fIselection\fP 1i
+Specifies the particular selection desired.
+.IP \fItargets\fP 1i
+Specifies the types of information needed about
+the selection.
+.IP \fIcount\fP 1i
+Specifies the length of the \fItargets\fP and \fIclient_data\fP lists.
+.IP \fIselection_callback\fP 1i
+Specifies the callback procedure to be called
+to receive each selection value.
+.IP \fIclient_data\fP 1i
+Specifies a list of client data (one for each target
+type) values that are passed to the callback procedure when
+it is invoked for the corresponding target.
+.IP \fItime\fP 1i
+Specifies the timestamp that indicates when the
+selection request was initiated.  This should be the
+timestamp of the event that triggered this request;
+the value
+.PN CurrentTime
+is not acceptable.
+.LP
+.eM
+The
+.PN XtGetSelectionValuesIncremental
+function is similar to
+.PN XtGetSelectionValueIncremental
+except that it takes a list of targets and client data.
+.PN XtGetSelectionValuesIncremental
+is equivalent to calling
+.PN XtGetSelectionValueIncremental
+successively for each \fItarget/client_data\fP pair except that
+.PN XtGetSelectionValuesIncremental
+does guarantee that all the conversions will use the same selection
+value because the ownership of the selection cannot change in the
+middle of the list, as would be possible when calling
+.PN XtGetSelectionValueIncremental
+repeatedly.
+For more information about \fIselection\fP, \fItarget\fP, and
+\fItime\fP, see Section 2.6 in the \fI\*(xC\fP.
+
+.NH 4
+Setting the Selection Owner for Incremental Transfers
+.XS
+\*(SN Setting the Selection Owner for Incremental Transfers
+.XE
+.LP
+To set the selection owner when using incremental transfers, use
+.PN XtOwnSelectionIncremental .
+.LP
+.IN "XtOwnSelectionIncremental" "" "@DEF@"
+.sM
+.FD 0
+Boolean XtOwnSelectionIncremental(\fIw\fP, \fIselection\fP, \fItime\fP, \
+\fIconvert_callback\fP, \fIlose_callback\fP,
+                                  \fIdone_callback\fP, \
+\fIcancel_callback\fP, \fIclient_data\fP)
+.br
+      Widget \fIw\fP;
+.br
+      Atom \fIselection\fP;
+.br
+      Time \fItime\fP;
+.br
+      XtConvertSelectionIncrProc \fIconvert_callback\fP;
+.br
+      XtLoseSelectionIncrProc \fIlose_callback\fP;
+.br
+      XtSelectionDoneIncrProc \fIdone_callback\fP;
+.br
+      XtCancelConvertSelectionProc \fIcancel_callback\fP;
+.br
+      XtPointer \fIclient_data\fP;
+.FN
+.IP \fIw\fP 1.25i
+Specifies the widget that wishes to become the owner.  \*(cI
+.IP \fIselection\fP 1.25i
+Specifies the atom that names the selection.
+.IP \fItime\fP 1.25i
+Specifies the timestamp that indicates when the
+selection ownership request was initiated.  This should be
+the timestamp of the event that triggered ownership; the value
+.PN CurrentTime
+is not acceptable.
+.IP \fIconvert_callback\fP 1.25i
+Specifies the procedure to be called whenever
+the current value of the selection is requested.
+.IP \fIlose_callback\fP 1.25i
+Specifies the procedure to be called whenever
+the widget has lost selection ownership, or NULL if the
+owner is not interested in being notified.
+.IP \fIdone_callback\fP 1.25i
+Specifies the procedure called after the
+requestor has received the entire selection, or NULL if
+the owner is not interested in being notified.
+.IP \fIcancel_callback\fP 1.25i
+Specifies the callback procedure to be called
+when a selection request aborts because a timeout expires,
+or NULL if the owner is not interested in being notified.
+.IP \fIclient_data\fP 1.25i
+Specifies the argument to be passed to each of
+the callback procedures when they are called.
+.LP
+.eM
+The
+.PN XtOwnSelectionIncremental
+procedure informs the \*(xI
+incremental selection mechanism that the specified widget wishes to
+own the selection.  It returns
+.PN True
+if the specified widget successfully becomes the selection owner or
+.PN False
+otherwise.
+For more information about \fIselection\fP, \fItarget\fP, and
+\fItime\fP, see Section 2.6 in the \fI\*(xC\fP.
+.LP
+If a done_callback procedure is specified, the client owns the storage allocated
+for passing the value to the \*(xI.  If \fIdone_callback\fP is NULL,
+the convert_callback procedure must allocate storage using
+.PN XtMalloc ,
+.PN XtRealloc ,
+or
+.PN XtCalloc ,
+and the final value specified is freed by the
+\*(xI when the transfer is complete.  After a selection transfer
+has started, only one of the done_callback or cancel_callback
+procedures is invoked to indicate completion of the transfer.
+.LP
+The lose_callback procedure does not indicate completion of any in-progress
+transfers; it is invoked at the time a
+.PN SelectionClear
+event is dispatched regardless of any active transfers, which are still
+expected to continue.
+.LP
+A widget that becomes the selection owner using
+.PN XtOwnSelectionIncremental
+may use
+.PN XtDisownSelection
+to relinquish selection ownership.
+
+.NH 3
+Setting and Retrieving Selection Target Parameters
+.XS
+\*(SN Setting and Retrieving Selection Target Parameters
+.XE
+.LP
+To specify target parameters for a selection request with a single target,
+use
+.PN XtSetSelectionParameters .
+.LP
+.IN "XtSetSelectionParameters" "" "@DEF@"
+.sM
+.FD 0
+void XtSetSelectionParameters(\fIrequestor\fP, \fIselection\fP, \fItype\fP, \
+\fIvalue\fP, \fIlength\fP, \fIformat\fP)
+.br
+      Widget \fIrequestor\fP;
+.br
+      Atom \fIselection\fP;
+.br
+      Atom \fItype\fP;
+.br
+      XtPointer \fIvalue\fP;
+.br
+      unsigned long \fIlength\fP;
+.br
+      int \fIformat\fP;
+.FN
+.IP \fIrequestor\fP 1i
+Specifies the widget making the request.  \*(cI
+.IP \fIselection\fP 1i
+Specifies the atom that names the selection.
+.IP \fItype\fP 1i
+Specifies the type of the property in which the parameters are passed.
+.IP \fIvalue\fP 1i
+Specifies a pointer to the parameters.
+.IP \fIlength\fP 1i
+Specifies the number of elements containing data in \fIvalue\fP,
+each element of a size indicated by \fIformat\fP.
+.IP \fIformat\fP 1i
+Specifies the size in bits of the data in the elements of \fIvalue\fP.
+.LP
+The specified parameters are copied and stored in a new property 
+of the specified type and format on the requestor's window.  To initiate
+a selection request with a target and these parameters, a subsequent
+call to 
+.PN XtGetSelectionValue
+or to
+.PN XtGetSelectionValueIncremental
+specifying the same requestor widget and selection atom will generate a
+.PN ConvertSelection
+request referring to the property containing the parameters.  If 
+.PN XtSetSelectionParameters
+is called more than once with the same widget and selection without
+a call to specify a request, the most recently specified parameters
+are used in the subsequent request.
+.LP
+.eM
+The possible values of \fIformat\fP are 8, 16, or 32.  If the format is 8,
+the elements of \fIvalue\fP are assumed to be sizeof(char);
+if 16, sizeof(short); if 32, sizeof(long).
+.LP
+To generate a MULTIPLE
+target request with parameters for any of the multiple targets of the
+selection request, precede individual calls to
+.PN XtGetSelectionValue
+and
+.PN XtGetSelectionValueIncremental
+with corresponding individual calls to
+.PN XtSetSelectionParameters ,
+and enclose these all within 
+.PN XtCreateSelectionRequest
+and
+.PN XtSendSelectionRequest.  
+.PN XtGetSelectionValues
+and
+.PN XtGetSelectionValuesIncremental
+cannot be used to make selection requests with parameterized targets.
+.sp
+.LP
+To retrieve any target parameters needed to perform a selection conversion,
+the selection owner calls 
+.PN XtGetSelectionParameters .
+.LP
+.IN "XtGetSelectionParameters" "" "@DEF@"
+.sM
+.FD 0
+void XtGetSelectionParameters(\fIowner\fP, \fIselection\fP, \
+\fIrequest_id\fP, \fItype_return\fP, \fIvalue_return\fP,
+                                                 \fIlength_return\fP, \
+\fIformat_return\fP)
+.br
+      Widget \fIowner\fP;
+.br
+      Atom \fIselection\fP;
+.br
+      XtRequestId \fIrequest_id\fP;
+.br
+      Atom *\fItype_return\fP;
+.br
+      XtPointer *\fIvalue_return\fP;
+.br
+      unsigned long *\fIlength_return\fP;
+.br
+      int *\fIformat_return\fP;
+.FN
+.IP \fIowner\fP 1i
+Specifies the widget that owns the specified selection.
+.IP \fIselection\fP 1i
+Specifies the selection being processed.
+.IP \fIrequest_id\fP 1i
+Specifies the requestor id in the case of incremental selections,
+or NULL in the case of atomic transfers.
+.IP \fItype_return\fP 1i
+Specifies a pointer to an atom in which the property type
+of the parameters is stored.
+.IP \fIvalue_return\fP 1i
+Specifies a pointer into which a pointer to the parameters is to be stored.
+A NULL is stored if no parameters accompany the request.
+.IP \fIlength_return\fP 1i
+Specifies a pointer into which the number of data elements
+in \fIvalue_return\fP of size indicated by \fIformat_return\fP are stored.
+.IP \fIformat_return\fP 1i
+Specifies a pointer into which the size in bits of the parameter data
+in the elements of \fIvalue\fP is stored.
+.LP
+.eM
+.PN XtGetSelectionParameters
+may be called only from within an
+.PN XtConvertSelectionProc
+or from within the first call to an 
+.PN XtConvertSelectionIncrProc
+with a new request_id.
+.LP
+It is the responsibility of the caller to free the returned parameters using
+.PN XtFree
+when the parameters are no longer needed.
+
+.NH 3
+Generating MULTIPLE Requests
+.XS
+\*(SN Generating MULTIPLE Requests
+.XE
+.LP
+To have the \*(xI bundle multiple calls to make selection requests into
+a single request using a \s-1MULTIPLE\s+1 target, use 
+.PN XtCreateSelectionRequest
+and
+.PN XtSendSelectionRequest .
+.LP
+.IN "XtCreateSelectionRequest" "" "@DEF@"
+.sM
+.FD 0
+void XtCreateSelectionRequest(\fIrequestor\fP, \fIselection\fP)
+.br
+      Widget \fIrequestor\fP;
+.br
+      Atom \fIselection\fP;
+.FN
+.IP \fIrequestor\fP 1i
+Specifies the widget making the request.  \*(cI
+.IP \fIselection\fP 1i
+Specifies the particular selection desired.
+.LP
+.eM
+When 
+.PN XtCreateSelectionRequest
+is called, subsequent calls to 
+.PN XtGetSelectionValue ,
+.PN XtGetSelectionValueIncremental ,
+.PN XtGetSelectionValues ,
+and
+.PN XtGetSelectionValuesIncremental ,
+with the requestor and selection as specified to 
+.PN XtCreateSelectionRequest ,
+are bundled into a single selection request with
+multiple targets.  The request is made by calling 
+.PN XtSendSelectionRequest .
+.LP
+.IN "XtSendSelectionRequest" "" "@DEF@"
+.sM
+.FD 0
+void XtSendSelectionRequest(\fIrequestor\fP, \fIselection\fP, \fItime\fP)
+.br
+      Widget \fIrequestor\fP;
+.br
+      Atom \fIselection\fP;
+.br
+      Time \fItime\fP;
+.FN
+.IP \fIrequestor\fP 1i
+Specifies the widget making the request.  \*(cI
+.IP \fIselection\fP 1i
+Specifies the particular selection desired.
+.IP \fItime\fP 1i
+Specifies the timestamp that indicates when the selection request was
+initiated.  The value 
+.PN CurrentTime
+is not acceptable.
+.LP
+.eM
+When 
+.PN XtSendSelectionRequest
+is called with a value of \fIrequestor\fP and \fIselection\fP matching
+a previous call to 
+.PN XtCreateSelectionRequest ,
+a selection request is sent to the selection owner.
+If a single target request is queued, that request is made.
+If multiple targets are queued, they are bundled into a single request
+with a target of MULTIPLE using the specified timestamp.
+As the values are returned, the callbacks specified in
+.PN XtGetSelectionValue ,
+.PN XtGetSelectionValueIncremental ,
+.PN XtGetSelectionValues ,
+and
+.PN XtGetSelectionValueIncremental
+are invoked.
+.LP
+Multi-threaded applications should lock the application context before
+calling
+.PN XtCreateSelectionRequest
+and release the lock after calling
+.PN XtSendSelectionRequest
+to ensure that the thread assembling the request is safe from interference
+by another thread assembling a different request naming the same widget
+and selection.
+.sp
+.LP
+To relinquish the composition of a MULTIPLE request without sending it, use
+.PN XtCancelSelectionRequest .
+.LP
+.IN "XtCancelSelectionRequest" "" "@DEF@"
+.sM
+.FD 0
+void XtCancelSelectionRequest(\fIrequestor\fP, \fIselection\fP)
+.br
+      Widget \fIrequestor\fP;
+.br
+      Atom \fIselection\fP;
+.FN
+.IP \fIrequestor\fP 1i
+Specifies the widget making the request.  \*(cI
+.IP \fIselection\fP 1i
+Specifies the particular selection desired.
+.LP
+.eM
+When
+.PN XtCancelSelectionRequest
+is called, any requests queued since the last call to
+.PN XtCreateSelectionRequest
+for the same widget and selection are discarded
+and any resources reserved are released.
+A subsequent call to
+.PN XtSendSelectionRequest
+will not result in any request being made.
+Subsequent calls to
+.PN XtGetSelectionValue ,
+.PN XtGetSelectionValues ,
+.PN XtGetSelectionValueIncremental ,
+or
+.PN XtGetSelectionValuesIncremental
+will not be deferred.
+
+.NH 3
+Auxiliary Selection Properties
+.XS
+\*(SN Auxiliary Selection Properties
+.XE
+.LP
+Certain uses of parameterized selections require clients to name
+other window properties within a selection parameter.  To permit
+reuse of temporary property names in these circumstances and
+thereby reduce the number of unique atoms created in the server,
+the \*(xI provides two interfaces for acquiring temporary property names.
+.LP
+To acquire a temporary property name atom for use in a selection
+request, the client may call
+.PN XtReservePropertyAtom .
+.LP
+.IN "XtReservePropertyAtom" "" "@DEF@"
+.sM
+.FD 0
+Atom XtReservePropertyAtom(\fIw\fP)
+.br
+      Widget \fIw\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget making a selection request.
+.LP
+.eM
+.PN XtReservePropertyAtom
+returns an atom that may be used as a property name during selection
+requests involving the specified widget. 
+As long as the atom remains reserved, it is unique with respect to all
+other reserved atoms for the widget.
+.LP
+To return a temporary property name atom for reuse and to delete
+the property named by that atom, use
+.PN XtReleasePropertyAtom .
+.LP
+.IN "XtReleasePropertyAtom" "" "@DEF@"
+.sM
+.FD 0
+void XtReleasePropertyAtom(\fIw\fP, \fIatom\fP)
+.br
+      Widget \fIw\fP;
+.br
+      Atom \fIatom\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget used to reserve the property name atom.
+.IP \fIatom\fP 1i
+Specifies the property name atom returned by
+.PN XtReservePropertyAtom
+that is to be released for reuse.
+.LP
+.eM
+.PN XtReleasePropertyAtom
+marks the specified property name atom as
+no longer in use and ensures that any property having that name
+on the specified widget's window is deleted.  If \fIatom\fP does not
+specify a value returned by
+.PN XtReservePropertyAtom
+for the specified widget, the results are undefined.
+
+.NH 3
+Retrieving the Most Recent Timestamp
+.XS
+\*(SN Retrieving the Most Recent Timestamp
+.XE
+.LP
+To retrieve the timestamp from the most recent call to
+.PN XtDispatchEvent
+that contained a timestamp, use
+.PN XtLastTimestampProcessed .
+.LP
+.IN "XtLastTimestampProcessed" "" "@DEF@"
+.sM
+.FD 0
+Time XtLastTimestampProcessed(\fIdisplay\fP)
+.br
+      Display *\fIdisplay\fP;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies an open display connection.
+.LP
+.eM
+If no
+.PN KeyPress ,
+.PN KeyRelease ,
+.PN ButtonPress ,
+.PN ButtonRelease ,
+.PN MotionNotify ,
+.PN EnterNotify ,
+.PN LeaveNotify ,
+.PN PropertyNotify ,
+or
+.PN SelectionClear
+event has yet been passed to
+.PN XtDispatchEvent
+for the specified display,
+.PN XtLastTimestampProcessed
+returns zero.
+
+.NH 3
+Retrieving the Most Recent Event
+.XS
+\*(SN Retrieving the Most Recent Event
+.XE
+.LP
+To retrieve the event from the most recent call to
+.PN XtDispatchEvent
+for a specific display, use
+.PN XtLastEventProcessed .
+.LP
+.IN "XtLastEventProcessed" "" "@DEF@"
+.sM
+.FD 0
+XEvent *XtLastEventProcessed(\fIdisplay\fP)
+.br
+      Display *\fIdisplay\fP;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the display connection from which to retrieve the event.
+.LP
+.eM
+Returns the last event passed to
+.PN XtDispatchEvent
+for the specified display.  Returns NULL if there is no such event.
+The client must not modify the contents of the returned event.
+
+.NH 2
+Merging Exposure Events into a Region
+.XS
+\*(SN Merging Exposure Events into a Region
+.XE
+.LP
+The \*(xI provide an
+.PN XtAddExposureToRegion
+utility function that merges
+.PN Expose
+and
+.PN GraphicsExpose
+events into a region for clients to process at once
+rather than processing individual rectangles.
+For further information about regions,
+see Section 16.5 in \fI\*(xL\fP.
+.sp
+.LP
+To merge
+.PN Expose
+and
+.PN GraphicsExpose
+events into a region, use
+.PN XtAddExposureToRegion .
+.LP
+.IN "XtAddExposureToRegion" "" "@DEF@"
+.sM
+.FD 0
+void XtAddExposureToRegion(\fIevent\fP, \fIregion\fP)
+.br
+     XEvent *\fIevent\fP;
+.br
+     Region \fIregion\fP;
+.FN
+.IP \fIevent\fP 1i
+Specifies a pointer to the
+.PN Expose
+or
+.PN GraphicsExpose
+event.
+.IP \fIregion\fP 1i
+Specifies the region object (as defined in
+.Pn < X11/Xutil.h >).
+.LP
+.eM
+The
+.PN XtAddExposureToRegion
+function computes the union of the rectangle defined by the exposure
+event and the specified region.
+Then it stores the results back in \fIregion\fP.
+If the event argument is not an
+.PN Expose
+or
+.PN GraphicsExpose
+event,
+.PN XtAddExposureToRegion
+returns without an error and without modifying \fIregion\fP.
+.LP
+This function is used by the exposure compression mechanism;
+see Section 7.9.3.
+
+.NH 2
+Translating Widget Coordinates
+.XS
+\fB\*(SN Translating Widget Coordinates\fP
+.XE
+.LP
+To translate an x-y coordinate pair from widget coordinates to root
+window absolute coordinates, use
+.PN XtTranslateCoords .
+.LP
+.IN "XtTranslateCoords" "" "@DEF@"
+.sM
+.FD 0
+void XtTranslateCoords(\fIw\fP, \fIx\fP, \fIy\fP, \fIrootx_return\fP, \
+\fIrooty_return\fP)
+.br
+      Widget \fIw\fP;
+.br
+      Position \fIx\fP, \fIy\fP;
+.br
+      Position *\fIrootx_return\fP, *\fIrooty_return\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the widget.  \*(rI
+.IP \fIx\fP 1i
+.br
+.ns
+.IP \fIy\fP 1i
+Specify the widget-relative x and y coordinates.
+.IP \fIrootx_return\fP 1i
+.br
+.ns
+.IP \fIrooty_return\fP 1i
+Return the root-relative x and y coordinates.
+.LP
+.eM
+While
+.PN XtTranslateCoords
+is similar to the Xlib
+.PN XTranslateCoordinates 
+function, it does not generate a server request because all the required
+information already is in the widget's data structures.
+
+.NH 2
+Translating a Window to a Widget
+.XS
+\fB\*(SN Translating a Window to a Widget\fP
+.XE
+.LP
+To translate a given window and display pointer into a widget instance, use
+.PN XtWindowToWidget .
+.LP
+.IN "XtWindowToWidget" "" "@DEF@"
+.sM
+.FD 0
+Widget XtWindowToWidget(\fIdisplay\fP, \fIwindow\fP)
+.br
+      Display *\fIdisplay\fP;
+.br
+      Window \fIwindow\fP;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the display on which the window is defined.
+.IP \fIwindow\fP 1i
+Specifies the drawable for which you want the widget.
+.LP
+.eM
+If there is a realized widget whose window is the specified drawable on
+the specified \fIdisplay\fP,
+.PN XtWindowToWidget
+returns that widget.
+If not and if the drawable has been associated with a widget through
+.PN XtRegisterDrawable ,
+.PN XtWindowToWidget
+returns the widget associated with the drawable.  In other cases it
+returns NULL.
+
+.NH 2
+Handling Errors
+.XS
+\fB\*(SN Handling Errors\fP
+.XE
+.LP
+The \*(xI allow a client to register procedures that are called
+whenever a fatal or nonfatal error occurs.
+These facilities are intended for both error reporting and logging
+and for error correction or recovery.
+.LP
+Two levels of interface are provided: 
+.IP \(bu 5
+A high-level interface that takes an error
+name and class and retrieves the error message text from
+an error resource database.
+.IP \(bu 5
+A low-level interface that takes a simple string to display.
+.LP
+The high-level functions construct a string to pass to the lower-level
+interface.
+The strings may be specified in application code and are
+overridden by the contents of an external systemwide file,
+the ``error database file''.  The location and name of this file are
+implementation-dependent.
+.NT
+The application-context-specific error handling is not
+implemented on many systems, although the interfaces are
+always present.
+Most implementations will have just one set of error handlers
+for all application contexts within a process.
+If they are set for different application contexts,
+the ones registered last will prevail.
+.NE
+.sp
+.LP
+To obtain the error database (for example, to merge with
+an application- or widget-specific database), use
+.PN XtAppGetErrorDatabase .
+.LP
+.IN "XtAppGetErrorDatabase" "" "@DEF@"
+.sM
+.FD 0
+XrmDatabase *XtAppGetErrorDatabase(\^\fIapp_context\fP\^)
+.br
+     XtAppContext \fIapp_context\fP;
+.FN
+.IP \fIapp_context\fP 1i
+Specifies the application context.
+.LP
+.eM
+The
+.PN XtAppGetErrorDatabase
+function returns the address of the error database.
+The \*(xI do a lazy binding of the error database and do not merge in the
+database file until the first call to
+.PN XtAppGetErrorDatabaseText .
+.LP
+For a complete listing of all errors and warnings 
+that can be generated by the \*(xI, see Appendix D.
+.sp
+.LP
+The high-level error and warning handler procedure pointers are of type
+.PN XtErrorMsgHandler .
+.LP
+.IN "XtErrorMsgHandler" "" "@DEF@"
+.sM
+.FD 0
+typedef void (*XtErrorMsgHandler)(String, String, String, String, \
+String*, Cardinal*);
+.br
+    String \fIname\fP;
+.br
+    String \fItype\fP;
+.br
+    String \fIclass\fP;
+.br
+    String \fIdefaultp\fP;
+.br
+    String *\fIparams\fP;
+.br
+    Cardinal *\fInum_params\fP;
+.FN
+.IP \fIname\fP 1i
+Specifies the name to be concatenated with the specified type to form 
+the resource name of the error message.
+.IP \fItype\fP 1i
+Specifies the type to be concatenated with the name to form the 
+resource name of the error message.
+.IP \fIclass\fP 1i
+Specifies the resource class of the error message.
+.IP \fIdefaultp\fP 1i
+Specifies the default message to use if no error database entry is found.
+.IP \fIparams\fP 1i
+Specifies a pointer to a list of parameters to be substituted in the message.
+.IP \fInum_params\fP 1i
+Specifies the number of entries in \fIparams\fP.
+.LP
+.eM
+The specified name can be a general kind of error, 
+like ``invalidParameters'' or ``invalidWindow'', 
+and the specified type gives extra information
+such as the name of the routine in which the error was detected.
+Standard 
+.PN printf 
+notation is used to substitute the parameters into the message.
+.sp
+.LP
+An error message handler can obtain the error database text for an
+error or a warning by calling
+.PN XtAppGetErrorDatabaseText .
+.LP
+.IN "XtAppGetErrorDatabaseText" "" "@DEF@"
+.sM
+.FD 0
+void XtAppGetErrorDatabaseText(\fIapp_context\fP, \fIname\fP, \fItype\fP, \fIclass\fP, \fIdefault\fP, \fIbuffer_return\fP, \fInbytes\fP, \fIdatabase\fP)
+.br
+      XtAppContext \fIapp_context\fP;
+.br
+      String \fIname\fP, \fItype\fP, \fIclass\fP;
+.br
+      String \fIdefault\fP;
+.br
+      String \fIbuffer_return\fP;
+.br
+      int \fInbytes\fP;
+.br
+      XrmDatabase \fIdatabase\fP;
+.FN
+.IP \fIapp_context\fP 1i
+Specifies the application context.
+.IP \fIname\fP 1i
+.br
+.ns
+.IP \fItype\fP 1i
+Specify the name and type concatenated to form the resource name 
+of the error message.
+.IP \fIclass\fP 1i
+Specifies the resource class of the error message.
+.IP \fIdefault\fP 1i
+Specifies the default message to use if an error database entry is not found.
+.IP \fIbuffer_return\fP 1i
+Specifies the buffer into which the error message is to be returned.
+.IP \fInbytes\fP 1i
+Specifies the size of the buffer in bytes.
+.IP \fIdatabase\fP 1i
+Specifies the name of the alternative database to be used,
+or NULL if the application context's error database is to be used.
+.LP
+.eM
+The
+.PN XtAppGetErrorDatabaseText
+returns the appropriate message from the error database
+or returns the specified default message if one is not found in the
+error database.
+To form the full resource name and class when querying the database,
+the \fIname\fP and \fItype\fP are concatenated with a single ``.''
+between them and the \fIclass\fP is concatenated with itself with a
+single ``.'' if it does not already contain a ``.''.
+.sp
+.LP
+To return the application name and class as passed to
+.PN XtDisplayInitialize
+for a particular Display, use
+.PN XtGetApplicationNameAndClass .
+.LP
+.IN "XtGetApplicationNameAndClass" "" "@DEF@"
+.sM
+.FD 0
+void XtGetApplicationNameAndClass(\fIdisplay\fP, \fIname_return\fP, \
+\fIclass_return\fP)
+.br
+      Display* \fIdisplay\fP;
+.br
+      String* \fIname_return\fP;
+.br
+      String* \fIclass_return\fP;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies an open display connection that has been initialized with
+.PN XtDisplayInitialize .
+.IP \fIname_return\fP 1i
+Returns the application name.
+.IP \fIclass_return\fP 1i
+Returns the application class.
+.LP
+.eM
+.PN XtGetApplicationNameAndClass
+returns the application name and class passed to
+.PN XtDisplayInitialize
+for the specified display.  If the display was
+never initialized or has been closed, the result is undefined.  The
+returned strings are owned by the \*(xI and must not be modified
+or freed by the caller.
+.sp
+.LP
+To register a procedure to be called on fatal error conditions, use
+.PN XtAppSetErrorMsgHandler .
+.LP
+.IN "XtAppSetErrorMsgHandler" "" "@DEF@"
+.sM
+.FD 0
+XtErrorMsgHandler XtAppSetErrorMsgHandler(\fIapp_context\fP, \fImsg_handler\fP)
+.br
+      XtAppContext \fIapp_context\fP;
+.br
+      XtErrorMsgHandler \fImsg_handler\fP;
+.FN
+.IP \fIapp_context\fP 1i
+Specifies the application context.
+.IP \fImsg_handler\fP 1i
+Specifies the new fatal error procedure, which should not return.
+.LP
+.eM
+.PN XtAppSetErrorMsgHandler
+returns a pointer to the previously
+installed high-level fatal error handler.
+The default high-level fatal error handler provided by the \*(xI is named
+.PN _XtDefaultErrorMsg
+.IN "_XtDefaultErrorMsg" "" "@DEF"
+and constructs a string from the error resource database and calls
+.PN XtError .
+Fatal error message handlers should not return.
+If one does,
+subsequent \*(xI behavior is undefined.
+.sp
+.LP
+To call the high-level error handler, use
+.PN XtAppErrorMsg .
+.LP
+.IN "XtAppErrorMsg" "" "@DEF@"
+.sM
+.FD 0
+void XtAppErrorMsg(\fIapp_context\fP, \fIname\fP, \fItype\fP, \fIclass\fP, \
+\fIdefault\fP, \ \fIparams\fP, \fInum_params\fP)
+.br
+      XtAppContext \fIapp_context\fP;
+.br
+      String \fIname\fP;
+.br
+      String \fItype\fP;
+.br
+      String \fIclass\fP;
+.br
+      String \fIdefault\fP;
+.br
+      String *\fIparams\fP;
+.br
+      Cardinal *\fInum_params\fP;
+.FN
+.IP \fIapp_context\fP 1i
+Specifies the application context.
+.IP \fIname\fP 1i
+Specifies the general kind of error.
+.IP \fItype\fP 1i
+Specifies the detailed name of the error.
+.IP \fIclass\fP 1i
+Specifies the resource class.
+.IP \fIdefault\fP 1i
+Specifies the default message to use if an error database entry is not found.
+.IP \fIparams\fP 1i
+Specifies a pointer to a list of values to be stored in the message.
+.IP \fInum_params\fP 1i
+Specifies the number of entries in \fIparams\fP.
+.LP
+.eM
+The \*(xI internal errors all have class
+``XtToolkitError''.
+.sp
+.LP
+To register a procedure to be called on nonfatal error conditions, use
+.PN XtAppSetWarningMsgHandler .
+.LP
+.IN "XtAppSetWarningMsgHandler" "" "@DEF@"
+.sM
+.FD 0
+XtErrorMsgHandler XtAppSetWarningMsgHandler(\fIapp_context\fP, \fImsg_handler\fP)
+.br
+      XtAppContext \fIapp_context\fP;
+.br
+      XtErrorMsgHandler \fImsg_handler\fP;
+.FN
+.IP \fIapp_context\fP 1i
+Specifies the application context.
+.IP \fImsg_handler\fP 1i
+Specifies the new nonfatal error procedure, which usually returns.
+.LP
+.eM
+.PN XtAppSetWarningMsgHandler
+returns a pointer to the previously
+installed high-level warning handler.
+The default high-level warning handler provided by the \*(xI is named
+.PN _XtDefaultWarningMsg
+.IN "_XtDefaultWarningMsg" "" "@DEF@"
+and constructs a string
+from the error resource database and calls
+.PN XtWarning .
+.sp
+.LP
+To call the installed high-level warning handler, use
+.PN XtAppWarningMsg .
+.LP
+.IN "XtAppWarningMsg" "" "@DEF@"
+.sM
+.FD 0
+void XtAppWarningMsg(\fIapp_context\fP, \fIname\fP, \fItype\fP, \fIclass\fP, \fIdefault\fP, \fIparams\fP, \fInum_params\fP)
+.br
+      XtAppContext \fIapp_context\fP;
+.br
+      String \fIname\fP;
+.br
+      String \fItype\fP;
+.br
+      String \fIclass\fP;
+.br
+      String \fIdefault\fP;
+.br
+      String *\fIparams\fP;
+.br
+      Cardinal *\fInum_params\fP;
+.FN
+.IP \fIapp_context\fP 1i
+Specifies the application context.
+.IP \fIname\fP 1i
+Specifies the general kind of error.
+.IP \fItype\fP 1i
+Specifies the detailed name of the error.
+.IP \fIclass\fP 1i
+Specifies the resource class.
+.IP \fIdefault\fP 1i
+Specifies the default message to use if an error database entry is not found.
+.IP \fIparams\fP 1i
+Specifies a pointer to a list of values to be stored in the message.
+.IP \fInum_params\fP 1i
+Specifies the number of entries in \fIparams\fP.
+.LP
+.eM
+The \*(xI internal warnings all have class
+``XtToolkitError''.
+.sp
+.LP
+The low-level error and warning handler procedure pointers are of type
+.PN XtErrorHandler .
+.LP
+.IN "XtErrorHandler" "" "@DEF@"
+.sM
+.FD 0
+typedef void (*XtErrorHandler)(String);
+.br
+      String \fImessage\fP;
+.FN
+.IP \fImessage\fP 1i
+Specifies the error message.
+.LP
+.eM
+The error handler should display the message string in some appropriate fashion.
+.sp
+.LP
+To register a procedure to be called on fatal error conditions, use
+.PN XtAppSetErrorHandler .
+.LP
+.IN "XtAppSetErrorHandler" "" "@DEF@"
+.sM
+.FD 0
+XtErrorHandler XtAppSetErrorHandler(\fIapp_context\fP, \fIhandler\fP)
+.br
+      XtAppContext \fIapp_context\fP;
+.br
+      XtErrorHandler \fIhandler\fP;
+.FN
+.IP \fIapp_context\fP 1i
+Specifies the application context.
+.IP \fIhandler\fP 1i
+Specifies the new fatal error procedure, which should not return.
+.LP
+.eM
+.PN XtAppSetErrorHandler
+returns a pointer to the previously installed
+low-level fatal error handler.
+The default low-level error handler provided by the \*(xI is
+.PN _XtDefaultError .
+.IN "_XtDefaultError" "" "@DEF@"
+On POSIX-based systems,
+it prints the message to standard error and terminates the application.
+Fatal error message handlers should not return.
+If one does,
+subsequent \*(xI behavior is undefined.
+.sp
+.LP
+To call the installed fatal error procedure, use
+.PN XtAppError .
+.LP
+.IN "XtAppError" "" "@DEF@"
+.sM
+.FD 0
+void XtAppError(\fIapp_context\fP, \fImessage\fP)
+.br
+      XtAppContext \fIapp_context\fP;
+.br
+      String \fImessage\fP;
+.FN
+.IP \fIapp_context\fP 1i
+Specifies the application context.
+.IP \fImessage\fP 1i
+Specifies the message to be reported.
+.LP
+.eM
+Most programs should use
+.PN XtAppErrorMsg ,
+not
+.PN XtAppError ,
+to provide for customization and internationalization of error messages.
+.sp
+.LP
+To register a procedure to be called on nonfatal error conditions, use
+.PN XtAppSetWarningHandler .
+.LP
+.IN "XtAppSetWarningHandler" "" "@DEF@"
+.sM
+.FD 0
+XtErrorHandler XtAppSetWarningHandler(\fIapp_context\fP, \fIhandler\fP)
+.br
+      XtAppContext \fIapp_context\fP;
+.br
+      XtErrorHandler \fIhandler\fP;
+.FN
+.IP \fIapp_context\fP 1i
+Specifies the application context.
+.IP \fIhandler\fP 1i
+Specifies the new nonfatal error procedure, which usually returns.
+.LP
+.eM
+.PN XtAppSetWarningHandler
+returns a pointer to the previously installed
+low-level warning handler.
+The default low-level warning handler provided by the \*(xI is
+.PN _XtDefaultWarning .
+.IN "_XtDefaultWarning" "" "@DEF@"
+On POSIX-based systems,
+it prints the message to standard error and returns to the caller.
+.sp
+.LP
+To call the installed nonfatal error procedure, use
+.PN XtAppWarning .
+.LP
+.IN "XtAppWarning" "" "@DEF@"
+.sM
+.FD 0
+void XtAppWarning(\fIapp_context\fP, \fImessage\fP)
+.br
+      XtAppContext \fIapp_context\fP;
+.br
+      String \fImessage\fP;
+.FN
+.IP \fIapp_context\fP 1i
+Specifies the application context.
+.IP \fImessage\fP 1i
+Specifies the nonfatal error message to be reported.
+.LP
+.eM
+Most programs should use
+.PN XtAppWarningMsg ,
+not
+.PN XtAppWarning ,
+to provide for customization and internationalization of warning messages.
+
+.NH 2
+Setting WM_COLORMAP_WINDOWS
+.XS
+\fB\*(SN Setting WM_COLORMAP_WINDOWS\fP
+.XE
+.LP
+A client may set the value of the \s-1WM_COLORMAP_WINDOWS\s+1
+.IN "WM_COLORMAP_WINDOWS" "" "@DEF@"
+property on a widget's window by calling
+.PN XtSetWMColormapWindows .
+.LP
+.IN "XtSetWMColormapWindows" "" "@DEF@"
+.sM
+.FD 0
+void XtSetWMColormapWindows(\fIwidget\fP, \fIlist\fP, \fIcount\fP)
+.br
+      Widget \fIwidget\fP;
+.br
+      Widget* \fIlist\fP;
+.br
+      Cardinal \fIcount\fP;
+.FN
+.IP \fIwidget\fP 1i
+Specifies the widget on whose window the \s-1WM_COLORMAP_WINDOWS\s+1
+property is stored.  \*(cI
+.IP \fIlist\fP 1i
+Specifies a list of widgets whose windows are potentially to be
+listed in the \s-1WM_COLORMAP_WINDOWS\s+1 property.
+.IP \fIcount\fP 1i
+Specifies the number of widgets in \fIlist\fP.
+.LP
+.eM
+.PN XtSetWMColormapWindows
+returns immediately if \fIwidget\fP is not realized or if \fIcount\fP is 0.
+Otherwise,
+.PN XtSetWMColormapWindows
+constructs an ordered list of windows
+by examining each widget in \fIlist\fP in turn and
+ignoring the widget if it is not realized, or
+adding the widget's window to the window list if the widget is realized
+and if its colormap resource is different from the colormap
+resources of all widgets whose windows are already on the window list.
+.LP
+Finally,
+.PN XtSetWMColormapWindows
+stores the resulting window list in the \s-1WM_COLORMAP_WINDOWS\s+1
+property on the specified widget's window.
+Refer to Section 4.1.8 in the \fI\*(xC\fP for details of
+the semantics of the \s-1WM_COLORMAP_WINDOWS\s+1 property.
+
+.NH 2
+Finding File Names
+.XS
+\fB\*(SN Finding File Names\fP
+.XE
+.LP
+The \*(xI provide procedures to look for a file by name, allowing
+string substitutions in a list of file specifications.  Two
+routines are provided for this:
+.PN XtFindFile
+and
+.PN XtResolvePathname .
+.PN XtFindFile
+uses an arbitrary set of client-specified substitutions, and
+.PN XtResolvePathname
+uses a set of standard substitutions corresponding
+to the \fIX/Open Portability Guide\fP language localization conventions.
+Most applications should use
+.PN XtResolvePathname .
+.LP
+A string substitution is defined by a list of
+.PN Substitution
+.IN "Substitution" "" "@DEF@"
+entries.
+.LP
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	char match;
+	String substitution;
+} SubstitutionRec, *Substitution;
+.De
+.eM
+.LP
+File name evaluation is handled in an operating-system-dependent
+fashion by an
+.PN XtFilePredicate
+.IN "XtFilePredicate" "" "@DEF@"
+procedure.
+.LP
+.sM
+.FD 0
+typedef Boolean (*XtFilePredicate)(String);
+.br
+      String \fIfilename\fP;
+.FN
+.IP \fIfilename\fP 1i
+Specifies a potential filename.
+.LP
+.eM
+A file predicate procedure is called with a string that is
+potentially a file name.  It should return
+.PN True 
+if this string specifies a file that is appropriate for the intended use and 
+.PN False
+otherwise.
+.sp
+.LP
+To search for a file using substitutions in a path list, use
+.PN XtFindFile .
+.LP
+.IN "XtFindFile" "" "@DEF@"
+.sM
+.FD 0
+String XtFindFile(\fIpath\fP, \fIsubstitutions\fP, \fInum_substitutions\fP, \
+\fIpredicate\fP)
+.br
+      String \fIpath\fP;
+.br
+      Substitution \fIsubstitutions\fP;
+.br
+      Cardinal \fInum_substitutions\fP;
+.br
+      XtFilePredicate \fIpredicate\fP;
+.FN
+.IP \fIpath\fP 1.2i
+Specifies a path of file names, including substitution characters.
+.IP \fIsubstitutions\fP 1.2i
+Specifies a list of substitutions to make into the path.
+.IP \fInum_substitutions\fP 1.2i
+Specifies the number of substitutions passed in.
+.IP \fIpredicate\fP 1.2i
+Specifies a procedure called to judge each potential file name, or NULL.
+.LP
+.eM
+The \fIpath\fP parameter specifies a string that consists of a series of
+potential file names delimited by colons.  Within each name, the
+percent character specifies a string substitution selected by the
+following character.  The character sequence ``%:'' specifies an
+embedded colon that is not a delimiter; the sequence is replaced by a
+single colon.  The character sequence ``%%'' specifies a percent
+character that does not introduce a substitution; the sequence is
+replaced by a single percent character.  If a percent character is
+followed by any other character,
+.PN XtFindFile
+looks through the
+specified \fIsubstitutions\fP for that character in the \fImatch\fP field
+and, if found,
+replaces the percent and match characters with the string in the
+corresponding \fIsubstitution\fP field.  A \fIsubstitution\fP field entry of NULL
+is equivalent to a pointer to an empty string.  If the operating
+system does not interpret multiple embedded name separators in the
+path (i.e., ``/'' in POSIX) the same way as a single separator,
+.PN XtFindFile
+will collapse multiple separators into a single one after performing
+all string substitutions.  Except for collapsing embedded separators,
+the contents of the string substitutions are not interpreted by
+.PN XtFindFile
+and may therefore contain any operating-system-dependent
+characters, including additional name separators.  Each resulting
+string is passed to the predicate procedure until a string is found for
+which the procedure returns
+.PN True ;
+this string is the return value for
+.PN XtFindFile .
+If no string yields a
+.PN True
+return from the predicate,
+.PN XtFindFile
+returns NULL.
+.LP
+If the \fIpredicate\fP parameter is NULL, an internal procedure that checks
+if the file exists, is readable, and is not a directory is used.
+.LP
+It is the responsibility of the caller to free the returned string using
+.PN XtFree
+when it is no longer needed.
+.sp
+.LP
+To search for a file using standard substitutions in a path list, use
+.PN XtResolvePathname .
+.LP
+.IN "XtResolvePathname" "" "@DEF@"
+.sM
+.FD 0
+String XtResolvePathname(\fIdisplay\fP, \fItype\fP, \fIfilename\fP, \fIsuffix\fP, \
+\fIpath\fP, \fIsubstitutions\fP, \fInum_substitutions\fP, \fIpredicate\fP)
+.br
+      Display *\fIdisplay\fP;
+.br
+      String \fItype\fP, \fIfilename\fP, \fIsuffix\fP, \fIpath\fP;
+.br
+      Substitution \fIsubstitutions\fP;
+.br
+      Cardinal \fInum_substitutions\fP;
+.br
+      XtFilePredicate \fIpredicate\fP;
+.FN
+.IP \fIdisplay\fP 1.2i
+Specifies the display to use to find the language for language substitutions.
+.IP \fItype\fP
+.br
+.ns
+.IP \fIfilename\fP
+.br
+.ns
+.IP \fIsuffix\fP 1.2i
+Specify values to substitute into the path.
+.IP \fIpath\fP 1.2i
+Specifies the list of file specifications, or NULL.
+.IP \fIsubstitutions\fP 1.2i
+Specifies a list of additional substitutions to make into the path, or NULL.
+.IP \fInum_substitutions\fP 1.2i
+Specifies the number of entries in \fIsubstitutions\fP.
+.IP \fIpredicate\fP 1.2i
+Specifies a procedure called to judge each potential file name, or NULL.
+.LP
+.eM
+The substitutions specified by
+.PN XtResolvePathname
+are determined from the value of the language string retrieved by
+.PN XtDisplayInitialize
+for the specified display.
+To set the
+language for all applications specify ``*xnlLanguage: \fIlang\fP'' in the
+resource database. 
+.IN "xnlLanguage"
+The format and content of the language string are
+implementation-defined.   One suggested syntax is to compose
+the language string of three parts;  a  ``language  part'',  a
+``territory  part'' and a ``codeset part''.  The manner in which
+this composition is accomplished is implementation-defined,
+and the \*(xI make no interpretation of the parts other
+than to use them in substitutions as described below.
+.LP
+.PN XtResolvePathname
+calls
+.PN XtFindFile
+with the following substitutions
+in addition to any passed by the caller and returns the value returned by
+.PN XtFindFile :
+.IP %N 5
+The value of the \fIfilename\fP parameter, or the application's
+class name if \fIfilename\fP is NULL.
+.IP %T 5
+The value of the \fItype\fP parameter.
+.IP %S 5
+The value of the \fIsuffix\fP parameter.
+.IP %L 5
+The language string associated with the specified display.
+.IP %l 5
+The language part of the display's language string.
+.IP %t 5
+The territory part of the display's language string.
+.IP %c 5
+The codeset part of the display's language string.
+.IP %C 5
+The customization string retrieved from the resource
+database associated with \fIdisplay\fP.
+.IP %D 5
+The value of the implementation-specific default path.
+.LP
+If a path is passed to
+.PN XtResolvePathname ,
+it is passed along to
+.PN XtFindFile .
+If the \fIpath\fP argument is NULL, the value of the
+.PN \s-1XFILESEARCHPATH\s+1
+.IN "XFILESEARCHPATH" "" "@DEF@"
+environment variable is passed to
+.PN XtFindFile .
+If
+.PN \s-1XFILESEARCHPATH\s+1
+is not defined, an implementation-specific default path is used
+that contains at least six entries.  These entries
+must contain the following substitutions:
+
+.nf
+.ta .3i 2i 2.5i
+1.	%C, %N, %S, %T, %L	or	%C, %N, %S, %T, %l, %t, %c
+2.	%C, %N, %S, %T, %l
+3.	%C, %N, %S, %T
+4.	%N, %S, %T, %L	or	%N, %S, %T, %l, %t, %c
+5.	%N, %S, %T, %l
+6.	%N, %S, %T
+.fi
+
+The order of these six entries within the path must be as given above.
+The order and use of substitutions within a given entry
+are implementation-dependent.
+If the path begins
+with a colon, it is preceded by %N%S.  If the path includes two
+adjacent colons, \fB%N%S\fP is inserted between them.
+.LP
+The \fItype\fP parameter is intended to be a category of files, usually
+being translated into a directory in the pathname.  Possible values
+might include ``app-defaults'', ``help'', and ``bitmap''.
+.LP
+The \fIsuffix\fP parameter is intended to be appended to the file name.
+Possible values might include ``.txt'', ``.dat'', and ``.bm''.
+.LP
+A suggested value for the default path on POSIX-based systems is
+.IP
+/usr/lib/X11/%L/%T/%N%C%S:/usr/lib/X11/%l/%T/%N%C%S:\\
+.br
+/usr/lib/X11/%T/%N%C%S:/usr/lib/X11/%L/%T/%N%S:\\
+.br
+/usr/lib/X11/%l/%T/%N%S:/usr/lib/X11/%T/%N%S
+
+.LP
+Using this example, if the user has specified a language, it is
+used as a subdirectory of /usr/lib/X11 that is searched for other
+files.  If the desired file is not found there, the lookup is
+tried again using just the language part of the specification.  If the
+file is not there, it is looked for in /usr/lib/X11.  The \fItype\fP
+parameter is used as a subdirectory of the language directory or of
+/usr/lib/X11, and \fIsuffix\fP is appended to the file name.
+.LP
+The %D substitution allows the addition of path
+elements to the implementation-specific default path, typically to
+allow additional directories to be searched without preventing
+resources in the system directories from being found.  For example, a
+user installing resource files under a directory called ``ourdir''
+might set
+.PN \s-1XFILESEARCHPATH\s+1
+to
+.IP
+%D:ourdir/%T/%N%C:ourdir/%T/%N
+.LP
+The customization string is obtained by querying the resource database
+currently associated with the display (the database returned by
+.PN XrmGetDatabase )
+for the resource \fIapplication_name\fP.customization, class
+\fIapplication_class\fP.Customization, where \fIapplication_name\fP
+and \fIapplication_class\fP are the values returned by
+.PN XtGetApplicationNameAndClass .
+If no value is specified in the database, the empty string is used.
+.LP
+It is the responsibility of the caller to free the returned string using
+.PN XtFree
+when it is no longer needed.
+
+.NH 2
+Hooks for External Agents
+.XS
+\fB\*(SN Hooks for External Agents\fP
+.XE
+.LP
+Applications may register
+functions that are called at a particular control points in the \*(xI.
+These functions are intended to be used to provide notification
+of an \*Q\*(tk event\*U, such as widget creation, to an external agent,
+such as an interactive resource editor, drag-and-drop server, or
+an aid for physically challenged users.
+The control points containing such registration hooks are identified
+in a \*Qhook registration\*U object.
+.LP
+To retrieve the hook registration widget, use
+.PN XtHooksOfDisplay .
+.LP
+.IN "XtHooksOfDisplay" "" "@DEF@"
+.sM
+.FD 0
+Widget XtHooksOfDisplay(\fIdisplay\fP)
+.br
+      Display *\fIdisplay\fP;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the desired display.
+.LP
+.eM
+The class of this object is a private, implementation-dependent
+subclass of
+.PN Object .
+The hook object has no parent.  The resources of this object are 
+the callback lists for hooks and the read-only resources for getting 
+a list of parentless shells.  All of the callback lists are initially 
+empty.  When a display is closed, the hook object associated with it 
+is destroyed. 
+.LP
+The following procedures can be called with the hook registration object
+as an argument:
+.sp
+.IP
+.PN XtAddCallback ,
+.PN XtAddCallbacks ,
+.PN XtRemoveCallback ,
+.PN XtRemoveCallbacks ,
+.PN XtRemoveAllCallbacks ,
+.PN XtCallCallbacks ,
+.PN XtHasCallbacks ,
+.PN XtCallCallbackList
+.IP
+.PN XtClass ,
+.PN XtSuperclass ,
+.PN XtIsSubclass ,
+.PN XtCheckSubclass ,
+.PN XtIsObject ,
+.PN XtIsRectObj ,
+.PN XtIsWidget ,
+.PN XtIsComposite ,
+.PN XtIsConstraint ,
+.PN XtIsShell ,
+.PN XtIsOverrideShell ,
+.PN XtIsWMShell ,
+.PN XtIsVendorShell ,
+.PN XtIsTransientShell ,
+.PN XtIsToplevelShell ,
+.PN XtIsApplicationShell ,
+.PN XtIsSessionShell
+.IP
+.PN XtWidgetToApplicationContext
+.IP
+.PN XtName ,
+.PN XtParent ,
+.PN XtDisplayOfObject ,
+.PN XtScreenOfObject
+.IP
+.PN XtSetValues ,
+.PN XtGetValues ,
+.PN XtVaSetValues ,
+.PN XtVaGetValues
+.sp
+.LP
+
+.NH 3
+Hook Object Resources
+.XS
+\fB\*(SN Hook Object Resources\fP
+.XE
+.LP
+The resource names, classes, and representation types that are specified
+in the hook object resource list are:
+.KS
+.TS
+lw(1.5i) lw(1.5i) lw(2.5i) .
+_
+.sp 6p
+Name	Class	Representation
+.sp 6p
+_
+.sp 6p
+XtNcreateHook	XtCCallback	XtRCallback
+XtNchangeHook	XtCCallback	XtRCallback
+XtNconfigureHook	XtCCallback	XtRCallback
+XtNgeometryHook	XtCCallback	XtRCallback
+XtNdestroyHook	XtCCallback	XtRCallback
+XtNshells	XtCReadOnly	XtRWidgetList
+XtNnumShells	XtCReadOnly	XtRCardinal
+.sp 6p
+_
+.TE
+.KE
+.LP
+Descriptions of each of these resources:
+.LP
+The XtNcreateHook callback list is called from:
+.PN XtCreateWidget ,
+.PN XtCreateManagedWidget ,
+.PN XtCreatePopupShell ,
+.PN XtAppCreateShell ,
+and their corresponding varargs versions.
+.LP
+The \fIcall_data\fP parameter in a createHook callback may be 
+cast to type
+.PN XtCreateHookData .
+.LP
+.IN "XtCreateHookData" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	String   type;
+	Widget   widget;
+	ArgList  args;
+	Cardinal num_args;
+} XtCreateHookDataRec, *XtCreateHookData;
+.De
+.eM
+.LP
+The \fItype\fP is set to
+.PN XtHcreate ,
+\fIwidget\fP is the newly created widget, and \fIargs\fP and \fInum_args\fP
+are the arguments passed to the create function. The callbacks are 
+called before returning from the create function.
+.LP
+The XtNchangeHook callback list is called from:
+.IP
+.PN XtSetValues ,
+.PN XtVaSetValues
+.IP
+.PN XtManageChild ,
+.PN XtManageChildren ,
+.PN XtUnmanageChild ,
+.PN XtUnmanageChildren
+.IP
+.PN XtRealizeWidget ,
+.PN XtUnrealizeWidget
+.IP
+.PN XtAddCallback ,
+.PN XtRemoveCallback ,
+.PN XtAddCallbacks, 
+.PN XtRemoveCallbacks ,
+.PN XtRemoveAllCallbacks
+.IP
+.PN XtAugmentTranslations ,
+.PN XtOverrideTranslations ,
+.PN XtUninstallTranslations
+.IP
+.PN XtSetKeyboardFocus ,
+.PN XtSetWMColormapWindows
+.IP
+.PN XtSetMappedWhenManaged ,
+.PN XtMapWidget ,
+.PN XtUnmapWidget
+.IP
+.PN XtPopup ,
+.PN XtPopupSpringLoaded ,
+.PN XtPopdown
+.LP
+.sp
+.LP
+The \fIcall_data\fP parameter in a changeHook callback may
+be cast to type
+.PN XtChangeHookData .
+.IN "XtChangeHookData" "" "@DFEF@"
+.LP
+.KS
+.sM
+.Ds 0
+.TA .5i 2.5i
+.ta .5i 2.5i
+typedef struct {
+	String  type;
+	Widget  widget;
+	XtPointer event_data;
+	Cardinal num_event_data;
+} XtChangeHookDataRec, *XtChangeHookData;
+.De
+.eM
+.KE
+.LP
+When the changeHook callbacks are called as a result of a call to
+.PN XtSetValues
+or
+.PN XtVaSetValues ,
+\fItype\fP is set to
+.PN XtHsetValues ,
+\fIwidget\fP is the new widget passed to the set_values procedure, and
+\fIevent_data\fP may be cast to type 
+.PN XtChangeHookSetValuesData .
+.IN "XtChangeHookSetValuesData" "" "@DEF@"
+.LP
+.KS
+.sM
+.Ds 0
+.TA .5i 2.5i
+.ta .5i 2.5i
+typedef struct {
+	Widget   old, req;
+	ArgList  args;
+	Cardinal num_args;
+} XtChangeHookSetValuesDataRec, *XtChangeHookSetValuesData;
+.De
+.eM
+.KE
+.LP
+The \fIold\fP, \fIreq\fP, \fIargs\fP, and \fInum_args\fP are the
+parameters passed to the set_values procedure.  The callbacks are called 
+after the set_values and constraint set_values procedures have been called.
+.LP
+When the changeHook callbacks are called as a result of a call to
+.PN XtManageChild
+or
+.PN XtManageChildren ,
+\fItype\fP is set to
+.PN XtHmanageChildren ,
+\fIwidget\fP is the parent, \fIevent_data\fP may be cast to type
+WidgetList and is the list of children being managed, and 
+\fInum_event_data\fP is the length of the widget list.
+The callbacks are called after the children have been managed.
+.LP
+When the changeHook callbacks are called as a result of a call to
+.PN XtUnmanageChild
+or
+.PN XtUnmanageChildren ,
+\fItype\fP is set to
+.PN XtHunmanageChildren ,
+\fIwidget\fP is the parent, \fIevent_data\fP may be cast to type
+WidgetList and is a list of the children being unmanaged, and
+\fInum_event_data\fP is the length of the widget list.
+The callbacks are called after the children have been unmanaged.
+.LP
+The changeHook callbacks are called twice as a result of a call to
+.PN XtChangeManagedSet ,
+once after unmanaging and again after managing.
+When the callbacks are called the first time, \fItype\fP is set to
+.PN XtHunmanageSet , 
+\fIwidget\fP is the parent, \fIevent_data\fP may be cast to type 
+WidgetList and is a list of the children being unmanaged, and 
+\fInum_event_data\fP is the length of the widget list.
+When the callbacks are called the second time, the \fItype\fP is set to
+.PN XtHmanageSet , 
+\fIwidget\fP is the parent, \fIevent_data\fP may be cast to type 
+WidgetList and is a list of the children being managed, and 
+\fInum_event_data\fP is the length of the widget list.
+.LP
+When the changeHook callbacks are called as a result of a call to
+.PN XtRealizeWidget ,
+the \fItype\fP is set to
+.PN XtHrealizeWidget 
+and \fIwidget\fP is the widget being realized.
+The callbacks are called after the widget has been realized.
+.LP
+When the changeHook callbacks are called as a result of a call to
+.PN XtUnrealizeWidget ,
+the \fItype\fP is set to
+.PN XtHunrealizeWidget ,
+and \fIwidget\fP is the widget being unrealized.
+The callbacks are called after the widget has been unrealized.
+.LP
+When the changeHook callbacks are called as a result of a call to
+.PN XtAddCallback ,
+\fItype\fP is set to
+.PN XtHaddCallback ,
+\fIwidget\fP is the widget to which the callback is being added, and
+\fIevent_data\fP may be cast to type String and is the name of the 
+callback being added.
+The callbacks are called after the callback has been added to the widget.
+.LP
+When the changeHook callbacks are called as a result of a call to
+.PN XtAddCallbacks ,
+the \fItype\fP is set to
+.PN XtHaddCallbacks ,
+\fIwidget\fP is the widget to which the callbacks are being added, and
+\fIevent_data\fP may be cast to type String and is the name of the 
+callbacks being added.
+The callbacks are called after the callbacks have been added to the widget.
+.LP
+When the changeHook callbacks are called as a result of a call to
+.PN XtRemoveCallback ,
+the \fItype\fP is set to
+.PN XtHremoveCallback ,
+\fIwidget\fP is the widget from which the callback is being removed, and
+\fIevent_data\fP may be cast to type String and is the name of
+the callback being removed.  The callbacks are called after the callback 
+has been removed from the widget.
+.LP
+When the changeHook callbacks are called as a result of a call to
+.PN XtRemoveCallbacks ,
+the \fItype\fP is set to
+.PN XtHremoveCallbacks ,
+\fIwidget\fP is the widget from which the callbacks are being removed, and
+\fIevent_data\fP may be cast to type String and is the name of the 
+callbacks being removed.  The callbacks are called after the callbacks 
+have been removed from the widget.
+.LP
+When the changeHook callbacks are called as a result of a call to
+.PN XtRemoveAllCallbacks ,
+the \fItype\fP is set to
+.PN XtHremoveAllCallbacks
+and \fIwidget\fP is the widget from which the callbacks are being removed.
+The callbacks are called after the callbacks have been removed from the
+widget.
+.LP
+When the changeHook callbacks are called as a result of a call to
+.PN XtAugmentTranslations ,
+the \fItype\fP is set to
+.PN XtHaugmentTranslations
+and \fIwidget\fP is the widget whose translations are being modified.
+The callbacks are called after the widget's translations have been 
+modified.
+.LP
+When the changeHook callbacks are called as a result of a call to
+.PN XtOverrideTranslations ,
+the \fItype\fP is set to
+.PN XtHoverrideTranslations
+and \fIwidget\fP is the widget whose translations are being modified.
+The callbacks are called after the widget's translations have been 
+modified.
+.LP
+When the changeHook callbacks are called as a result of a call to
+.PN XtUninstallTranslations ,
+The \fItype\fP is
+.PN XtHuninstallTranslations
+and \fIwidget\fP is the widget whose translations are being uninstalled.
+The callbacks are called after the widget's translations have been 
+uninstalled.
+.LP
+When the changeHook callbacks are called as a result of a call to
+.PN XtSetKeyboardFocus ,
+the \fItype\fP is set to
+.PN XtHsetKeyboardFocus
+and \fIevent_data\fP may be cast to type Widget and is the value of 
+the descendant argument passed to \fBXtSetKeyboardFocus\fP. The 
+callbacks are called before returning from \fBXtSetKeyboardFocus\fP.
+.LP
+When the changeHook callbacks are called as a result of a call to
+.PN XtSetWMColormapWindows ,
+\fItype\fP is set to
+.PN XtHsetWMColormapWindows ,
+\fIevent_data\fP may be cast to type WidgetList and is the value of 
+the list argument passed to \fBXtSetWMColormapWindows\fP, and 
+\fInum_event_data\fP is the length of the list. The callbacks are 
+called before returning from \fBXtSetWMColormapWindows\fP.
+.LP
+When the changeHook callbacks are called as a result of a call to
+.PN XtSetMappedWhenManaged ,
+the \fItype\fP is set to
+.PN XtHsetMappedWhenManaged
+and \fIevent_data\fP may be cast to type Boolean and is the value of 
+the mapped_when_managed argument passed to \fBXtSetMappedWhenManaged\fP. 
+The callbacks are called after setting the widget's mapped_when_managed 
+field and before realizing or unrealizing the widget.
+.LP
+When the changeHook callbacks are called as a result of a call to
+.PN XtMapWidget ,
+the \fItype \fP is set to
+.PN XtHmapWidget
+and \fIwidget\fP is the widget being mapped.
+The callbacks are called after mapping the widget.
+.LP
+When the changeHook callbacks are called as a result of a call to
+.PN XtUnmapWidget ,
+the \fItype \fP is set to
+.PN XtHunmapWidget
+and \fIwidget\fP is the widget being unmapped.
+The callbacks are called after unmapping the widget.
+.LP
+When the changeHook callbacks are called as a result of a call to
+.PN XtPopup ,
+the \fItype\fP is set to
+.PN XtHpopup ,
+\fIwidget\fP is the widget being popped up, and \fIevent_data\fP may 
+be cast to type XtGrabKind and is the value of the grab_kind argument 
+passed to \fBXtPopup\fP.
+The callbacks are called before returning from \fBXtPopup\fP.
+.LP
+When the changeHook callbacks are called as a result of a call to
+.PN XtPopupSpringLoaded ,
+the \fItype\fP is set to
+.PN XtHpopupSpringLoaded
+and \fIwidget\fP is the widget being popped up.
+The callbacks are called 
+before returning from \fBXtPopupSpringLoaded\fP.
+.LP
+When the changeHook callbacks are called as a result of a call to
+.PN XtPopdown ,
+the \fItype\fP is set to
+.PN XtHpopdown
+and \fIwidget\fP is the widget being popped down.
+The callbacks are called 
+before returning from \fBXtPopdown\fP.
+.LP
+A widget set that exports interfaces that change application state
+without employing the \*(xI library should invoke the change hook
+itself.  This is done by:
+.sp
+.Ds
+.TA .5i 2i
+.ta .5i 2i
+        XtCallCallbacks(XtHooksOfDisplay(dpy), XtNchangeHook, call_data);
+.De
+.sp
+.LP
+The XtNconfigureHook callback list is called any time the \*(xI
+move, resize, or configure a widget and when
+.PN XtResizeWindow
+is called.
+.LP
+The \fIcall_data\fP parameter may be cast to type
+.PN XtConfigureHookData.
+.LP
+.IN "XtConfigureHookData" "" "@DEF@"
+.KS
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	String type;
+	Widget widget;
+	XtGeometryMask changeMask;
+	XWindowChanges changes;	
+} XtConfigureHookDataRec, *XtConfigureHookData;
+.De
+.eM
+.KE
+.sp
+.LP
+When the configureHook callbacks are called, the \fItype\fP is
+.PN XtHconfigure ,
+\fIwidget\fP is the widget being configured, and \fIchangeMask\fP and 
+\fIchanges\fP reflect the changes made to the widget. The callbacks 
+are called after changes have been made to the widget.
+.LP
+The XtNgeometryHook callback list is called from 
+.PN XtMakeGeometryRequest
+and
+.PN XtMakeResizeRequest
+once before and once after geometry negotiation occurs.
+.LP
+The \fIcall_data\fP parameter may be cast to type
+.PN XtGeometryHookData .
+.LP
+.IN "XtGeometryHookData" "" "@DFEF@"
+.LP
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	String type;
+	Widget widget;
+	XtWidgetGeometry* request;
+	XtWidgetGeometry* reply;
+	XtGeometryResult result;
+} XtGeometryHookDataRec, *XtGeometryHookData;
+.De
+.eM
+.sp
+.LP
+When the geometryHook callbacks are called prior to geometry negotiation, 
+the \fItype\fP is
+.PN XtHpreGeometry ,
+\fIwidget\fP is the widget for which the request is being made, and
+\fIrequest\fP is the requested geometry.
+When the geometryHook callbacks 
+are called after geometry negotiation, the \fItype\fP is
+.PN XtHpostGeometry ,
+\fIwidget\fP is the widget for which the request was made, \fIrequest\fP
+is the requested geometry, \fIreply\fP is the resulting geometry granted, 
+and \fIresult\fP is the value returned from the geometry negotiation.
+.LP
+The XtNdestroyHook callback list is called when a widget is destroyed.
+The \fIcall_data parameter\fP may be cast to type
+.PN XtDestroyHookData .
+.LP
+.IN "XtDestroyHookData" "" "@DFEF@"
+.sp
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	String type;
+	Widget widget;
+} XtDestroyHookDataRec, *XtDestroyHookData;
+.De
+.eM
+.sp
+.LP
+When the destroyHook callbacks are called as a result of a call to
+.PN XtDestroyWidget ,
+the \fItype\fP is
+.PN XtHdestroy
+and \fIwidget\fP is the widget being destroyed. The callbacks are
+called upon completion of phase one destroy for a widget.
+.LP
+The XtNshells and XtnumShells are read-only resources that report a
+list of all parentless shell widgets associated with a display.
+.LP
+Clients who use these hooks must exercise caution in calling \*(xI
+functions in order to avoid recursion.
+
+.NH 3
+Querying Open Displays
+.XS
+\fB\*(SN Querying Open Displays\fP
+.XE
+.LP
+To retrieve a list of the Displays associated with an application context,
+use
+.PN XtGetDisplays .
+.LP
+.IN "XtGetDisplays" "" "@DEF@"
+.sM
+.FD 0
+void XtGetDisplays(\fIapp_context\fP, \fIdpy_return\fP, \fInum_dpy_return\fP)
+.br
+      XtAppContext \fIapp_context\fP;
+.br
+      Display ***\fIdpy_return\fP;
+.br
+      Cardinal *\fInum_dpy_return\fP;
+.FN
+.IP \fIapp_context\fP 1.5i
+Specifies the application context.
+.IP \fIdpy_return\fP 1.5i
+Returns a list of open Display connections in the specified application
+context.
+.IP \fInum_dpy_return\fP 1.5i
+Returns the count of open Display connections in \fIdpy_return\fP.
+.LP
+.eM
+\fBXtGetDisplays\fP may be used by an external agent to query the
+list of open displays that belong to an application context. To free 
+the list of displays, use
+.PN XtFree .
+.bp