.\" $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