Page: | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 |
---|
The Intrinsics provide a number of
utility functions that you can use to
Home |
---|
To determine the number of elements
in a fixed-size array, use XtNumber.
array | Specifies a fixed size array of arbitrary type. |
The XtNumber macro returns the
number of elements allocated to the array.
Home |
---|
To translate a widget name to a widget
instance, use XtNameToWidget.
reference | Specifies the widget from which the search is to start. Must be of class Core or any subclass thereof. |
names | Specifies the partially qualified name of the desired widget. |
The XtNameToWidget function
searches for a descendant of the reference widget whose
name matches the specified names. The names parameter specifies
a simple object name or a series of simple object name components
separated by periods or asterisks. 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:
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 Intrinsics do not require that all children of a widget have unique names, 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.
Home |
---|
The Intrinsics' 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 malloc,
calloc, realloc, and free with the following
added functionality:
See the standard C library documentation
on malloc, calloc, realloc, and free for
more information.
To allocate storage, use XtMalloc.
size | Specifies the number of bytes desired. |
The XtMalloc function returns
a pointer to a block of storage of at least the specified size
bytes. If there is insufficient memory to allocate the new
block, XtMalloc calls XtErrorMsg.
To allocate and initialize an array,
use XtCalloc.
num | Specifies the number of array elements to allocate. |
size | Specifies the size of each array element in bytes. |
The 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, XtCalloc calls XtErrorMsg.
XtCalloc returns the address of the allocated storage.
To change the size of an allocated
block of storage, use XtRealloc.
ptr | Specifies a pointer to the old storage allocated with XtMalloc, XtCalloc, or XtRealloc, or NULL. |
num | Specifies number of bytes desired in new storage. |
The 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, XtRealloc calls XtErrorMsg. If ptr
is NULL, XtRealloc simply calls XtMalloc. XtRealloc
then returns the address of the new block.
To free an allocated block of storage,
use XtFree.
ptr | Specifies a pointer to a block of storage allocated with XtMalloc, XtCalloc, or XtRealloc, or NULL. |
The XtFree function returns
storage, allowing it to be reused. If ptr is NULL, XtFree
returns immediately.
To allocate storage for a new instance of a type, use XtNew.
type | Specifies a previously declared type. |
XtNew returns
a pointer to the allocated storage. If there is insufficient memory
to allocate the new block, XtNew calls XtErrorMsg.
XtNew is a convenience macro that calls XtMalloc
with the following arguments specified:
The storage allocated by XtNew
should be freed using XtFree.
To copy an instance of a string, use
XtNewString.
string | Specifies a previously declared string. |
XtNewString
returns a pointer to the allocated storage. If there is insufficient
memory to allocate the new block, XtNewString calls XtErrorMsg.
XtNewString is a convenience macro that calls XtMalloc
with the following arguments specified:
(strcpy(XtMalloc((unsigned)strlen(str) + 1), str))
The storage allocated by XtNewString
should be freed using XtFree.
Home |
---|
The Intrinsics 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. To obtain
a shareable GC with modifiable fields, use XtAllocateGC.
object | Specifies an object, giving the screen for which the returned GC is valid. Must be of class Object or any subclass thereof. |
depth | Specifies the depth for which the returned GC is valid, or 0. |
value_mask | Specifies fields of the GC that are initialized from values. |
values | Specifies the values for the initialized fields. |
dynamic_mask | Specifies fields of the GC that may be modified by the caller. |
unused_mask | Specifies fields of the GC that will not be used by the caller. |
The XtAllocateGC function returns
a shareable GC that may be modified by the client. The screen
field of the specified widget or of the nearest widget ancestor
of the specified object and the specified depth argument
supply the root and drawable depths for which the GC is to be
valid. If depth is zero the depth is taken from the depth
field of the specified widget or of the nearest widget ancestor
of the specified object.
The value_mask argument specifies
fields of the GC that are initialized with the respective member
of the values structure. The dynamic_mask argument
specifies fields that the caller intends to modify during program
execution. The caller must insure that the corresponding GC field
is set prior to each use of the GC. The unused_mask 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 unused_mask. The caller may assume that at
all times all fields not specified in either dynamic_mask or
unused_mask have their default value if not specified in
value_mask or the value specified by values. If
a field is specified in both value_mask and dynamic_
mask, the effect is as if it were specified only in dynamic
mask and then immediately set to the value in values. If
a field is set in unused_mask and also in either value_
mask or dynamic _mask, the specification in unused_
mask is ignored.
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. XtAllocateGC may modify
and return an existing GC if it was allocated with a nonzero unused_
mask.
To obtain a shareable GC with no modifiable
fields, use XtGetGC.
object | Specifies an object, giving the screen and depth for which the returned GC is valid. Must be of class Object or any subclass thereof. |
value_mask | Specifies which fields of the values structure are specified. |
Values | Specifies the actual values for this GC. |
The XtGetGC function returns a shareable, read-only GC. The parameters to this function are the same as those for XCreateGC except that an Object is passed instead of a Display. XtGetGC is equivalent to XtAllocateGC with depth, dynamic mask, and unused_mask all zero.
XtGetGC
shares only GCs in which all values in the GC returned by XCreateGC
are the same. In particular, it does not use the value mask
provided to determine which fields of the GC a widget considers
relevant. The value_mask is used only to tell the server
which fields should be filled in from values and which
it should fill in with default values.
To deallocate a shared GC when it is
no longer needed, use XtReleaseGC.
object | Specifies any object on the Display for which the GC was created. Must be of class Object or any subclass thereof. |
gc | Specifies the shared GC obtained with either XtAllocateGC or XtGetGC. |
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.
Home |
---|
Arbitrary widgets in multiple applications
can communicate with each other by means of the Intrinsics global
selection mechanism, which conforms to the specifications in the
Inter-Client Communication Conventions Manual. The Intrinsics
supply functions for providing and receiving selection data in
one logical piece (atomic transfers) or in smaller logical segments
(incremental transfers).
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 Intrinsics 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 Intrinsics is not required to match the underlying
transport protocol between the application and the X server; the
Intrinsics will break a too large selection into smaller pieces
for transport if necessary and will coalesce a selection transmitted
incrementally if the value was requested atomically.
11.5.1.
Setting and Getting the Selection Timeout Value
To set the Intrinsics selection timeout, use XtAppSetSelectionTimeout.
app_context | Specifies the application context. |
timeout | Specifies the selection timeout in milliseconds. |
To get the current selection timeout
value, use XtAppGetSelectionTimeout.
app_context | Specifies the application context. |
The 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 application resource as retrieved
by XtDisplayInitialize. If selectionTimeout is not specified,
the default is five seconds.
11.5.2. Using Atomic Transfers
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.
11.5.2.1. Atomic Transfer Procedures
The following procedures are used by
the selection owner when providing selection data in a single
unit.
The procedure pointer specified by
the owner to supply the selection data to the Intrinsics is of
type XtConvertSelectionProc.
This procedure is called by the
Intrinsics selection mechanism to get the value of a selection
as a given type from the current selection owner. It returns True
if the owner successfully converted the selection to the target
type or False otherwise. If the procedure returns False,
the values of the return arguments are undefined. Each XtConvertSelectionProc
should respond to target value TARGETS by returning a value
containing the list of the targets into which it is prepared to
convert the selection. The value returned in format_return
must be one of 8, 16, or 32 to allow the server to byte-swap
the data if necessary.
This procedure does not need to worry
about responding to the MULTIPLE or the TIMESTAMP target values
(see Section 2.6.2 in the Inter-Client Communication Conventions
Manual). 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 Intrinsics using
the time specified in the call to XtOwnSelection or XtOwnSelectionIncremental.
To retrieve the SelectionRequest
event that triggered the XtConvertSelectionProc procedure,
use XtGetSelectionRequest.
w | Specifies the widget that currently owns this selection. Must be of class Core or any subclass thereof. |
selection | Specifies the selection being processed. |
request_id | Specifies the requestor id in the case of incremental selections, or NULL in the case of atomic transfers. |
XtGetSelectionRequest
may only be called from within an XtConvertSelectionProc
procedure and returns a pointer to the SelectionRequest
event that caused the conversion procedure to be invoked. Request_id
specifies a unique id for the individual request in the case
that multiple incremental transfers are outstanding. For atomic
transfers, request_id must be specified as NULL. If no
SelectionRequest event is being processed for the specified
widget, selection, and request_id, XtGetSelectionRequest
returns NULL.
The procedure pointer specified by
the owner when it desires notification upon losing ownership is
of type XtLoseSelectionProc.
w | Specifies the widget that has lost selection ownership. |
Selection | Specifies the atom naming the selection. |
This procedure is called by the Intrinsics
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.
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
XtSelectionDoneProc.
typedef void (*XtSelectionDoneProc)(Widget,
Atom*, Atom*);
Widget w;
Atom *selection;
Atom *target;
w | Specifies the widget that owns the converted selection. |
selection | Specifies the atom naming the selection that was converted. |
target | Specifies the target type to which the conversion was done. |
This procedure is called by the Intrinsics
selection mechanism to inform the selection owner that a selection
requestor has successfully retrieved a selection value. If the
selection owner has registered an 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 XtSeleclionDoneProc,
it also owns the storage containing the converted selection value.
11.5.2.2. Getting the Selection Value
The procedure pointer specified by
the requestor to receive the selection data from the Intrinsics
is of type XtSelectionCallbackProc.
.
This procedure is called by the Intrinsics selection mechanism to deliver the requested selection to the requestor.
If the SelectionNotify event
returns a property of 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.
To obtain the selection value in a
single logical unit, use XtGetSelectionValue or XtGetSelectionValues
.
The XtGetSelectionValue function
requests the value of the selection converted to the target type.
The specified callback is called at some time after XtGetSelectionValue
is called, when the selection data is received from the X server.
It may be called before or after XtGetSelectionValue returns.
For more information about selection, target, and time,
see Section 2.6 in the Inter-Client Communication Conventions
Manual.
The XtGetSelectionValues function
is similar to multiple calls to 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 selection, target, and time see Section 2.6
in the Inter-Client Communication Conventions Manual.
11.5.2.3. Setting the Selection Owner
To set the selection owner and indicate
that the selection value will be provided in one piece, use XtOwnSelection
.
The XtOwnSelection function informs the Intrinsics selection mechanism that a widget wishes to own a selection. It returns True if the widget successfully becomes the owner and 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.
If a done_proc is specified, the client
owns the storage allocated for passing the value to the Intrinsics.
If done_proc is NULL, the convert_proc must allocate storage
using XtMalloc, XtRealloc, or XtCalloc, and
the value specified is freed by the Intrinsics when the transfer
is complete.
Usually, a selection owner maintains
ownership indefinitely until some other widget requests ownership,
at which time the Intrinsics 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 Intrinsics that it no longer is to be the selection
owner by using XtDisownSelection.
w | Specifies the widget that wishes to relinquish ownership. |
selection | Specifies the atom naming the selection being given up. |
time | Specifies the timestamp that indicates when the request to relinquish selection ownership was initiated. |
The XtDisownSelection function informs the Intrinsics 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, XtDisownSelection does nothing.
After a widget has called 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 XtDisownSelection finishes
after the call to XtDisownSelection.
11.5.3. Using Incremental Transfers
When using the incremental interface, an owner may have to process more than one selection request for the same selection, converted to the same target, at the same time. The incremental functions take a request_id argument, which is an identifier that is guaranteed to be unique among all incremental requests that are active concurrently.
For example,consider the following:
The following procedures are used by
selection owners who wish to provide the selection data in multiple
segments.
The procedure pointer specified by
the incremental owner to supply the selection data to the Intrinsics
is of type XtConvertSelectionlncrProc.
typedef XtPointer XtRequestId;
w | Specifies the widget that currently owns this selection. |
selection | Specifies the atom that names the selection requested. |
target | Specifies the type of information required about the selection. |
type_return | Specifies a pointer to an atom into which the property type of the converted value of the selection is to be stored. |
value_return | 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. |
length_return | Specifies a pointer into which the number of elements in value return, each of size indicated by format return, is to be stored. |
format_return | 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. |
max_length | Specifies the maximum number of bytes which may be transferred at any one time. |
client_data | Specifies the value passed in by the widget when it took ownership of the selection. |
request_id | Specifies an opaque identification for a specific request. |
This procedure is called repeatedly
by the Intrinsics selection mechanism to get the next incremental
chunk of data from a selection owner who has called XtOwnSelectionIncremental.
It must return True if the procedure has succeeded in converting
the selection data or 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 Intrinsics;
that is, a fixed transfer area may be allocated and returned in
value return for each segment to be transferred. This procedure
should store a non-NULL value in value return and zero
in length return to indicate that the entire selection
has been delivered. After returning this final segment, the request
id may be reused by the Intrinsics to begin a new transfer.
To retrieve the SelectionRequest
event that triggered the selection conversion procedure, use XtGetSelectionRequest,
described in Section 11.5.2.1.
The procedure pointer specified by
the incremental selection owner when it desires notification upon
no longer having ownership is of type XtLoseSelectionIncrProc.
w | Specifies the widget that has lost the selection ownership. |
selection | Specifies the atom that names the selection. |
client_data | Specifies the value passed in by the widget when it took ownership of the selection. |
This procedure, which is optional,
is called by the Intrinsics to inform the selection owner that
it no longer owns the selection.
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 XtSelectionDoneIncrProc .
w | Specifies the widget that owns the selection. |
selection | Specifies the atom that names the selection being transferred. |
target | Specifies the target type to which the conversion was done. |
request_id | Specifies an opaque identification for a specific request. |
client_data | Specified the value passed in by the widget when it took ownership of the selection. |
This procedure, which is optional, is called by the Intrinsics 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 Intrinsics will free only the final value returned by the selection owner using XtFree.
The procedure pointer specified by
the incremental selection owner to notify it if a transfer should
be terminated prematurely is of type XtCancelConvertSelectionProc.
w | Specifies the widget that owns the selection. |
selection | Specifies the atom that names the selection being transferred. |
target | Specifies the target type to which the conversion was done. |
request_id | Specifies an opaque identification for a specific request. |
client_data | Specifies the value passed in by the widget when it took ownership of the selection. |
This procedure is called by the Intrinsics
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.
11.5.3.2. Getting the Selection Value Incrementally
To obtain the value of the selection
using incremental transfers, use XtGetSelectionValueIncremental
or XtGetSelectionValuesIncremental.
The XtGetSelectionValueIncremental
function is similar to XtGetSelectionValue except that
the selection_callback procedure will be called repeatedly upon
delivery of multiple segments of the selection value. The end
of the selection value is indicated when selection_callback
is called with a non-NULL value of length zero, which must
still be freed by the client. If the transfer of the selection
is aborted in the middle of a transfer (for example, because to
timeout), the selection_callback procedure is called with a type
value equal to the symbolic constant XT_CONVERT_FAIL so that the
requestor can dispose of the partial selection value it has collected
up until that point. Upon receiving XT_CONVERT_FAIL, the requesting
client must determine for itself whether or not a partially completed
data transfer is meaningful. For more information about selection,
target, and time, see Section 2.6 in the Inter-Client
Communication Conventions Manual.
The XtGetSelectionValuesIncremental
function is similar to XtGetSelectionValueIncremental except
that it takes a list of targets and client data. XtGetSelectionValuesIncremental
is equivalent to calling XtGetSelectionValueIncremental
successively for each target/client data pair except that
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 XtGetSelectionValueIncremental
repeatedly. For more information about selection, target, and
time, see Section 2.6 in the Inter-Client Communication
Conventions Manual.
11.5.3.3. Setting the Selection Owner for Incremental Transfers
To set the selection owner when using incremental transfers, use
XtOwnSelectionIncremental.
The XtOwnSelectionIncremental
procedure informs the Intrinsics incremental selection mechanism
that the specified widget wishes to own the selection. It returns
True if the specified widget successfully becomes the selection
owner or False otherwise. For more information about selection,
target, and time, see Section 2.6 in the Inter-Client
Communication Conventions Manual.
If a done_callback procedure is specified,
the client owns the storage allocated for passing the value to
the Intrinsics. If done_callback is NULL, the convert_callback
procedure must allocate storage using XtMalloc, XtRealloc,
or XtCalloc, and the final value specified is freed by
the Intrinsics 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.
The lose_callback procedure does not indicate completion of any in-progress transfers; it is invoked at the time a SelectionClear event is dispatched regardless of any active transfers, which are still expected to continue.
A widget that becomes the selection owner using XtOwnSelectionIncremental
may use XtDisownSelection to relinquish selection ownership.
11.5.4. Setting and Retrieving Selection Target Parameters
To specify target parameters for a
selection request with a single target, use XtSetSelectionParameters
.
requestor | Specifies the widget making the request. Must be of class Core or any subclass thereof. |
selection | Specifies the atom that names the selection. |
type | Specifies the type of the property in which the parameters are passed. |
value | Specifies a pointer to the parameters. |
Iength | Specifies the number of elements containing data in value, each element of a size indicated by format. |
format | Specifies the size in bits of the data in the elements of value. |
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 XtGetSelectionValue or to XtGetSelectionValueIncremental specifying the same requestor widget and selection atom will generate a ConvertSelection request referring to the property containing the parameters. If 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.
The possible values of format are 8,
16, or 32. If the format is 8, the elements of value are
assumed to be sizeof(char); if 16, sizeof(short); if 32, sizeof(long).
To generate a MULTIPLE target request
with parameters for any of the multiple targets of the selection
request, precede individual calls to XtGetSelectionValue
and XtGetSelectionValueIncremental with corresponding individual
calls to XtSetSelectionParameters, and enclose these all
within XtCreateSelectionRequest and XtSendSelectionRequest.
XtGetSelectionValues and XtGetSelectionValuesIncremental
cannot be used to make selection requests with parameterized targets.
To retrieve any target parameters needed
to perform a selection conversion, the selection owner calls XtGetSelectionParameters.
owner | Specifies the widget that owns the specified selection. |
Selection | Specifies the selection being processed. |
request_id | Specifies the requestor id in the case of incremental selections, or NULL in the case of atomic transfers. |
type_return | Specifies a pointer to an atom in which the property type of the parameters are stored. |
value_return | Specifies a pointer into which a pointer to the parameters are to be stored. A NULL is stored if no parameters accompany the request. |
length_return | Specifies a pointer into which the number of data elements in value_return of size indicated by format_return are stored. |
format_return | Specifies a pointer into which the size in bits of the parameter data in the elements of value is stored. |
XtGetSelectionParameter
may only be called from within an XtConvertSelectionProc
or from within the first call to an XtConvertSelectionIncrProc
with a new request_id.
11.5.5. Generating MULTIPLE Requests
To have the Intrinsics bundle multiple
calls to make selection requests into a single request using a
MULTIPLE target, use XtCreateSelectionRequest and XtSendSelectionRequest.
requestor | Specifies the widget making the request. Must be of class Core or any subclass thereof. |
selection | Specifies the particular selection desired. |
When XtCreateSelectionRequest is called,
subsequent calls to XtGetSelectionValue, XtGetSelectionValueIncremental,
XtGetSelectionValues and XtGetSelectionValuesIncremental,
with the requestor and selection as specified to XtCreateSelectionRequest
are bundled into a single selection request with multiple targets.
The request is made by calling XtSendSelectionRequest.
When XtSendSelectionRequest
is called with a value of requestor and selection matching a previous
call to 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 XtGetSelectionValue, XtGetSelectionValueIncremental,
XtGetSelectionValues and XtGetSelectionValueIncremental
are invoked.
Multi-threaded applications should
lock the application context before calling XtCreateSelectionRequest
and release the lock after calling 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.
To relinquish the composition of a
MULTIPLE request without sending it, use XtCancelSelectionRequest
.
requestor | Specifies the widget making the request. Must be of class Core or any subclass thereof. |
selection | Specifies the particular selection desired. |
When XtCancelSelectionRequest
is called, any requests queued since the last call to XtCreateSelectionRequest
for the same widget and selection are discarded and any resources
reserved are released. A subsequent call to XtSendSelectionRequest
will not result in any request being made. Subsequent calls to
XtGetSelectionValue, XtGetSelectionValues, XtGetSelectionValueIncremental
or XtGetSelectionValuesIncremental will not be deferred.
11.5.6. Auxiliary Selection Properties
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 Intrinsics provides two interfaces for acquiring
temporary property names.
To acquire a temporary property name atom for use in a selection request, the client may call XtReservePropertyAtom.
w | Specifies the widget making a selection request. |
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.
To return a temporary property name
atom for reuse and to delete the property named by that atom,
use XtReleasePropertyAtom.
w | Specifies the widget used to reserve the property name atom. |
atom | Specifies the property name atom returned by XtReservePropertyAtom that is to be released for reuse. |
XtReleasePropertyAtom
marks the specified property name atom as no longer in use and
insures that any property having that name on the specified widget's
window is deleted. If atom does not specify a value returned
by XtReservePropertyAtom for the specified widget, the
results are undefined.
11.5.7. Retrieving the Most Recent Timestamp
To retrieve the timestamp from the
most recent call to XtDispatchEvent that contained a timestamp,
use XtLastTimestampProcessed.
display | Specifies an open display connection. |
If no KeyPress, KeyRelease,
ButtonPress, ButtonRelease, MotionNotify,
EnterNotify, LeaveNotify, PropertyNotify,
or SelectionClear event has yet been passed to XtDispatchEvent
for the specified display, XtLastTimestampProcessed returns
zero.
11.5.8. Retrieving the Most Recent Event
To retrieve the event from the most
recent call to XtDispatchEvent for a specific display,
use XtLastEventProcessed .
display | Specifies the display connection from which to retrieve the event. |
Returns the last event passed to XtDispatchEvent
for the specified display. Returns NULL if there is no such
event. The client must not modify the contents of the returned
event.
Home |
---|
11.6. Merging Exposure Events into a Region
The Intrinsics provide an XtAddExposureToRegion
utility function that merges Expose and 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 Xlib - C Language X Interface.
To merge Expose and GraphicsExpose
events into a region, use XtAddExposureToRegion.
event | Specifies a pointer to the Expose or GraphicsExpose event. |
region | Specifies the region object (as defined in <X11/Xutil.h>). |
The XtAddExposureToRegion function
computes the union of the rectangle defined by the exposure event
and the specified region. Then it stores the results back in region.
If the event argument is not an Expose or GraphicsExpose event,
XtAddExposureToRegion returns without an error and without
modifying region.
This function is used by the exposure
compression mechanism; see Section 7.9.3.
Home |
---|
To translate an x-y coordinate pair
from widget coordinates to root window absolute coordinates, use
XtTranslateCoords.
w | Specifies the widget. Must be of class RectObj or any subclass thereof. |
x | |
y | Specify the widget-relative x and y coordinates. |
rootx_return | |
rooty_return | Return the root-relative x and y coordinates. |
While XtTranslateCoords is similar
to the Xlib XTranslateCoordinates function, it does not
generate a server request because all the required information
already is in the widget's data structures.
Home |
---|
To translate a given window and display
pointer into a widget instance, use XtWindowToWidget .
display | Specifies the display on which the window is defined. |
Window | Specifies the drawable for which you want the widget. |
If there is a realized widget whose
window is the specified drawable on the specified display,
XtWindowToWidget returns that widget. If not and if
the drawable has been associated with a widget through XtRegisterDrawable,
XtWindowToWidget returns the widget associated with the
drawable. In other cases it returns NULL.
Home |
---|
The Intrinsics allow a client to register procedures that is called whenever a fatal or nonfatal error occurs. These facilities are intended for both error reporting and logging and for error correction or recovery.
Two levels of interface are provided:
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 system-wide file, the "error database file". The location and name of this file is implementation dependent.
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. |
To obtain the error database (for example,
to merge with an application- or widget-specific database), use
XtAppGetErrorDatabase.
app_context | Specifies the application context. |
The XtAppGetErrorDatabase function
returns the address of the error database. The Intrinsics do a
lazy binding of the error database and do not merge in the database
file until the first call to XtAppGetErrorDatabaseText
.
For a complete listing of all errors
and warnings that can be generated by the Intrinsics, see Appendix
D.
The high-level error and warning handler
procedure pointers are of type XtErrorMsgHandler.
name | Specifies the name to be concatenated with the specified type to form the resource name of the error message. |
type | Specifies the type to be concatenated with the name to form the resource name of the error message. |
class | Specifies the resource class of the error message. |
defaultp | Specifies the default message to use if no error database entry is found. |
params | Specifies a pointer to a list of parameters to be substituted in the message. |
num_params | Specifies the number of entries in params. |
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 printf
notation is used to substitute the parameters into the message.
An error message handler can obtain
the error database text for an error or a warning by calling XtAppGetErrorDatabaseText
.
app_context | Specifies the application context. |
name | |
type | Specify the name and type concatenated to form the resource name of the error message |
class | Specifies the resource class of the error message. |
default | Specifies the default message to use if an error database entry is not found. |
buffer_return | Specifies the buffer into which the error message is to be returned. |
nbytes | Specifies the size of the buffer in bytes. |
database | Specifies the name of the alternative database to be used, or NULL if the application context's error database is to be used. |
The 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 name and type are concatenated
with a single "." between them and the class is concatenated
with itself with a single "." if it does not already
contain a ".".
To return the application name and
class as passed to XtDisplayInitialize for a particular
Display, use XtGetApplicationNameAndClass.
display | Specifies an open display connection that has been initialized with XtDisplayInitialize . |
name_return | Returns the application name. |
class_return | Returns the application class. |
XtGetApplicationNameAndClass returns
the application name and
class passed to 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 Intrinsics
and must not be modified or freed by the caller.
To register a procedure to be called
on fatal error conditions, use XtAppSetErrorMsgHandler.
app_context | Specifies the application context. |
msg_handler | Specifies the new fatal error procedure, which should not return. |
XtAppSetErrorMsgHandler
returns a pointer to the previously installed high-level
fatal error handler. The default high-level fatal error
handler provided by the Intrinsics is named _XtDefaultErrorMsgand constructs a string from the error resource database and
calls XtError. Fatal error message handlers should not
return. If one does, subsequent Intrinsics behavior is undefined.
To call the high-level error handler,
use XtAppErrorMsg.
app_context | Specifies the application context. |
name | Specifies the general kind of error. |
type | Specifies the detailed name of the error. |
class | Specifies the resource class. |
default | Specifies the default message to use if an error database entry is not found. |
params | Specifies a pointer to a list of values to be stored in the message. |
num_params | Specifies the number of entries in params. |
The Intrinsics internal errors all
have class "XtToolkitError".
To register a procedure to be called
on nonfatal error conditions, use XtAppSetWarningMsgHandler
.
app_context | Specifies the application context. |
msg_handler | Specifies the new nonfatal error procedure, which usually returns. |
XtAppSetWarningMsgHandler returns
a pointer to the previously
installed high-level warning handler. The default high-level warning
handler provided by the Intrinsics is named _XtDefaultWarningMsg
and constructs a string from the error resource database
and calls XtWarning.
To call the installed high-level warning
handler, use XtAppWarningMsg.
app_context | Specifies the application context. |
name | Specifies the general kind of error. |
type | Specifies the detailed name of the error. |
class | Specifies the resource class. |
default | Specifies the default message to use if an error database entry is not found. |
params | Specifies a pointer to a list of values to be stored in the message. |
num_params | Specifies the number of entries in params. |
The Intrinsics internal warnings all
have class "XtToolkitError".
The low-level error and warning handler
procedure pointers are of type XtErrorHandler.
message | Specifies the error message. |
The error handler should display the
message string in some appropriate fashion.
To register a procedure to be called
on fatal error conditions, use XtAppSetErrorHandler.
app_context | Specifies the application context. |
handler | Specifies the new fatal error procedure, which should not return. |
XtAppSetErrorHandler returns
a pointer to the previously installed low-level fatal error handler.
The default low-level error handler provided by the Intrinsics
is _XtDefaultError. 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
Intrinsics behavior is undefined.
To call the installed fatal error procedure,
use XtAppError.
void XtAppError(app_context, message)
XtAppContext app_context;
String message;
app_context | Specifies the application context. |
message | Specifies the message to be reported. |
Most programs should use XtAppErrorMsg,
not XtAppError, to provide for customization and internationalization
of error messages.
To register a procedure to be called
on nonfatal error conditions, use XtAppSetWarningHandler
.
app | context Specifies the application context. |
handler | Specifies the new nonfatal error procedure, which usually returns. |
XtAppSetWarningHandler returns
a pointer to the previously installed low-level warning handler.
The default low-level warning handler provided by the Intrinsics
is _XtDefaultWarning. On POSIX-based systems, it prints
the message to standard error and returns to the caller.
To call the installed nonfatal error
procedure, use XtAppWarning.
app_context | Specifies the application context. |
message | Specifies the nonfatal error message to be reported. |
Most programs should use XtAppWarningMsg,
not XtAppWarning, to provide for customization and internationalization
of warning messages.
Home |
---|
A client may set the value of the WM_COLORMAP_WINDOWS
property on a widget's window by calling XtSetWMColormapWindows.
widget | Specifies the widget on whose window the WM_COLORMAP_WINDOWS property is stored. Must be of class Core or any subclass thereof. |
Iist | Specifies a list of widgets whose windows are potentially to be listed in the WM_COLORMAP_WINDOWS property. |
count | Specifies the number of widgets in list. |
XtSetWMColormapWindows returns
immediately if widget is not realized or if countmessage is
0. Otherwise, XtSetWMColormapWindows constructs an ordered
list of windows by examining each widget in list 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.
Finally, XtSetWMColormapWindows
stores the resulting window list in the WM_COLORMAP_WINDOWS
property on the specified widget's window. Refer to Section 4.1.8
in the Inter-Client Communication Conventions Manual for
details of the semantics of the WM_COLORMAP_WINDOWS property.
Home |
---|
The Intrinsics provide procedures to
look for a file by name, allowing string substitutions in a list
of file specifications. Two routines are provided for this: XtFindFile
and XtResolvePathname. XtFindFile uses an arbitrary
set of client-specified substitutions, and XtResolvePathname
uses a set of standard substitutions corresponding to the X/Open
Portability Guide (provided in printed version only) language localization conventions. Most
applications should use XtResolvePathname.
A string substitution is defined by
a list of Substitution entries.
typedef struct { char match; String substitution; } SubstitutionRec, *Substitution;
File name evaluation is handled in
an operating-system-dependent fashion by an XtFilePredicate
procedure.
filename | Specifies a potential filename. |
A file predicate procedure is called
with a string that is potentially a file name. It should return
True if this string specifies a file that is appropriate
for the intended use and False otherwise.
To search for a file using substitutions
in a path list, use XtFindFile.
path | Specifies a path of file names, including substitution characters. |
substitutions | Specifies a list of substitutions to make into the path. |
num_substitutions | Specifies the number of substitutions passed in. |
predicate | Specifies a procedure called to judge each potential file name, or NULL. |
The path parameter specifies a string that consists of a series of potential file names delimited by colons. Within each name, the percent character specifies a string substitution 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, XtFindFile looks through the specified substitutions for that character in the match field and if found replaces the percent and match characters with the string in the corresponding substitution field. A substitution 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, 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 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 True; this string is the return value for XtFindFile. If no string yields a True return from the predicate, XtFindFile returns NULL.
If the predicate parameter is NULL, an internal procedure that checks if the file exists, is readable, and is not a directory is used.
It is the responsibility
of the caller to free the returned string using XtFree
when it is no longer needed.
To search for a file using standard
substitutions in a path list, use XtResolvePathname.
display | Specifies the display to use to find the language for language substitutions. |
type | |
filename | |
suffix | Specify values to substitute into the path. |
path | Specifies the list of file specifications, or NULL. |
substitutions | Specifies a list of additional substitutions to make into the path, or NULL. |
num_substitutions | Specifies the number of entries in substitutions. |
predicate | Specifies a procedure called to judge each potential file name, or NULL. |
The substitutions specified by XtResolvePathname are determined from the value of the language string retrieved by XtDisplayInitialize for the specified display. To set the language for all applications specify "*xnlLanguage: lang" in the resource database. 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 Intrinsics make no interpretation of the parts other than to use them in substitutions as described below.
XtResolvePathname calls
XtFindFile with the following substitutions in addition
to any passed by the caller and returns the value returned by
XtFindFile:
%N | The value of the filename parameter, or the application's class name if filename is NULL. |
%T | The value of the type parameter. |
%S | The value of the suffix parameter. |
%L | The language string associated with the specified display. |
%l | The language part of the display's language string. |
%t | The territory part of the display's language string. |
%c | The codeset part of the display's language string. |
%C | The customization string retrieved from the resource database associated with display. |
%D | The value of the implementation-specific default path. |
If a path is passed to XtResolvePathname,
it is passed along to XtFindFile. If the path argument
is NULL, the value of the XFILESEARCHPATH environment variable
is passed to XtFindFile. If XFILESEARCHPATH is not
defined, an implementation-specific default path is used which
contains at least 6 entries. These entries must contain the following
substitutions:
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 |
The order of these six entries within
the path must be as given above. The order and use of substitutions
within a given entry is implementation dependent. If the path
begins with a colon, it is preceded by %N%S. If the path includes
two adjacent colons, %N%S is inserted between them.
The type parameter is intended
to be a category of files, usually being translated into a directory
in the pathname. Possible values might include "app-defaults",
"help", and "bitmap".
The suffix parameter is intended to
be appended to the file name. Possible values might include ".txt",
".dat", and ".bm".
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 type parameter is used as a subdirectory
of the language directory or of /usr/lib/X11, and suffix is appended
to the file name.
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 XFILESEARCHPATH to
%D:ourdir/%T/%N%C:ourdir/%T/%N
The customization string is obtained
by querying the resource database currently associated with the
display (the database returned by XrmGetDatabase) for the
resource application_name.customization, class application_
class.Customization where application_name and application_class
are the values returned by XtGetApplicationNameAndClass.
If no value is specified in the database, the empty string is
used.
It is the responsibility of the caller
to free the returned string using XtFree when it is no
longer needed.
Home |
---|
Applications may register functions which are called at a particular control points in the Intrinsics. These functions are intended to be used to provide notification of an "X Toolkit event", e.g. widget creation, to an external agent, e.g. 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 "hook registration" object.
To retrieve the hook registration widget, use XtHooksOfDisplay.
display | Specifies the desired display. |
The class of this object is a private, implementation-dependent, subclass of 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.
The resource names, classes, and representation
types that are specified in the hook object resource list are
Name | Class | Representation |
XtNcreateHook | XtCCallback | XtRCallback |
XtNchangeHook | XtCCallback | XtRCallback |
XtNconfigureHook | XtCCallback | XtRCallback |
XtNgeometryHook | XtCCallback | XtRCallback |
XtNdestroyHook | XtCCallback | XtRCallback |
XtNshells | XtCReadOnly | XtRWidgetList |
XtNnumShells | XtCReadOnly | XtRCardinal |
Descriptions of each of these resources:
The XtNcreateHook callback list is called from: XtCreateWidget, XtCreateManagedWidget, XtCreatePopupShell, XtAppCreateShell, and their corresponding varargs versions.
The call_data parameter in a
createHook callback may be cast to type XtCreateHookData.
typedef struct { Suing type; Widget widget; ArgList args; Cardinal num_args; } XtCreateHookDataRec, *XtCreateHookData;
The type is set to XtHcreate, widget is the newly created widget, args and num_args are the arguments passed to the create function. The callbacks are called before returning from the create function.
The call_data parameter in a changeHook callback
may be cast to type XtChangeHookData.
typedef struct { String type; Widget widget; XtPointer event_data; Cardinal num_event_data; } XtChangeHookDataRec, *XtChangeHookData;
When the changeHook callbacks are called as a result
of a call to XtSetValues or XtVaSetValues, type
is set to XtHsetValues, widget is the new widget
passed to the set_values procedure, and event_data may
be cast to type XtChangeHookSetValuesData.
typedef struct { Widget old, req; ArgList args; Cardinal num_args; } XtChangeHookSetValuesDataRec, *XtChangeHookSetValuesData;
The old, req, args, and num_args 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.
When the changeHook callbacks are called as a result of a call to XtManageChild or XtManageChildren, type is set to XtHmanageChildren, widget is the parent, event_data may be cast to type WidgetList and is the list of children being managed, and num_event_data is the length of the widget list. The callbacks are called after the children have been managed.
When the changeHook callbacks are called as a result of a call to XtUnmanageChild or XtUnmanageChildren, type is set to XtHunmanageChildren, widget is the parent, event_data may be cast to type WidgetList and is a list of the children being unmanaged, and num_event_data is the length of the widget list. The callbacks are called after the children have been unmanaged.
The changeHook callbacks are called twice as a result of a call to XtChangeManagedSet, once after unmanaging and again after managing. When the callbacks are called the first time type is set to XtHunmanageSet, widget is the parent, event_data may be cast to type WidgetList and is a list of the children being unmanaged, and num_ vent_ data is the length of the widget list. When the callbacks are called the second time the type is set to XtHmanageSet, widget is the parent, event_data may be cast to type WidgetList and is a list of the children being managed, and num_event_data is the length of the widget list.
When the changeHook callbacks are called as a result of a call to XtRealizeWidget The type is set to XtHrealizeWidget and widget is the widget being realized. The callbacks are called after the widget has been realized.
When the changeHook callbacks are called as a result of a call to XtUnrealizeWidget the type is set to XtHrealizeWidget and widget is the widget being unrealized. The callbacks are called after the widget has been unrealized.
When the changeHook callbacks are called as a result of a call to XtAddCallback, type is set to XtHaddCallback, widget is the widget to which the callback is being added, and event_data 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.
When the changeHook callbacks are called as a result of a call to XtAddCallbacks the type is set to XtHaddCallbacks, widget is the widget to which the callbacks are being added, and event_data 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.
When the changeHook callbacks are called as a result of a call to XtRemoveCallback the type is set to XtHremoveCallback, widget is the widget from which the callback is being removed, and event_data 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.
When the changeHook callbacks are called as a result
of a call to XtRemoveCallbacks, the type is set
to XtHremoveCallbacks, widget is the widget from
which the callbacks are being removed, and event_data 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.
When the changeHook callbacks are called as a result of a call to XtRemoveAllCallbacks the type is set to XtHremoveAllCallbacks and widget is the widget from which the callbacks are being removed. The callbacks are called after the callbacks have been removed from the widget.
When the changeHook callbacks are called as a result
of a call to XtAugmentTranslations the type is set
to XtHaugmentTranslations and widget is the widget
whose translations are being modified. The callbacks are called
after the widget's translations have been modified.
When the changeHook callbacks are called as a result
of a call to XtOverrideTranslations the type is set
to XtHoverrideTranslations and widget is the widget
whose translations are being modified. The callbacks are called
after the widget's translations have been modified.
When the changeHook callbacks are called as a result of a call to XtUninstallTranslations The type is XtHuninstallTranslations and widget is the widget whose translations are being uninstalled. The callbacks are called after the widget's translations have been uninstalled.
When the changeHook callbacks are called as a result of a call to XtSetKeyboardFocus the type is set to XtHsetKeyboardFocus and event_data may be cast to type Widget and is the value of the descendant argument passed to XtSetKeyboardFocus. The callbacks are called before returning from XtSetKeyboardFocus.
When the changeHook callbacks are called
as a result of a call to XtSetWMColormapWindows, type
is set to XtHsetWMColormapWindows, event_data may
be cast to type WidgetList and is the value of the list argument
passed to XtSetWMColormapWindows, and num_event_data
is the length of the list. The callbacks are called before
returning from XtSetWMColormapWindows.
When the changeHook callbacks are called as a result
of a call to XtSetMappedWhenManaged type is set
to XtHsetMappedWhenManaged and event_data may be
cast to type Boolean and is the value of the mapped_when_managed
argument passed to XtSetMappedWhenManaged. The callbacks
are called after setting the widget's mapped_when_managed field
and before realizing or unrealizing the widget.
When the changeHook callbacks are called as a result of a call to XtMapWidget type is set to XtHmapWidget and widget is the widget being mapped. The callbacks are called after mapping the widget.
When the changeHook callbacks are called as a result of a call to XtUnmapWidget typeis set to XtHunmapWidget and widget is the widget being unmapped. The callbacks are called after unmapping the widget.
When the changeHook callbacks are called as a result of a call to XtPopup, type is set to XtHpopup, widget is the widget being popped up, and event_data may be cast to type XtGrabKind and is the value of the grab_kind argument passed to XtPopup. The callbacks are called before returning from XtPopup.
When the changeHook callbacks are called as a result
of a call to XtPopupSpringLoaded, type is set to
XtHpopupSpringLoaded and widget is the widget being
popped up. The callbacks are called before returning from XtPopupSpringLoaded.
When the changeHook callbacks are called as a result
of a call to XtPopdown, type is set to XtHpopdown
and widget is the widget being popped down. The callbacks
are called before returning from XtPopdown.
A widget set which exports interfaces which change
application state without employing the Intrinsics library should
invoke the change hook itself. This is done by:
XtCallCallbacks(XtHooksOfDisplay(dpy), XtNchangeHook,
call_data);
The XtNconfigureHook callback list is called any time the Intrinsics move, resize, or configure a widget, and when XtResizeWindow is called.
The call_data parameter may be cast to type
XtConfigureHookData.
typedef struct { String type; Widget widget; XtGeometryMask changeMask; XWindowChanges changes; } XtConfigureHookDataRec, *XtConfigureHookData;
When the configureHook callbacks are called the type is XtHconfigure, widget is the widget being configured, changeMask and changes reflect the changes made to the widget. The callbacks are called after changes have been made to the widget.
The XtNgeometryHook callback list is called from XtMakeGeometryRequest and XtMakeResizeRequest once before and once after geometry negotiation occurs.
The call_data parameter may be cast to type XtGeometryHookData.
typedef struct { String type; Widget widget; XtWidgetGeometry* request; XtWidgetGeometry* reply; XtGeometryResult result; } XtGeometryHookDataRec, *XtGeometryHookData;
When the geometryHook callbacks are called prior to geometry negotiation, type is XtHpreGeometry, widget is the widget for which the request is being made, and request is the requested geometry. When the geometryHook callbacks are called after geometry negotiation, type is XtHpostGeometry, widget is the widget for which the request was made, request is the requested geometry, reply is the resulting geometry granted, and result is the value returned from the geometry negotiation.
The XtNdestroyHook callback list is called when a widget is destroyed. The call_data parameter may be cast to type XtDestroyHookData.
typedef struct { String type; Widget widget; } XtDestroyHookDataRec, *XtDestroyHookData;
When the destroyHook callbacks are called as a result of a call to XtDestroyWidget, type is XtHdestroy and widget is the widget being destroyed. The callbacks are called upon completion of phase one destroy for a widget.
The XtNshells and XtnumShells are read-only resources
which report a list of all parentless shell widgets associated
with a display.
Clients who use these hooks must exercise caution
in calling Intrinsics functions in order to avoid recursion.
11.12.2. Querying Open Displays
To retrieve a list of the Displays associated with
an application context, use XtGetDisplays.
void XtGetDisplays(app_context, dpy_return,nurn_
dpy_return)
XtAppContext app_context;
Display ***dpy_return;
Cardinal *num dpy_return;
app_context | Specifies the application context. |
dpy_return | Returns a list of open Display connections in the specified application context. |
num dpy_return | Returns the count of open Display connections in dpy_return. |
XtGetDisplays 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 XtFree.
Home |
---|
Contents | Previous Chapter | Next Chapter |