hpux man page for xtownseleca

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()