XtOwnSelection() XtOwnSelection()
Name
XtOwnSelection - make selection data available to other clients.
Synopsis
Boolean XtOwnSelection(w, selection, time, convert_proc, lose_proc, done_proc)
Widget w;
Atom selection;
Time time;
XtConvertSelectionProc convert_proc;
XtLoseSelectionProc lose_proc;
XtSelectionDoneProc done_proc;
Inputs
w Specifies the widget that wishes to become the owner.
selection Specifies an atom that describes the type of the selection (usually XA_PRIMARY, or XA_SECONDARY).
time Specifies the time when selection ownership should commence. This should be the timestamp of the event that triggered ownership.
The value CurrentTime is not acceptable.
convert_proc
Specifies the procedure to call whenever someone requests the current value of the selection.
lose_proc Specifies the procedure to call when the widget loses selection ownership, or NULL if the owner is not interested in being called
back.
done_proc Specifies the procedure to call after a transfer completes, or NULL if the owner is not interested in being called back.
Returns
True if the widget successfully became the selection owner; False otherwise.
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 three procedures with the Intrinsics atomic data transfer mechanism: convert_proc will be
called when a client requests the selection; it must convert the selection data to the requested type. lose_proc, if non-NULL, will be
called when another widget or another client asserts ownership of the selection. (It will not be called if the widget relinquishes owner-
ship by calling XtDisownSelection() or if the widget fails to gain ownership in the first place.) done_proc, if non-NULL will be called
after the requesting client has received the data converted by convert_proc.
XtOwnSelection() returns True if the widget has successfully become the owner and False otherwise. The widget may fail to become the owner
if some other widget has asserted ownership after this widget, as indicated by time. Widgets can lose selection ownership either because
another client more recently asserted ownership of the selection, or because the widget voluntarily gave up ownership of the selection with
XtDisownSelection().
If done_proc is NULL, then convert_proc 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_proc is specified, it is the responsibility of this procedure to free
any memory allocated by the convert_proc.
See XtConvertSelectionProc(2), XtLoseSelectionProc(2), and XtSelectionDoneProc(2), for information on how to write the procedures that are
passed to this function.
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.
Selection ownership is not restricted to widgets; an application can export data as well. The widget argument to XtOwnSelection() 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
XtDisownSelection(1), XtGetSelectionValue(1),
XtConvertSelectionProc(2), XtLoseSelectionProc(2), XtSelectionDoneProc(2).
Xt - Selections XtOwnSelection()