Name

XtOwnSelectionIncremental — set the selection owner when using incremental transfers. 

Synopsis

Boolean XtOwnSelectionIncremental(w, selection, time, convert_callback, lose_callback, done_callback, cancel_callback, client_data)

      Widget w;
      Atom selection;
      Time time;
      XtConvertSelectionIncrProc convert_callback;
      XtLoseSelectionIncrProc lose_callback;
      XtSelectionDoneIncrProc done_callback;
      XtCancelConvertSelectionProc cancel_callback;
      XtPointer client_data;

Arguments

wSpecifies the widget that wishes to become the owner. 

selectionSpecifies an atom that names the selection (for example, XA_PRIMARY, XA_SECONDARY, or CLIPBOARD). 

timeSpecifies the timestamp that indicates when the selection ownership should commence.  This should be the timestamp of the event that triggered ownership; the value CurrentTime is not acceptable. 

convert_callback
Specifies the procedure that is to be called whenever the current value of the selection is requested.

lose_callback
Specifies the procedure that is to be called whenever the widget has lost selection ownership or NULL if the owner is not interested in being notified. 

done_callback
Specifies the procedure that is called after the requestor has received, the entire selection or NULL if the owner is not interested in being notified. 

cancel_callback
Specifies the procedure that is to be called when a selection request aborts because a timeout expires, or NULL if the owner is not interested in being notified. 

client_dataSpecifies the argument that is to be passed to each of the callback procedures when they are called. 

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. 

The XtOwnSelectionIncremental procedure informs the Intrinsics incremental selection mechanism that the specified widget wishes to own the selection.  It returns True if the specified widget successfully becomes the selection owner or False otherwise. 

If a done_callback is specified, the client owns the storage allocated for passing the value to the Intrinsics.  If done_callback is NULL, the convert_callback must allocate storage using XtMalloc, XtRealloc or XtCalloc and the final value specified will be freed by the Intrinsics when the transfer is complete.  After a selection transfer has started, only one of the done_callback or cancel_callback procedures will be invoked to indicate completion of the transfer. 

The lose_callback does not indicate completion of any in-progress transfers; it will be invoked at the time a SelectionClear event is dispatched regardless of any active transfers, which are still expected to continue. 

A widget that becomes the selection owner using XtOwnSelectionIncremental may use XtDisownSelection to relinquish selection ownership. 

See Also

XtAppGetSelectionTimeout(1), XtAppSetSelectionTimeout(1), XtDisownSelection(1), XtGetSelectionRequest(1), XtGetSelectionTimeout(1), XtGetSelectionValue(1), XtGetSelectionValueIncremental(1), XtGetSelectionValues(1), XtGetSelectionValuesIncremental(1), XtOwnSelection(1), XtSetSelectionTimeout(1).