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 (usually 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 transferred 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 selection. 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 elements of value_return. Must be 8, 16, or 32; this information allows
the X server to byte-swap the data if necessary.
Returns
True if the conversion is successful; False otherwise.
Availability
Release 4 and later.
Description
An XtConvertSelectionIncrProc is registered in a call to XtOwnSelectionIncremental(). 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 XtConvertSelectionIncrProc should determine whether it will be able to convert the
selection 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 converted 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 XtConvertSelectionIncrProc() should return the converted subsequent chunks of the selec-
tion 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 XtConvertSelectionIncrProc, 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 pre-
pared 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 MULTIPLE 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 concurrent transfer requests; i.e., it cannot assume that it will be
called repeatedly with a single request_id until that transfer is complete, 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 Also
XtGetSelectionValueIncremental(1), XtGetSelectionValuesIncremental(1), XtOwnSelectionIncremental(1),
XtCancelConvertSelectionProc(2), XtConvertSelectionProc(2), XtLoseSelectionIncrProc(2), XtSelectionDoneIncrProc(2).
Xt - Selections XtConvertSelectionIncrProc()