XtConvertSelectionProc()XtConvertSelectionProc()Name
XtConvertSelectionProc - interface definition for a procedure to return
requested 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;
Inputs
w Specifies the widget that currently owns the selection.
selection Specifies the atom that describes the selection requested
(usually XA_PRIMARY or XA_SECONDARY).
target Specifies the type of information requested about the
selection (FILENAME, TEXT, or XA_WINDOW, for example).
Outputs
type_return Returns the property type of the converted value of the
selection. (Both FILENAME and TEXT might have property
type XA_STRING, for example.)
value_return
Returns the address of the converted value of the selec‐
tion. The selection owner is responsible for allocating
this storage.
length_return
Returns the length of the value in value_return, in units
as specified by format_return.
format_return
Returns the size in bits of each of the length_return ele‐
ments of value_return. Must be 8, 16, or 32; this informa‐
tion allows the X server to byte-swap the data if neces‐
sary.
Returns
True if the conversion is successful; False otherwise.
Description
An XtConvertSelectionProc is registered in a call to XtOwnSelection()
when a client requests to become the owner of a selection. It is
called when the value of the selection is requested.
If an XtConvertSelectionProc cannot convert the selection data to the
requested target type, it should return False. Otherwise, it should
convert the value, allocating memory for it if necessary. It should
store the type of the converted data (which is generally not the same
as target) in type_return, store the address of the converted value in
value_return, store the number of blocks of converted data in
length_return, store the size of each of those blocks of converted data
in format_return, and return True.
If an XtSelectionDoneProc was registered with the XtConvertSelection‐
Proc, then this procedure will be called when the requestor has copied
the converted data, and should free any memory allocated for that data.
If no XtSelectionDoneProc was registered, then the Intrinsics will
automatically free the returned value by calling XtFree().
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. The list of targets should be an
array of interned Atoms, and type_return should be XA_ATOM.
An XtConvertSelectionProc will not be called with a target of MULTIPLE
or TIME
STAMP (see Section 2.6.2 of the Inter-Client Communications Conventions
Manual, Appendix L in Volume Zero). The Intrinsics automatically break
a MULTIPLE request into a series of calls to the procedure, and auto‐
matically respond to a TIMESTAMP request using the time passed to
XtOwnSelection().
Usage
Most widgets that display data of any sort should make that data
selectable by the user, and should call XtOwnSelection() with an XtCon‐
vertSelectionProc when data is selected by the user.
Although it is usually widgets that handle selections, there are times
when an application might want to export selected data. A calculator
program might have a menu item labeled "Cut", for example, which would
call XtOwnSelection() to make the currently displayed value available
for pasting. (It would probably also have a "Paste" command that would
call XtGetSelectionValue() to obtain the currently selected value and
use it, if it is a number.)
An XtConvertSelectionProc transfers the selection value in a single
block, and relies on the Intrinsics to break that block up and reassem‐
ble it as necessary if it is larger than the maximum size for a single
transfer to the X server. This procedure and the XtOwnSelection()
function that registers it are part of the Intrinsics atomic selection
transfer mechanism. In Release 4 and later, the Intrinsics also sup‐
port an incremental transfer mechanism which allows the selection owner
to return the selection value a piece at a time. If there is a large
amount of selected data, the incremental interface means that it does
not have to be copied all at once-on systems with limited memory, this
can be important. Also, some selections, such as disjoint pieces of
text in a text widget, are more naturally transferred in separate
pieces. See XtOwnSelectionIncremental(1) and XtConvertSelectionIncr‐
Proc(2) for more information.
The Xmu function XmuConvertStandardSelection() converts the selection
to the following standard targets: CLASS, CLIENT_WINDOW, DEC‐
NET_ADDRESS, HOSTNAME, IP_ADDRESS, NAME, OWNER_OS, TARGETS, TIMESTAMP,
and USER. It is used in the example shown below. See Section 2.6.5 of
the Inter-Client Communications Conventions Manual for the meaning of
these standard targets. See XmuConvertStandardSelection(6) for more
information.
When working with selections, you will have to work with Atoms. Many
standard Atoms are defined in <X11/Xatom.h>. Those that are not (for
example, TARGETS) 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 example XtConvertSelectionProc below is from the client xclipboard.
It can be easily adapted for use by most widgets and applications.
Note the use of predefined Atoms and the Xmu Atom macros. XmuConvert‐
StandardSelection() is used to convert to the standard target types,
and also (when the target is TARGETS) to return a list of those stan‐
dard types that it supports. This list is then augmented with the
types supported explicitly by the procedure.
#include <X11/Xatom.h>
#include <X11/Xmu/Atoms.h>
#include <X11/Xmu/StdSel.h>
static Boolean ConvertSelection(w, selection, target,
type, value, length, format)
Widget w;
Atom *selection, *target, *type;
XtPointer *value;
unsigned long *length;
int *format;
{
Display* d = XtDisplay(w);
XSelectionRequestEvent* req =
XtGetSelectionRequest(w, *selection, (XtRequestId)NULL);
if (*target == XA_TARGETS(d)) {
Atom* targetP;
Atom* std_targets;
unsigned long std_length;
XmuConvertStandardSelection(w, req->time, selection, target, type,
(caddr_t*)&std_targets, &std_length, format);
*value = XtMalloc(sizeof(Atom)*(std_length + 5));
targetP = *(Atom**)value;
*targetP++ = XA_STRING;
*targetP++ = XA_TEXT(d);
*targetP++ = XA_LENGTH(d);
*targetP++ = XA_LIST_LENGTH(d);
*targetP++ = XA_CHARACTER_POSITION(d);
*length = std_length + (targetP - (*(Atom **) value));
bcopy((char*)std_targets, (char*)targetP, sizeof(Atom)*std_length);
XtFree((char*)std_targets);
*type = XA_ATOM;
*format = 32;
return True;
}
if (*target == XA_LIST_LENGTH(d)
*target == XA_LENGTH(d))
{
long * temp;
temp = (long *) XtMalloc(sizeof(long));
if (*target == XA_LIST_LENGTH(d))
*temp = 1L;
else /* *target == XA_LENGTH(d) */
*temp = (long) TextLength (text);
*value = (caddr_t) temp;
*type = XA_INTEGER;
*length = 1L;
*format = 32;
return True;
}
if (*target == XA_CHARACTER_POSITION(d))
{
long * temp;
temp = (long *) XtMalloc(2 * sizeof(long));
temp[0] = (long) 0;
temp[1] = TextLength (text);
*value = (caddr_t) temp;
*type = XA_SPAN(d);
*length = 2L;
*format = 32;
return True;
}
if (*target == XA_STRING
*target == XA_TEXT(d)
*target == XA_COMPOUND_TEXT(d))
{
extern char *_XawTextGetSTRING();
if (*target == XA_COMPOUND_TEXT(d))
*type = *target;
else
*type = XA_STRING;
*length = TextLength (text);
*value = _XawTextGetSTRING((TextWidget) text, 0, *length);
*format = 8;
return True;
}
if (XmuConvertStandardSelection(w, req->time, selection, target, type,
(caddr_t *)value, length, format))
return True;
return False;
}
See AlsoXtGetSelectionValue(1), XtOwnSelection(1),
XtConvertSelectionIncrProc(2), XtSelectionDoneProc(2),
XmuConvertStandardSelection(6).
Xt - Selections XtConvertSelectionProc()
