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 own‐
ership. 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 selec‐
tion 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 oth‐
erwise.
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 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 selec‐
tion. (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.) 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 indi‐
cated 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 mem‐
ory allocated by the convert_proc.
See XtConvertSelectionProc(2), XtLoseSelectionProc(2), and XtSelection‐
DoneProc(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 con‐
tains 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 AlsoXtDisownSelection(1), XtGetSelectionValue(1),
XtConvertSelectionProc(2), XtLoseSelectionProc(2), XtSelectionDone‐
Proc(2).
Xt - Selections XtOwnSelection()
