diff options
Diffstat (limited to 'libXt/specs/CH11')
| -rw-r--r-- | libXt/specs/CH11 | 3566 |
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 |