diff options
Diffstat (limited to 'libXt/specs/CH11')
| -rw-r--r-- | libXt/specs/CH11 | 3566 |
1 files changed, 0 insertions, 3566 deletions
diff --git a/libXt/specs/CH11 b/libXt/specs/CH11 deleted file mode 100644 index 55b8d92f3..000000000 --- a/libXt/specs/CH11 +++ /dev/null @@ -1,3566 +0,0 @@ -.\" $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 |