XtGetSelectionValueIncremental() XtGetSelectionValueIncremental()
Name
XtGetSelectionValueIncremental - obtain the selection value using incremental transfers.
Synopsis
void XtGetSelectionValueIncremental(w, selection, target, callback,
client_data, time)
Widget w;
Atom selection;
Atom target;
XtSelectionCallbackProc callback;
XtPointer client_data;
Time time;
Inputs
w Specifies the widget that is making the request. Must be of class Core or any subclass thereof.
selection Specifies the particular selection desired (usually XA_PRIMARY or XA_SECONDARY).
target Specifies the type of the information that is needed about the selection.
callback Specifies the callback procedure that is to be called to receive each data segment.
client_data
Specifies client-specific data that is to be passed to the specified callback procedure when it is invoked.
time Specifies the timestamp that indicates when the selection request was initiated. This should be the timestamp of the event which
triggered this request; the value CurrentTime is not acceptable.
Availability
Release 4 and later.
Description
XtGetSelectionValueIncremental() initiates an ICCCM-compliant request to the owner of the selection identified by selection to convert the
selected value to the type identified by target, and registers callback with the Intrinsics incremental selection interface as the proce-
dure to call when segments of the requested value are delivered.
callback will be called some time after XtGetSelectionValue() is called. It may be called before or after XtGetSelectionValue() returns.
It will be called once for each segment of the selection value, and a final time with a non-NULL value (which must be freed) and a zero
length. This final call is simply an indication that the transfer is complete.
If the transfer times out or is otherwise aborted before it completes, callback will be called with type pointing to the atom XT_CON-
VERT_FAIL. In this case, the requestor must decide whether to abort the entire transfer or to proceed with the partially transferred
selection.
If there is no owner for the selection or if the owner could not convert to the requested type, callback will be called with a value of
NULL and length zero.
See XtSelectionCallbackProc(2) for more information on how to write a callback appropriate to register with this function.
Usage
Because of the asynchronous nature of interclient communication, it is not possible to call a function that returns the value of the selec-
tion immediately. When you need the value of the selection, to paste it into a widget, for example, you must request the value of the
selection and supply a callback which will be called at some later time. It is in this callback that you can actually perform your paste.
Most applications and widgets can use XtGetSelectionValue() which will call the specified callback exactly once with the value. Some
selection owners will find it more natural to supply the selection value in an incremental fashion, delivering one piece at a time. This
could be the case when the selection is large disjoint pieces of text in a text editor widget, for example. The selection requestor may
request selections incrementally, but is never required to do so-the Intrinsics will coalesce an incrementally transferred value if the
requestor requests it through the atomic XtGetSelectionValue() interface.
In some cases, however, it may be more natural to receive selection values through the incremental interface. Note that there is informa-
tion in the boundaries of each segment that is transferred incrementally. This information is lost if the selection is coalesced into a
single value.
See XtGetSelectionValue() for more information.
See Also
XtGetSelectionValue(1), XtGetSelectionValuesIncremental(1), XtOwnSelectionIncremental(1).
Xt - Selections XtGetSelectionValueIncremental()