XtConvertSelectionIncrProc()XtConvertSelectionIncrProc()Name
XtConvertSelectionIncrProc - interface definition for a procedure to
return selection data incrementally.
Synopsis
typedef Boolean (*XtConvertSelectionIncrProc)(Widget, Atom*, Atom*,
Atom*, XtPointer*, unsigned long*, int*, unsigned long*, XtPointer,
XtRequestId*);
Widget w;
Atom *selection;
Atom *target;
Atom *type_return;
XtPointer *value_return;
unsigned long *length_return;
int *format_return;
unsigned long *max_length;
XtPointer client_data;
XtRequestId *request_id;
Inputs
w Specifies the widget which currently owns this selection.
selection Specifies the atom that names the selection requested (usu‐
ally XA_PRIMARY or XA_SECONDARY).
target Specifies the type of information requested about selection
(FILENAME, TEXT, or XA_WINDOW, for example).
max_length Specifies the maximum number of bytes which may be trans‐
ferred at any one time.
client_data Specifies the data registered with this procedure in the
call to XtOwnSelectionIncremental().
request_id Identifies the transfer request (multiple concurrent
requests are possible) for which data is to be returned.
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.
Availability
Release 4 and later.
Description
An XtConvertSelectionIncrProc is registered in a call to XtOwnSelec‐
tionIncremental(). This procedure is called repeatedly by the Intrin‐
sics selection mechanism to get pieces of the selection value.
On the first call with a particular request_id, an XtConvertSelection‐
IncrProc should determine whether it will be able to convert the selec‐
tion to the requested target type. If not, it should return False
immediately. Otherwise, it should allocate memory (of not more than
max_length bytes) and place the first "chunk" or increment of the con‐
verted selection value in it. Then it should set value_return to the
address of this allocated memory, and set type_return, length_return,
and format_return as appropriate and return True.
On subsequent calls with the same request_id, an XtConvertSelectionIn‐
crProc() should return the converted subsequent chunks of the selection
value, again setting all the return arguments and returning True. It
may reuse the previously allocated block of memory.
When an XtConvertSelectionIncrProc is called after it has transferred
the last of the selection data, it 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 re-used by the Intrinsics to begin a new transfer.
If an XtSelectionDoneIncrProc proc was registered with the XtConvertSe‐
lectionIncrProc, then that procedure is responsible for freeing any
memory allocated for a transfer when that transfer completes. If no
XtSelectionDoneIncrProc is registered, the Intrinsics will automati‐
cally call XtFree() on the final value returned. If an incremental
transfer is aborted before it completes, the XtCancelConvertSelection‐
Proc is responsible for freeing any memory allocated for that transfer.
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 return_type should be XA_ATOM.
An XtConvertSelectionIncrProc will not be called with a target of MUL‐
TIPLE or TIMESTAMP (see Section 2.6.2 of the Inter-Client Communica‐
tions Conventions Manual, Appendix L in Volume Zero). The Intrinsics
automatically break a MULTIPLE request into a series of calls to the
procedure, and automatically respond to a TIMESTAMP request using the
time passed to XtOwnSelectionIncremental().
See XtConvertSelectionProc(2) for more information on handling requests
for the selection value.
Usage
An XtConvertSelectionIncrProc must be prepared to handle multiple con‐
current transfer requests; i.e., it cannot assume that it will be
called repeatedly with a single request_id until that transfer is com‐
plete, and then be called with a new request_id. For this reason, it
must remember how far along in each transfer it is for each request_id.
The Xlib Context Manager (see XSaveContext()) can be useful for this
purpose.
See AlsoXtGetSelectionValueIncremental(1), XtGetSelectionValuesIncremental(1),
XtOwnSelectionIncremental(1),
XtCancelConvertSelectionProc(2), XtConvertSelectionProc(2), XtLoseSe‐
lectionIncrProc(2), XtSelectionDoneIncrProc(2).
Xt - Selections XtConvertSelectionIncrProc()
