hpux man page for xtconvertsa

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