\&
.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 \- 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
Translate a window to a widget
.IP \(bu 5
Handle errors
.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 .
.IN "XtNumber" "" "@DEF@"
.FD 0
Cardinal XtNumber(\fIarray\fP)
.br
      ArrayVariable \fIarray\fP;
.FN
.IP \fIarray\fP 1i
Specifies a fixed-size array.
.LP
The
.PN XtNumber
macro returns the number of elements in the specified argument lists, 
resources lists, and other counted arrays.
.NH 2
Translating Strings to Widget Instances
.XS
\fB\*(SN Translating Strings to Widget Instances\fP
.XE
.LP
To translate a widget name to widget instance, use
.PN XtNameToWidget .
.IN "XtNameToWidget" "" "@DEF@"
.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.
.IP \fInames\fP 1i
Specifies the partially qualified name of the desired widget.
.LP
The
.PN XtNameToWidget
function searches for a descendant of the reference
widget whose name matches the specified names.  The names 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 is a subclass of
.PN 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 names, where each component of names 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(s).  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 .
.IN "XtMalloc" "" "@DEF@"
.FD 0
char *XtMalloc(\fIsize\fP);
.br
      Cardinal \fIsize\fP;
.FN
.IP \fIsize\fP 1i
Specifies the number of bytes desired.
.LP
The
.PN XtMalloc
functions returns a pointer to a block of storage of at least 
the specified size 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 .
.IN "XtCalloc" "" "@DEF@"
.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 an array element in bytes.
.LP
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 .
.sp
.LP
To change the size of an allocated block of storage, use
.PN XtRealloc .
.IN "XtRealloc" "" "@DEF@"
.FD 0
char *XtRealloc(\fIptr\fP, \fInum\fP);
.br
      char *\fIptr\fP;
.br
      Cardinal \fInum\fP;
.FN
.ds Po to the old storage
.IP \fIptr\fP 1i
Specifies a pointer \*(Po.
.IP \fInum\fP 1i
Specifies number of bytes desired in new storage.
.LP
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 ptr is NULL,
.PN XtRealloc
allocates the new storage without copying the old contents;
that is, it simply calls
.PN XtMalloc .
.sp
.LP
To free an allocated block of storage, use
.PN XtFree .
.IN "XtFree" "" "@DEF@"
.FD 0
void XtFree(\fIptr\fP);
.br
      char *\fIptr\fP;
.FN
.ds Po to the block of storage that is to be freed
.IP \fIptr\fP 1i
Specifies a pointer \*(Po.
.LP
The
.PN XtFree
function returns storage and allows it to be reused.
If ptr is NULL,
.PN XtFree
returns immediately.
.sp
.LP
To allocate storage for a new instance of a data type, use
.PN XtNew .
.IN "XtNew" "" "@DEF@"
.FD 0
\fItype\fP *XtNew(\fItype\fP);
.br
      \fItype\fP;
.FN
.IP \fItype\fP 1i
Specifies a previously declared data type.
.LP
.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
.sp
.LP
To copy an instance of a string, use
.PN XtNewString .
.IN "XtNewString" "" "@DEF@"
.FD 0
String XtNewString(\fIstring\fP);
.br
      String \fIstring\fP;
.FN
.IP \fIstring\fP 1i
Specifies a previously declared string.
.LP
.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
.NH 2
Sharing Graphics Contexts
.XS
\fB\*(SN Sharing Graphics Contexts\fP
.XE
.LP
The \*(xI provide a mechanism whereby cooperating clients 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 all GCs obtained by means of this mechanism must be treated as read-only.
If a changeable GC is needed, the Xlib
.PN XCreateGC
function should be used instead.
.LP
To obtain a read-only, sharable GC, use
.PN XtGetGC .
.IN "XtGetGC" "" "@DEF@"
.FD 0
GC XtGetGC(\fIw\fP, \fIvalue_mask\fP, \fIvalues\fP)
.br
      Widget \fIw\fP;
.br
      XtGCMask \fIvalue_mask\fP;
.br
      XGCValues *\fIvalues\fP;
.FN
.IP \fIw\fP 1i
Specifies the widget.
.ds Vm fields of the values are specified
.IP \fIvalue_mask\fP 1i
Specifies which \*(Vm.
.IP \fIvalues\fP 1i
Specifies the actual values for this GC.
.LP
The
.PN XtGetGC
function returns a sharable, read-only GC.
The parameters to this function are the same as those for
.PN XCreateGC 
except that a widget is passed instead of a display.
.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 value_mask provided to
determine which fields of the GC a widget considers relevant.
The value_mask is used only to tell the server which fields should be
filled in with widget data and which it should fill in with default values.
For further information about value_mask and values,
see
.PN XCreateGC
in the \fI\*(xL\fP.
.sp
.LP
To deallocate a shared GC when it is no longer needed, use
.PN XtReleaseGC .
.IN "XtReleaseGC" "" "@DEF@"
.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.
.IP \fIgc\fP 1i
Specifies the GC to be deallocated.
.LP
References to sharable GCs are counted and a free request is generated to the
server when the last user of a given GC destroys it.
.NH 2
Managing Selections
.XS
\*(SN Managing Selections
.XE
.LP
Arbitrary widgets (possibly not all in the same application) can communicate 
with each other by means of the \*(tk global selection mechanism,
which is defined in the \fI\*(xC\fP.
The \*(xI provide 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 client and the X server;
the \*(xI will break a too-large selection 
into smaller pieces for transport if necessary
and will coalesce a selection transmitted incrementally if the value
was requested atomically.
.LP
The next sections discuss how to:
.IP \(bu 5
Set and get the selection timeout value
.IP \(bu 5
Use atomic transfers
.IP \(bu 5
Use incremental transfers
.IP \(bu 5
Conveniently retrieve the most recent timestamp received

.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 .
.IN "XtAppSetSelectionTimeout" "" "@DEF@"
.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.
.sp
.LP
To get the current selection timeout value, use
.PN XtAppGetSelectionTimeout .
.IN "XtAppGetSelectionTimeout" "" "@DEF@"
.FD 0
unsigned long XtAppGetSelectionTimeout(\fIapp_context\fP)
.br
     XtAppContext \fIapp_context\fP;
.FN
.IP \fIapp_context\fP 1i
Specifies the application context.
.LP
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 
.PN selectionTimeout
application resource, or, if
.PN selectionTimeout
is not specified,
it defaults to five seconds.
.NH 3
Using Atomic Transfers
.XS
\*(SN Using Atomic Transfers
.XE
.LP
The next three three sections discuss:
.IP \(bu 5
Atomic transfer procedures
.IP \(bu 5
Getting the selection value
.IP \(bu 5
Setting the selection owner
.NH 4
Atomic Transfer Procedures
.XS
\*(SN Atomic Transfer Procedures
.XE
.IN "Selections" "atomic"
.LP
The following procedures are to be used with atomic transfers.
The first four are used by the selection owner,
and the last one is used by the requestor.
.LP
.IN "XtConvertSelectionProc" "" "@DEF@"
.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 which currently owns this selection.
.IP \fIselection\fP 1i
Specifies the atom that describes the type of 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 value 
(each of size indicated by format) 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
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
they are prepared to convert their selection into.
.sp
.LP
.IN "XtLoseSelectionProc" "" "@DEF@"
.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 that describes the selection type.
.LP
This procedure is called by the \*(xI selection mechanism
to inform the specified widgets that it has lost the given selection.
Note that this procedure does not ask the widget to lose the 
selection ownership.
.sp
.LP
.IN "XtSelectionDoneProc" "" "@DEF@"
.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 that describes the selection type that was converted.
.IP \fItarget\fP 1i
Specifies the target type to which the conversion was done.
.LP
This procedure is called by the \*(xI selection mechanism
to inform the selection owner when 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 
but 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.
.sp
.LP
.IN "XtSelectionCallbackProc" "" "@DEF@"
.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 type of 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 but the type that
is used to represent the target.
The special \*(tk atom 
.PN XT_CONVERT_FAIL 
is used to indicate that the selection conversion failed because the
selection owner did not respond within the \*(xI's 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 value.
.IP \fIformat\fP 1i
Specifies the size in bits of the data elements of value.
.LP
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 0.
.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 the \fI\*(xC\fP).
A selection request with
the MULTIPLE target type will be transparently transformed into a
series of calls to this procedure, one for each target type, and a
selection request with the TIMESTAMP target value will be 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 which triggered the convert_selection procedure, use
.PN XtGetSelectionRequest .
.IN "XtGetSelectionRequest" "" "@DEF@"
.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 which currently owns this 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.
.LP
.PN XtGetSelectionRequest
may only be called from within a
convert_selection procedure and returns a pointer to the
.PN SelectionRequest
event which caused the procedure to be invoked.
Request_id specifies a unique id for the individual request in the
case that multiple incremental transfers are outstanding.  For atomic
transfers, request_id must be specified as NULL.  If no
.PN SelectionRequest
event is being processed for the specified
widget, selection and request_id,
.PN XtGetSelectionRequest
returns NULL.

.NH 4
Getting the Selection Value
.XS
\*(SN Getting the Selection Value
.XE
.LP
To obtain the selection value in a single, logical unit, use
.PN XtGetSelectionValue
or
.PN XtGetSelectionValues .
.IN "XtGetSelectionValue" "" "@DEF@"
.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
.ds Wi that is making the request
.IP \fIw\fP 1i
Specifies the widget \*(Wi.
.IP \fIselection\fP 1i
Specifies the particular selection desired (that is, primary or secondary).
.IP \fItarget\fP 1i
Specifies the type of the information that is needed about the selection.
.ds Cb \ that is to be called when the selection value has been obtained
.IP \fIcallback\fP 1i
Specifies the callback procedure\*(Cb.
Note that this is how the selection value is communicated back to the client.
.ds Cd it is called
.IP \fIclient_data\fP 1i
Specifies the argument that is to be passed to the specified procedure
when \*(Cd.
.ds Ti is desired
.IP \fItime\fP 1i
Specifies the timestamp that indicates when the selection \*(Ti.
This should be the timestamp of the event which triggered this request;
the value 
.PN CurrentTime 
is not acceptable; see the \fI\*(xC\fP.
.LP
The
.PN XtGetSelectionValue
function requests the value of the selection that has been converted to 
the target type. 
The specified callback will be called some time after 
.PN XtGetSelectionValue 
is called;
in fact, it may be called before or after 
.PN XtGetSelectionValue 
returns.
.sp
.LP
.IN "XtGetSelectionValues" "" "@DEF@"
.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
.ds Wi that is making the request
.IP \fIw\fP 1i
Specifies the widget \*(Wi.
.IP \fIselection\fP 1i
Specifies the particular selection desired (that is, primary or secondary).
.IP \fItargets\fP 1i
Specifies the types of information that is needed about the selection.
.IP \fIcount\fP 1i
Specifies the length of the targets and client_data lists.
.ds Cb \ that is to be called with each selection value obtained
.IP \fIcallback\fP 1i
Specifies the callback procedure\*(Cb.
Note that this is how the selection values are communicated back to the
client.
.IP \fIclient_data\fP 1i
Specifies the client data (one for each target type)
that is passed to the callback procedure when it is called for that target.
.ds Ti value is desired
.IP \fItime\fP 1i
Specifies the timestamp that indicates when the selection \*(Ti.
This should be the timestamp of the event which triggered this request;
the value 
.PN CurrentTime
is not acceptable; see the \fI\*(xC\fP.
.LP
The
.PN XtGetSelectionValues
function is similar to
.PN XtGetSelectionValue 
except that it takes a list of target types and a list of client data 
and obtains the current value of the selection converted to each of the targets.
The effect is as if each target were specified in a separate call to
.PN XtGetSelectionValue .
The callback is called once with the corresponding client data for each target.
.PN XtGetSelectionValues
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 when calling
.PN XtGetSelectionValue
repeatedly.
.NH 4
Setting the Selection Owner
.XS
\*(SN Setting the Selection Owner
.XE
.LP
To set the selection owner when using atomic transfers,
use
.PN XtOwnSelection .
.IN "XtOwnSelection" "" "@DEF@"
.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
.ds Wi that wishes to become the owner
.IP \fIw\fP 1i
Specifies the widget \*(Wi.
.IP \fIselection\fP 1i
Specifies an atom that describes the type of the selection (for example,
.PN XA_PRIMARY , 
.PN XA_SECONDARY , 
or
.PN XA_CLIPBOARD ).
.ds Ti ownership should commence
.IP \fItime\fP 1i
Specifies the timestamp that indicates when the selection \*(Ti.
This should be the timestamp of the event that triggered ownership;
the value
.PN CurrentTime 
is not acceptable; see the \fI\*(xC\fP.
.IP \fIconvert_proc\fP 1i
Specifies the procedure that is to be called whenever someone requests the 
current value of the selection.
.IP \fIlose_selection\fP 1i
Specifies the procedure that is 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 that is called 
after the requestor has received the selection or NULL if the owner is not
interested in being called back.
.LP
The
.PN XtOwnSelection
function informs the \*(xI selection mechanism that a
widget believes it owns a selection.
It returns 
.PN True 
if the widget has successfully become 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.
Note that widgets can lose selection ownership either 
because someone else asserted later ownership of the selection 
or because the widget voluntarily gave up ownership of the selection.
Also note that the lose_selection procedure is not called 
if the widget fails to obtain selection ownership in the first place.
.sp
.LP
Usually, the \*(xI selection mechanism informs an application 
when one of its widgets has lost ownership of the selection.
However, in response to some user actions 
(for example, when a user deletes the information selected),
the application should explicitly inform the \*(xI that it's widget
no longer is to be the selection owner by using
.PN XtDisownSelection .
.IN "XtDisownSelection" "" "@DEF@"
.FD 0
void XtDisownSelection(\fIw\fP, \fIselection\fP, \fItime\fP)
.br
      Widget \fIw\fP;
.br
      Atom \fIselection\fP;
.br
      Time \fItime\fP;
.FN
.ds Wi that wishes to relinquish ownership
.IP \fIw\fP 1i
Specifies the widget \*(Wi.
.IP \fIselection\fP 1i
Specifies the atom that specifies which selection it is giving up.
.ds Ti ownership is relinquished
.IP \fItime\fP 1i
Specifies the timestamp that indicates when the selection \*(Ti.
.LP
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 will be 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
request_id 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
argument.  This allows the owner to distinguish between the first
requestor, who is asking for the second segment, and the second
requestor, who is asking for the first segment. 
.LP
The next three sections discuss:
.IP \(bu 5
Incremental transfer procedures
.IP \(bu 5
Getting the selection value
.IP \(bu 5
Setting the selection owner

.NH 4
Incremental Transfer Procedures
.XS
\*(SN Incremental Transfer Procedures
.XE
.IN "Selections" "incremental"
.LP
The following procedures are to be used with incremental transfers.
The first five are used by the selection owner and the last two are
used by the requestor.
.LP
.sp
.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 which currently owns this selection.
.IP \fIselection\fP 1i
Specifies the atom that names the selection requested
(for example, XA_PRIMARY or XA_SECONDARY).
.IP \fItarget\fP 1i
Specifies the type of information required about selection;
for example, FILENAME, TEXT, XA_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, both file name and text might
have property type 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.
.IP \fIlength_return\fP 1i
Specifies a pointer into which the number of elements
in value (each of size indicated by format) 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.
.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
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 value
for each segment to be transferred.  This procedure should store a
non-NULL value in value and zero in length_return to indicate that the
entire selection has been delivered.  After returning this final
segment, the request_id may be re-used by the \*(xI to begin a
new transfer.

.sp
.LP
To retrieve the
.PN SelectionRequest
event which triggered the convert_selection procedure, use
.PN XtGetSelectionRequest ,
described in section 11.5.2.1.
.sp
.IN "XtLoseSelectionIncrProc" "" "@DEF@"
.FN 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
This procedure, which is optional, is called by the \*(xI to
inform the selection owner that it no longer owns the selection.
.sp
.IN "XtSelectionDoneIncrProc" "" "@DEF@"
.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
This procedure, which is optional, is called by the \*(xI after
the requestor has retrieved the final (0-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
.IN "XtCancelConvertSelectionProc" "" "@DEF@"
.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
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 selection value using incremental transfers, use
.PN XtGetSelectionValueIncremental
or
.PN XtGetSelectionValuesIncremental .
.IN "XtGetSelectionValueIncremental" "" "@DEF@"
.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 that is making the request.
.IP \fIselection\fP 1i
Specifies the particular selection desired (e.g. XA_PRIMARY or XA_SECONDARY).
.IP \fItarget\fP 1i
Specifies the type of the information that is needed
about the selection (e.g. TARGETS).
.IP \fIselection_callback\fP 1i
Specifies the callback procedure that is to be
called to receive each data segment.
.IP \fIclient_data\fP 1i
Specifies client-specific data that is 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 which triggered this request;
the value
.PN CurrentTime
is not acceptable; see the \fI\*(xC\fP.
.LP
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
selection_callback 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, due to timeout), the selection_callback procedure is
called with a type of
.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.
.sp
.IN "XtGetSelectionValuesIncremental" "" "@DEF@"
.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
      XtSelectionIncrCallbackProc \fIselection_callback\fP;
.br
      XtPointer *\fIclient_data\fP;
.br
      Time \fItime\fP;
.FN
.IP \fIw\fP 1i
Specifies the widget that is making the request.
.IP \fIselection\fP 1i
Specifies the particular selection desired (e.g. XA_PRIMARY or XA_SECONDARY).
.IP \fItargets\fP 1i
Specifies the types of information that is needed about
the selection (e.g. HOST, USER).
.IP \fIcount\fP 1i
Specifies the length of the targets and client_data lists.
.IP \fIselection_callback\fP 1i
Specifies the callback procedure that is to be called
to receive each selection value.
.IP \fIclient_data\fP 1i
Specifies a list of client data (one for each target
type) that is passed to the callback procedures when
they are 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 which triggered this request;
the value
.PN CurrentTime
is not acceptable; see the \fI\*(xC\fP.
.LP
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 target/client_data 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.

.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 .
.IN "XtOwnSelectionIncremental" "" "@DEF@"
.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.
.IP \fIselection\fP 1.25i
Specifies an atom that names the
selection (for example, XA_PRIMARY, XA_SECONDARY, or CLIPBOARD).
.IP \fItime\fP 1.25i
Specifies the timestamp that indicates when the
selection ownership should commence.  This should be
the timestamp of the event that triggered ownership; the value
.PN CurrentTime
is not acceptable; see the \fI\*(xC\fP.
.IP \fIconvert_callback\fP 1.25i
Specifies the procedure that is to be called whenever
the current value of the selection is requested.
.IP \fIlose_callback\fP 1.25i
Specifies the procedure that is 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 that is 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 that is 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 that is to be passed to each of
the callback procedures when they are called.
.LP
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.
.LP
If a done_callback is specified, the client owns the storage allocated
for passing the value to the \*(xI.  If done_callback is NULL,
the convert_callback must allocate storage using
.PN XtMalloc ,
.PN XtRealloc
or
.PN XtCalloc
and the final value specified will be 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 will be invoked to indicate completion of the transfer.
.LP
The lose_callback does not indicate completion of any in-progress
transfers; it will be 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
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
which contained a timestamp, use
.PN XtLastTimestampProcessed .
.IN "XtLastTimestampProcessed" "" "@DEF@"
.FD 0
Time XtLastTimestampProcessed(\fIdisplay\fP)
.br
      Display *\fIdisplay\fP;
.FN
.IP \fIdisplay\fP 1i
Specifies an open display connection.
.LP
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 2
Merging Exposure Events into a Region
.XS
\*(SN Merging Exposure Events into a Region
.XE
.LP
The \*(xI provide the
.PN XtAddExposureToRegion
utility function that merges
.PN Expose
and
.PN GraphicsExpose
events into a region that clients can process at once
rather than processing individual rectangles.
(For further information about regions,
see \fI\*(xL\fP.)
.sp
.LP
To merge
.PN Expose
and
.PN GraphicsExpose
events into a region, use
.PN XtAddExposureToRegion .
.IN "XtAddExposureToRegion" "" "@DEF@"
.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
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 region.
If the event argument is not an
.PN Expose
or
.PN GraphicsExpose
event,
.PN XtAddExposureToRegion
returns without an error and without modifying region.
.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
coordinates, use
.PN XtTranslateCoords .
.IN "XtTranslateCoords" "" "@DEF@"
.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.
.ds Nu widget-relative
.IP \fIx\fP 1i
.br
.ns
.IP \fIy\fP 1i
Specify the \*(Nu x and y coordinates.
.IP \fIrootx_return\fP 1i
.br
.ns
.IP \fIrooty_return\fP 1i
Returns the root-relative x and y coordinates.
.LP
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 window and display pointer into a widget instance, use
.PN XtWindowToWidget .
.IN "XtWindowToWidget" "" "@DEF@"
.FD 0
Widget XtWindowToWidget(\fIdisplay\fP, \fIwindow\fP)
.br
      Display *\fIdisplay\fP;
.br
      Window \fIwindow\fP;
.FN
.ds Di \ on which the window is defined
.IP \fIdisplay\fP 1i
Specifies the display\*(Di.
.IP \fIwindow\fP 1i
Specify the window for which you want the widget.
.NH 2
Handling Errors
.XS
\fB\*(SN Handling Errors\fP
.XE
.LP
The \*(xI let a client register procedures that are to be 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 looks the error up in an error resource database
.IP \(bu 5
A low-level interface that takes a simple string
.LP
The high-level functions construct a string to pass to the lower-level
interface.
On POSIX-based systems, the error database usually is 
.PN /usr/lib/X11/XtErrorDB .
.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.
If they are set for different application contexts,
the one performed 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 .
.IN "XtAppGetErrorDatabase" "" "@DEF@"
.FD 0
XrmDatabase *XtAppGetErrorDatabase(\^\fIapp_context\fP\^)
.br
     XtAppContext \fIapp_context\fP;
.FN
.IP \fIapp_context\fP 1i
Specifies the application context.
.LP
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.
.LP
The high-level error and warning handler procedure pointers are of the type
.PN XtErrorMsgHandler :
.IN "XtErrorMsgHandler" "" "@DEF@"
.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 that is concatenated with the specified type to form 
the resource name of the error message.
.IP \fItype\fP 1i
Specifies the type that is 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 values to be substituted in the message.
.IP \fInum_params\fP 1i
Specifies the number of values in the parameter list.
.LP
The specified name can be a general kind of error, 
like invalidParameters or invalidWindow, 
and the specified type gives extra information.
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 .
.IN "XtAppGetErrorDatabaseText" "" "@DEF@"
.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
Specifies the name and type that are concatenated to form the resource name 
of the error message.
.ds Cl \ of the error message
.IP \fIclass\fP 1i
Specifies the resource class\*(Cl.
.ds Dm \ if an error database entry is not found
.IP \fIdefault\fP 1i
Specifies the default message to use\*(Dm.
.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 that is to be used
or NULL if the application's database is to be used.
.LP
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.
.sp
.LP
To return the application name and class as passed to
.PN XtDisplayInitialize
for a particular Display, use
.PN XtGetApplicationNameAndClass .
.IN "XtGetApplicationNameAndClass" "" "@DEF@"
.FD 0
void XtGetApplicationNameAndClass(Display* \fIdisplay\fP, String* \
\fIname_return\fP, 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
.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 .
.IN "XtAppSetErrorMsgHandler" "" "@DEF@"
.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.
.ds Mh fatal error procedure, which should not return
.IP \fImsg_handler\fP 1i
Specifies the new \*(Mh.
.LP
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 \*(tk behavior is undefined.
.sp
.LP
To call the high-level error handler, use
.PN XtAppErrorMsg .
.IN "XtAppErrorMsg" "" "@DEF@"
.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.
.ds Cl
.IP \fIclass\fP 1i
Specifies the resource class\*(Cl.
.IP \fIdefault\fP 1i
Specifies the default message to use\*(Dm.
.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 values in the parameter list.
.LP
The \*(xI internal errors all have class
.PN XtToolkitError .
.sp
.LP
To register a procedure to be called on nonfatal error conditions, use
.PN XtAppSetWarningMsgHandler .
.IN "XtAppSetWarningMsgHandler" "" "@DEF@"
.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.
.ds Mh nonfatal error procedure, which usually returns
.IP \fImsg_handler\fP 1i
Specifies the new \*(Mh.
.LP
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 .
.IN "XtAppWarningMsg" "" "@DEF@"
.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.
.cd Cl
.IP \fIclass\fP 1i
Specifies the resource class\*(Cl.
.IP \fIdefault\fP 1i
Specifies the default message to use\*(Dm.
.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 values in the parameter list.
.LP
The \*(xI internal warninings all have class
.PN XtToolkitError .
.sp
.LP
The low-level error and warning handler procedure pointers are of type
.PN XtErrorHandler :
.IN "XtErrorHandler" "" "@DEF@"
.FD 0
typedef void (*XtErrorHandler)(String);
.br
      String \fImessage\fP;
.FN
.IP \fImessage\fP 1i
Specifies the error message.
.LP
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 .
.IN "XtAppSetErrorHandler" "" "@DEF@"
.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.
.ds Ha fatal error procedure, which should not return
.IP \fIhandler\fP 1i
Specifies the new \*(Ha.
.LP
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 \*(tk behavior is undefined.
.sp
.LP
To call the installed fatal error procedure, use
.PN XtAppError .
.IN "XtAppError" "" "@DEF@"
.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.
.ds Me reported
.IP \fImessage\fP 1i
Specifies the message that is to be \*(Me.
.LP
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 .
.IN "XtAppSetWarningHandler" "" "@DEF@"
.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.
.ds Ha nonfatal error procedure, which usually returns
.IP \fIhandler\fP 1i
Specifies the new \*(Ha.
.LP
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 .
.IN "XtAppWarning" "" "@DEF@"
.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 that is to be reported.
.LP
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 .
.IN "XtSetWMColormapWindows" "" "@DEF@"
.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 will be stored.
.IP \fIlist\fP 1i
Specifies a list of widgets whose windows are to be
listed in the \s-1WM_COLORMAP_WINDOWS\s+1 property.
.IP \fIcount\fP 1i
Specifies the number of widgets in list.
.LP
.PN XtSetWMColormapWindows
returns immediately if widget is not realized or if count is 0.
Otherwise,
.PN XtSetWMColormapWindows
constructs an ordered list of windows
by examining each widget in the list in turn and
.IP \(bu 5
ignoring the widget if it is not realized or 
.IP \(bu 5
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 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 using
string substitutions in a list of file specifications.  There are two
routines provided;
.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 X/Open Portability Guide 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.
.sp
.Ds 0
.TA .5i 3i
.ta .5i 3i
typedef struct {
	char match;
	String substitution;
} SubstitutionRec, *Substitution;
.De
.LP
File name evaluation is handled in an operating system-dependent
fashion by an
.PN XtFilePredicate
.IN "XtFilePredicate" "" "@DEF@"
procedure.
.FD 0
typedef Boolean (*XtFilePredicate)(String \fIfilename\fP);
.FN
.IP \fIfilename\fP 1i
Specifies a potential filename.
.LP
A file predicate procedure will be 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 .
.IN "XtFindFile" "" "@DEF@"
.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 1i
Specifies a path of file names including substitution characters.
.IP \fIsubstitutions\fP 1i
Specifies a list of substitutions to make into the path.
.IP \fInum_substitutions\fP 1i
Specifies the number of substitutions passed in.
.IP \fIpredicate\fP 1i
Specifies a procedure called to judge each potential file name, or NULL.
.LP
The path 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 controlled 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 substitutions for that character in the match field and if
found replaces the percent and match characters with the string in the
corresponding substitution field.  A substitution string 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 predicate parameter is NULL, an internal procedure that checks
if the file exists, is readable, and is not a directory will be 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 .
.IN "XtResolvePathname" "" "@DEF@"
.FD 0
String XtResolvePathname(\fIdpy\fP, \fItype\fP, \fIfilename\fP, \fIsuffix\fP, \
\fIpath\fP, \fIsubstitutions\fP, \fInum_substitutions\fP, \fIpredicate\fP)
.br
      Display *\fIdpy\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 \fIdpy\fP 1i
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 1i
Specify values to substitute into the path.
.IP \fIpath\fP 1i
Specifies the list of file specifications, or NULL.
.IP \fIsubstitutions\fP 1i
Specifies a list of additional substitutions to make into the path, or NULL.
.IP \fInum_substitutions\fP 1i
Specifies the number of entries in substitutions.
.IP \fIpredicate\fP 1i
Specifies a procedure called to judge each potential file name, or NULL.
.LP
The substitutions specified by
.PN XtResolvePathname
are determined from the value of the language string retrieved by
.PN XtDisplayInitialize
for the specified display.  A language is specified from three parts, two
of which are optional: the language, the territory, and the codeset.
These parts are combined into a single string as
language[_territory][.codeset]; the parts consist of arbitrary strings
of letters and numbers.  No interpretation of the parts of the
language is done other than to use them in substitutions.  To set the
language for all applications specify ``*xnlLanguage: \fIlang\fP'' in the
resource database. 
.IN "xnlLanguage"
.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 filename parameter, or the application's
class name if filename is NULL.
.IP %T 5
The value of the type parameter.
.IP %S 5
The value of the suffix parameter.
.IP %L 5
The language specification associated with the specified display.
.IP %l 5
The language part of the display's language spec.
.IP %t 5
The territory part of the display's language spec.
.IP %c 5
The codeset part of the display's language spec.
.LP
If a path is passed to
.PN XtResolvePathname
it will be passed along to
.PN XtFindFile .
If path is NULL, the value of the \s-1XFILESEARCHPATH\s+1
.IN "XFILESEARCHPATH" "" "@DEF@"
environment variable will be passed to
.PN XtFindFile .
If \s-1XFILESEARCHPATH\s+1
is not defined, an implementation-specific default path will be passed
in which contains at least /usr/lib/X11/%T/%N%S.  If the path begins
with a colon, it will be preceded by %N%S.  If the path includes two
adjacent colons, %N%S will be inserted between them.
.LP
The type 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 suffix 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%S:/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 will be
used as a subdirectory of /usr/lib/X11 that will be searched for other
files.  If the desired file is not found there, the lookup will be
tried again using just the language part of the specification.  If the
file is not there it will be looked for in /usr/lib/X11.  The type
parameter is used as a subdirectory of the language directory or of
/usr/lib/X11, and the suffix is appended to the file name.
.LP
It is the responsibility of the caller to free the returned string using
.PN XtFree
when it is no longer needed.
.bp
