XmeSecondaryTransfer(3X)

     NAME
          XmeSecondaryTransfer - A toolkit function that transfers
          data from the secondary selection to the destination widget

     SYNOPSIS
          #include <Xm/TransferP.h>
          void XmeSecondaryTransfer(
          Widget widget,
          Atom target,
          XtEnum op,
          Time time);

     VERSION
          This page documents Motif 2.1.

     DESCRIPTION
          XmeSecondaryTransfer transfers the data from the secondary
          selection to the destination widget.  A widget usually calls
          this function from an action routine that ends a secondary
          selection.  The destination widget is the owner of the
          _MOTIF_DESTINATIONselection.

          If the destination widget has used XmeSecondarySink to take
          ownership of that selection, XmeSecondaryTransfer
          initializes an XmDestinationCallbackStruct as follows:

             o  Sets the selection member to SECONDARY

             o  Sets the operation member to XmLINKif the op argument
                is XmLINK; sets the operation member to XmCOPYif the
                op argument is XmCOPY or XmMOVE.

             o  Sets the destination_data member to the value of the
                target argument

          XmeSecondaryTransfer makes the following sequence of calls:

             1. Calls the destination widget's
                destinationPreHookProctrait method, if any.
                destinationPreHookProcis one of the trait methods of
                the XmQTtransfer trait.  XmeSecondaryTransfer passes
                the initialized XmDestinationCallbackStruct as the
                call_data argument to the trait method.

             2. Calls the application's XmNdestinationCallback
                procedures, if any.

             3. Calls the destination widget's destinationProctrait
                method, if any, after all transfers initiated by the
                XmNdestinationCallbackprocedures have finished.
                However, if an XmNdestinationCallback procedure has
                called XmTransferDone with a status of
                XmTRANSFER_DONE_DEFAULT, then XmePrimarySink will not
                call the destinationProctrait method.

          It is the responsibility of the destination widget's
          XmNdestinationCallback procedures and the
          destinationProctrait method to transfer any data to the
          widget.

          If op is XmMOVE and the data is successfully transferred,
          XmeSecondaryTransfer asks the owner of the
          SECONDARYselection to convert that selection to the DELETE
          target.  In all cases, when the transfer operation is
          complete, XmeSecondaryTransfer asks the owner of the
          SECONDARYselection to convert that selection to the
          _MOTIF_LOSE_SELECTIONtarget.

          If the selection owner has called XmeSecondarySource to take
          ownership of the selection, these conversion requests first
          call the owner's XmNconvertCallback procedures, if any.  If
          no XmNconvertCallback procedures exist or if these
          procedures return a status of XmCONVERT_DEFAULT or
          XmCONVERT_MERGE, these requests then call the owner's
          convertProc trait method; convertProc is a trait method of
          the XmQTtransfer trait.

          widget    Specifies the widget that is the owner of the
                    secondary selection.

          target    Specifies a recommended target for the destination
                    widget to request when converting the secondary
                    selection.

          op        Specifies the transfer operation.  Possible values
                    are XmMOVE, XmCOPY, and XmLINK.

          time      Specifies the time of the transfer.  This is
                    usually the timestamp from the event passed to an
                    action routine.  You should call
                    XtLastTimeStampProcessed to generate the
                    timevalue.  If you set time to CurrentTime or 0,
                    UTM will automatically change the call to
                    XtLastTimeStampProcessed.

     RELATED
          XmQTtransfer(3), XmTransferDone(3), XmTransferValue(3),
          XmeClipboardSink(3), XmeClipboardSource(3),
          XmeConvertMerge(3), XmeDragSource(3), XmeDropSink(3),
          XmeGetEncodingAtom(3), XmePrimarySink(3),
          XmePrimarySource(3), XmeSecondarySink(3),
          XmeSecondarySource(3), XmeStandardConvert(3),
          XmeStandardTargets(3), and XmeTransferAddDoneProc(3).