Name

XtGetSelectionValueIncremental — obtain the selection value using incremental transfers. 

Synopsis

void XtGetSelectionValueIncremental(w, selection, target, selection_callback, client_data, time)

      Widget w;
      Atom selection;
      Atom target;
      XtSelectionCallbackProc selection_callback;
      XtPointer client_data;
      Time time;

Arguments

wSpecifies the widget that is making the request. 

selectionSpecifies the particular selection desired (e.g., XA_PRIMARY or XA_SECONDARY). 

targetSpecifies the type of the information that is needed about the selection (e.g., TARGETS). 

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.

timeSpecifies 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. 

Description

When using the incremental interface, an owner may have to process more than one selection request for the same selection, converted to the same target, at the same time.  The request_id argument is guaranteed to be unique among all incremental requests that are active concurrently. 

XtGetSelectionValueIncremental is similar to XtGetSelectionValue except that the selection_callback procedure will be called repeatedly upon delivery of multiple segments of the selection value.  The end of the selection value is indicated when selection_callback is called with a non-NULL value of length zero, which must still be freed by the client.  If the transfer of the selection is aborted in the middle of a transfer (for example, due to timeout), the selection_callback procedure is called with a type of XT_CONVERT_FAIL so that the requestor can dispose of the partial selection value it has collected up until that point.  Upon receiving XT_CONVERT_FAIL, the requesting client must determine for itself whether or not a partially completed data transfer is meaningful. 

See Also

XtGetSelectionValue(1), XtGetSelectionValuesIncremental(1), XtOwnSelectionIncremental(1).