XtOwnSelectionIncremental() XtOwnSelectionIncremental()
Name
XtOwnSelectionIncremental - make selection data available to other clients using the incremental transfer interface.
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;
Inputs
w Specifies the widget that wishes to become the owner.
selection Specifies an atom that names the selection (usually, XA_PRIMARY or XA_SECONDARY).
time Specifies 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 when the widget loses 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 inter-
ested 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_data Specifies the argument that is to be passed to each of the callback procedures when they are called.
Returns
True if the widget successfully became the selection owner; False otherwise.
Availability
Release 4 and later.
Description
XtOwnSelection() tells the Intrinsics that as of time time widget w has data it would like to make available to other clients through the
selection named by selection. It registers four procedures with the Intrinsics incremental data transfer mechanism and client_data to be
passed to each of these procedures.
convert_callback will be called when a client requests the value of the selection. It will be called repeatedly to obtain segments of the
selected value until it returns a non-NULL value of zero length. Note that this callback must be able to handle multiple transfer requests
at various stages of completion. See XtConvertSelectionIncrProc(2) for more information.
lose_callback will be called, if non-NULL, when another widget or another client asserts ownership of the selection. (It will not be
called if the widget relinquishes ownership by calling XtDisownSelection() or if the widget fails to gain ownership in the first place.)
See XtLoseSelectionIncrProc(2) for more information.
done_callback will be called, if non-NULL, when all segments of a selection have been transferred. See XtSelectionDoneIncrProc(2) for more
information.
cancel_callback will be called, if non-NULL, if a selection request is aborted because a timeout expires. See XtCancelConvertSelction-
Proc(2) for more information.
XtOwnSelectionIncremental() returns True if the specified widget successfully becomes the selection owner or False otherwise. The widget
may fail to become the owner if some other widget has asserted ownership after this widget, as indicated by time.
If done_callback is NULL, then convert_callback must allocate memory for the transfer with one of the Intrinsics memory allocation rou-
tines, so that the Intrinsics can automatically free it. If a non-NULL done_callback is specified, it is the responsibility of this proce-
dure or the cancel_callback to free any memory allocated by the convert_callback. After a selection transfer has started, only one of the
done_callback or cancel_callback procedures will be invoked to indicate completion or termination 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 dis-
patched 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.
Usage
Note that XtOwnSelection() simply informs the Intrinsics that a widget would like to own the selection. It is convert_proc that must do
the real work of transferring the selected data.
Most selection data can be transferred using the Intrinsics simpler atomic transfer mechanism; see XtOwnSelection(). For some widgets,
however, an incremental transfer may be more convenient. A text widget that supports disjoint selections of text, for example, may prefer
to export each contiguous segment individually rather than copying them all into one large block. Note that the Intrinsics will automati-
cally break up and reassemble blocks of data if they are too big for transfer using the underlying X protocol; large data size is therefore
not necessarily a reason for using incremental transfers.
Selection ownership is not restricted to widgets; an application can export data as well. The widget argument to XtOwnSelectionIncremen-
tal() serves mainly as a handle to be passed to the various procedures. You can use any widget, but it will make the most sense to use the
widget that contains the data you will be exporting.
XA_PRIMARY and XA_SECONDARY are symbolic names for predefined atoms. They are defined in <X11/Xatom.h>. You can export data over a custom
selection, but if you do, only clients that know the selection name will be able to request the data.
XtLastTimestampProcessed() is a convenient way to obtain a timestamp suitable for use as the time argument.
See Also
XtAppGetSelectionTimeout(1), XtAppSetSelectionTimeout(1), XtDisownSelection(1), XtGetSelectionValue(1), XtOwnSelection(1),
XtCancelConvertSelectionProc(2), XtConvertSelectionIncrProc(2), XtLoseSelectionIncrProc(2), XtSelectionDoneIncrProc(2).
Xt - Selections XtOwnSelectionIncremental()