Query: xtselectioa
OS: hpux
Section: 3
Format: Original Unix Latex Style Formatted with HTML and a Horizontal Scroll Bar
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 selection value was requested.
selection Specifies the selection that was requested (usually XA_PRIMARY 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 XtGetSelectionValue(), 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 selection 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
interpreted as indicated by the type argument. format will be one of 8, 16, or 32. The requesting client owns the storage allocated for
the selection 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 XtSelectionCallbackProc 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 XtGetSelectionValueIncremental() 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 selection 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 trans-
fer 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 mod-
ify 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 function, XmuInternAtom() which caches Atoms on the client side.
Additionally, 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
procedure 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 Also
XtDisownSelection(1), XtGetSelectionValue(1), XtGetSelectionValueIncremental(1), XtGetSelectionValues(1), XtGetSelectionValuesIncremen-
tal(1), XtOwnSelection(1), XtOwnSelectionIncremental(1).
Xt - Selections XtSelectionCallbackProc()