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_PRI‐
MARY 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.
DescriptionXtGetSelectionValueIncremental() 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 procedure 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 trans‐
fer 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_CONVERT_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 con‐
vert 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 selection
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 selec‐
tion 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 selec‐
tions 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 incremen‐
tally. This information is lost if the selection is coalesced into a
single value.
See XtGetSelectionValue() for more information.
See AlsoXtGetSelectionValue(1), XtGetSelectionValuesIncremental(1), XtOwnSelec‐
tionIncremental(1).
Xt - Selections XtGetSelectionValueIncremental()
