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 wid‐
get 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 interested in being notified.
cancel_callback
Specifies the procedure that is to be called when a selec‐
tion 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 oth‐
erwise.
Availability
Release 4 and later.
DescriptionXtOwnSelection() 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 XtDisownSelec‐
tion() 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 XtCancelConvertSelctionProc(2)
for more information.
XtOwnSelectionIncremental() returns True if the specified widget suc‐
cessfully becomes the selection owner or False otherwise. The widget
may fail to become the owner if some other widget has asserted owner‐
ship 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 routines,
so that the Intrinsics can automatically free it. If a non-NULL
done_callback is specified, it is the responsibility of this procedure
or the cancel_callback to free any memory allocated by the con‐
vert_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
dispatched regardless of any active transfers, which are still expected
to continue.
A widget that becomes the selection owner using XtOwnSelectionIncremen‐
tal() 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 automatically
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 nec‐
essarily 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 wid‐
get 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 AlsoXtAppGetSelectionTimeout(1), XtAppSetSelectionTimeout(1), XtDisownSe‐
lection(1), XtGetSelectionValue(1), XtOwnSelection(1),
XtCancelConvertSelectionProc(2), XtConvertSelectionIncrProc(2), XtLos‐
eSelectionIncrProc(2), XtSelectionDoneIncrProc(2).
Xt - Selections XtOwnSelectionIncremental()
