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()