XtSelectionCallbackProc()XtSelectionCallbackProc()Name
XtSelectionCallbackProc - interface definition for procedure called
when requested selection data is ready.
Synopsis
typedef void (*XtSelectionCallbackProc)(Widget, XtPointer, Atom *, Atom
*, XtPointer, unsigned long *, int *);
Widget w;
XtPointer client_data;
Atom *selection;
Atom *type;
XtPointer value;
unsigned long *length;
int *format;
Inputs
w Specifies the widget that requested the selection value.
client_data
Specifies data registered with this procedure when the selec‐
tion value was requested.
selection Specifies the selection that was requested (usually XA_PRI‐
MARY or XA_SECONDARY).
type Specifies the representation type of the selection value (for
example, XA_STRING).
value Specifies a pointer to the selection value.
length Specifies the number of elements in value.
format Specifies the size in bits of the data elements of value.
Description
An XtSelectionCallbackProc is registered in a call to XtGetSelectionVa‐
lue(), XtGetSelectionValues(), XtGetSelectionValueIncremental(), or
XtGetSelectionValuesIncremental(). Because interclient communication
is asynchronous, these functions cannot return the selection value
directly, and instead register an XtSelectionCallbackProc to be called
when the selection owner has converted and transferred the requested
data.
The w, client_data, and selection arguments are the same as those
passed when the selection value was requested. The type argument is a
pointer to an Atom that identifies the type of the returned data. This
is generally not the same as the Atom that was passed as the requested
target type. If the target was the Atom FILENAME, for example, the
type of the returned value will probably be XA_STRING. If the selec‐
tion owner does not respond within the Intrinsics timeout interval, the
Intrinsics call this callback with the special value XT_CONVERT_FAIL in
type. Note that XT_CONVERT_FAIL is not actually an Atom, and does not
need to be interned. An XtSelectionCallbackProc should test its type
argument to verify that the type of the data is as expected, or is at
least something it can handle.
The value argument is a pointer to the selection value. It is an array
of length elements, each element format bits long, and should be inter‐
preted as indicated by the type argument. format will be one of 8, 16,
or 32. The requesting client owns the storage allocated for the selec‐
tion value and is responsible for freeing it by calling XtFree() when
it is done with it. If there is no owner for the specified selection,
or that owner cannot convert the selected data to the requested type,
then this callback is called with value NULL and length zero.
If an XtSelectionCallbackProc is registered with XtGetSelectionValue(),
then it will only be called once, with the complete selection value
converted to the single requested target type. If it is registered
with XtGetSelectionValues(), it will be called once for each target
type that is specified in that call. Each call will pass the entire
selected values. These two functions are part of the Intrinsics atomic
selection transfer mechanism, and will only call their XtSelectionCall‐
backProc once to deliver a selection value. If the selection value is
larger than will fit in a single X protocol request, the Intrinsics
transparently handle breaking up the value and reassembling it after
transfer.
If an XtSelectionCallbackProc is registered with XtGetSelectionValueIn‐
cremental() or XtGetSelectionValuesIncremental(), then it will be
called at least twice for each selection value it delivers. These two
functions are part of the Intrinsics incremental selection transfer
mechanism, and call their XtSelectionCalbackProc to deliver the selec‐
tion value piece by piece. When the last chunk of a selection value
has been transferred, the callback is called a final time with length
zero, and a non-NULL value, which is a special signal that the transfer
is complete. The callback must free this non-NULL value, even though
the length argument is zero.
Usage
Note that the selection, type, length, and format arguments to this
callback are pointers to their values rather than the values them‐
selves. This is unusual in a procedure of this type, and you should be
sure to dereference them correctly. Note that you should not modify
the values pointed to by these arguments.
An XtSelectionCallbackProc can generally simply test type to see if it
is one of the possible values that it knows how to handle. If *type is
XT_CONVERT_FAIL, or some unrecognized type, the callback can just
return silently, or may notify the user that the selection failed by
calling XBell(), for example. It should do the same if called with
zero length and a NULL value.
When working with selections, you will have to work with Atoms. Many
standard Atoms are predefined in <X11/Xatom.h>, and have symbolic names
beginning with XA_. Atoms that are not defined in this file (TARGETS,
for example) may be interned explicitly as Atoms by calling the Xlib
function XInternAtom(). The Xmu library provides an alternate func‐
tion, XmuInternAtom() which caches Atoms on the client side. Addition‐
ally, the header <Xmu/Atoms.h> defines a number of macros, such as
XA_TARGETS(dpy), which call XmuInternAtom() and take a Display pointer
as their single argument.
Example
The following XtSelectionCallbackProc is modified from the X11R5 bitmap
client.
/* ARGSUSED */
void SelectionCallback(w, cldat, selection, type, value, length, format)
Widget w;
XtPointer cldat;
Atom *selection, *type;
XtPointer value;
unsigned long *length;
int *format;
{
BitmapWidget BW = (BitmapWidget) w;
Pixmap *pixmap;
if ((*length != 0) && (value != NULL)) {
switch (*type) {
case XA_BITMAP:
case XA_PIXMAP:
DestroyBitmapImage(&BW->bitmap.storage);
pixmap = (Pixmap *) value;
BW->bitmap.storage = GetImage(BW, *pixmap);
XFree((char *)pixmap);
break;
}
}
BW->bitmap.selection.limbo = FALSE;
}
This XtSelectionCallbackProc procedure is registered by the procedure
below, also modified from the X11R5 bitmap client. Note that this pro‐
cedure will optionally enter a local event loop so that it appears to
block. If called with wait True, then it will not return until the
selection value has been transferred.
void BWRequestSelection(w, btime, wait)
Widget w;
Time btime;
Boolean wait;
{
BitmapWidget BW = (BitmapWidget) w;
XtGetSelectionValue(w, XA_PRIMARY, XA_PIXMAP,
SelectionCallback, NULL, btime);
BW->bitmap.selection.limbo = TRUE;
if (wait)
while (BW->bitmap.selection.limbo) {
XEvent event;
XtNextEvent(&event);
XtDispatchEvent(&event);
}
}
See AlsoXtDisownSelection(1), XtGetSelectionValue(1), XtGetSelectionValueIncre‐
mental(1), XtGetSelectionValues(1), XtGetSelectionValuesIncremental(1),
XtOwnSelection(1), XtOwnSelectionIncremental(1).
Xt - Selections XtSelectionCallbackProc()
