Name
XtConvertSelectionProc — prototype procedure to convert selection data.
Synopsis
typedef Boolean (∗XtConvertSelectionProc)(Widget, Atom ∗, Atom ∗, Atom ∗, XtPointer ∗, unsigned long ∗, int ∗);
Widget w;
Atom ∗selection;
Atom ∗target;
Atom ∗type_return;
XtPointer ∗value_return;
unsigned long ∗length_return;
int ∗format_return;
Arguments
wSpecifies the widget that currently owns this selection.
selectionSpecifies the atom that describes the type of selection requested (for example, XA_PRIMARY or XA_SECONDARY).
targetSpecifies the target type of the selection that has been requested, which indicates the desired information about the selection (for example, FILENAME, TEXT, XA_WINDOW).
type_returnSpecifies 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 the property type XA_STRING.
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. If the selection owner has provided an XtSelectionDoneProc for the selection, this storage is owned by the selection owner; otherwise, it is owned by the Intrinsics selection mechanism, which frees it by calling XtFree when it is done with it.
length_return
Specifies a pointer into which the number of elements in value (each of size indicated by format) 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.
Description
Arbitrary widgets (possibly not all in the same application) can communicate with each other by means of the Toolkit global selection mechanism, which is defined in the Inter-Client Communications Manual (see Volume Zero, X Protocol Reference Manual). The Intrinsics provide functions for providing and receiving selection data in one logical piece (atomic transfers). The actual transfer between the selection owner and the Intrinsics is not required to be atomic; the Intrinsics will break a too-large selection into smaller pieces for transport if necessary.
The Intrinsics call the selection owner’s XtConvertSelectionProc to obtain selection data when another client requests it. The XtConvertSelectionProc is registered when the selection owner asserts its ownership.
The XtConvertSelectionProc should return 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 they are prepared to convert their selection into. This is used by the selection owner. The list of targets should be an array of interned Atoms, and return_type should be XA_ATOM.
Most type Atoms are defined in <X11/Xatom.h>. Those that are not (for example, TARGETS) must be interned explicitly as Atoms by calling the Xlib function XInternAtom.
Examples
The example below shows code to handle standard selection targets. This code is taken from the BitmapEdit widget developed in Volume Four, X Toolkit Intrinsics Programming Manual; however, this portion of it is adapted from the standard client xclipboard, and can be copied almost directly into your widget.
static Boolean
convert_proc(w, selection, target, type_return, value_return,
length_return, format_return)
Widget w;
Atom ∗selection;
Atom ∗target;
Atom ∗type_return;
XtPointer ∗value_return;
unsigned long ∗length_return;
int ∗format_return;
{
BitmapEditWidget cw = (BitmapEditWidget) w;
int x, y;
int width, height;
XSelectionRequestEvent∗ req = XtGetSelectionRequest(w,
∗selection, (XtRequestId) NULL);
/∗ handle all required atoms, and the one that we use ∗/
if (∗target == XA_TARGETS(XtDisplay(cw))) {
/∗ TARGETS handling copied from xclipboard.c ∗/
Atom∗ targetP;
Atom∗ std_targets;
unsigned long std_length;
XmuConvertStandardSelection(cw, req->time, selection,
target, type_return,
(XtPointer∗)&std_targets,
&std_length, format_return);
∗value_return = XtMalloc(sizeof(Atom)∗(std_length + 1));
targetP = ∗(Atom∗∗)value_return;
∗length_return = std_length + 1;
∗targetP++ = cw->bitmapEdit.target_atom;
bcopy((char∗)std_targets, (char∗)targetP, \
sizeof(Atom)∗std_length);
XtFree((char∗)std_targets);
∗type_return = XA_ATOM;
∗format_return = sizeof(Atom) ∗ 8;
return(True);
}
/∗ Xt already handles MULTIPLE, no branch necessary ∗/
else if (∗target == cw->bitmapEdit.target_atom) {
char ∗data;
width = cw->bitmapEdit.select_end_x -
cw->bitmapEdit.select_start_x;
height = cw->bitmapEdit.select_end_y -
cw->bitmapEdit.select_start_y;
/∗ 8 chars is enough for two 3-digit numbers and two
delimiters ∗/
∗length_return = ((width ∗ height) + 8) ∗ sizeof(char);
data = XtMalloc(∗length_return);
sprintf(data, "%d@%d~", width, height);
for (x = 0; x < width; x++) {
for (y = 0; y < height; y++) {
data[8 + x + (y ∗ width)] = cw->bitmapEdit.cell[
(x + cw->bitmapEdit.select_start_x) +
((y + cw->bitmapEdit.select_start_y) ∗
cw->bitmapEdit.pixmap_width_in_cells)];
}
}
∗value_return = data;
∗type_return = cw->bitmapEdit.target_atom;
∗format_return = 8; /∗ number of bits in char ∗/
return(True);
}
else {
if (XmuConvertStandardSelection(cw, CurrentTime, selection,
target, type_return, value_return,
length_return, format_return))
return True;
else {
XtWarning("bitmapEdit: requestor is requesting\
unsupported selection target type.\n");
return(False);
}
}
}
Overall, this code handles the TARGETS atom in the first branch, the expected selection target in the second, and any remaining standard atoms and any unknown atoms as two cases in the third branch. For ICCCM-compliant code, you can copy this entire function into your widget and then write just the second branch. Note that branches that successfully provide the requested data return True, and ones that don’t return False. The ICCCM also specifies that functions implementing selections must be able to respond to a MULTIPLE target value, which is used to handle selections too large to fit into a single property. However, the necessary handling is done by the Intrinsics. Your procedures do not need to worry about responding to the MULTIPLE target value; a selection request with this target type will be transparently transformed into a series of smaller transfers.
In the first branch you will also need to change the reference to the instance part field that stores the target atom used for selections, bitmapEdit.target_atom. If your widget uses a predefined atom or one supported by the Xmu facility, you would reference that atom here instead of the instance part field. If you called XInternAtom in initialize and stored the result in an instance part field, you specify that here.
See Also
XtFree(1), XtGetSelectionValue(1), XtGetSelectionValueIncremental(1), XtOwnSelection(1), XtConvertSelectionIncrProc(2), XtSelectionDoneProc(2).