3567 lines
101 KiB
Plaintext
3567 lines
101 KiB
Plaintext
.\" $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
|