XmePrimarySink(3X)

     NAME
          XmePrimarySink - A toolkit function that transfers data from
          the primary selection to a widget

     SYNOPSIS
          #include <Xm/TransferP.h>
          Boolean XmePrimarySink(
          Widget widget,
          XtEnum op,
          XtPointer location_data,
          Time time);

     VERSION
          This page documents Motif 2.1.

     DESCRIPTION
          XmePrimarySink transfers data from the primary selection to
          a widget.

          XmePrimarySink initializes an XmDestinationCallbackStructas
          follows:

             o  Sets the selection member to PRIMARY

             o  Sets the operation member to the value of the op
                argument

             o  Sets the location_data member to the value of the
                location_data argument

             o  Sets the time member to the value of the time argument

          XmePrimarySink 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.  XmePrimarySink passes the
                initialized XmDestinationCallbackStruct as the
                call_data argument.

             2. Calls any XmNdestinationCallback procedures that the
                application has attached to the destination widget.

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

          It is the responsibility of the XmNdestinationCallback
          procedures and the destinationProc trait method to transfer
          any data to the destination widget.

          If op is XmMOVE and the data is successfully transferred,
          XmePrimarySink asks the owner of the PRIMARY selection to
          convert that selection to the DELETE target.  If the
          selection owner has called XmePrimarySource to take
          ownership of the selection, this conversion request first
          calls 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, this request then calls the owner widget's
          convertProctrait method.

          widget    Specifies the widget that is the destination for
                    the data.

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

          location_data
                    Specifies information about the location where
                    data is to be transferred.  If the value is NULL,
                    the data is to be inserted at the widget's cursor
                    position.  Otherwise, the type and interpretation
                    of the value are specific to the widget class. If
                    location_data cannot fit inside an XtPointer,
                    location_data must either be a static variable or
                    be allocated. If location_data is allocated, a
                    call must be made to XmeTransferAddDoneProc to
                    establish a procedure to free the allocated
                    memory.  The value of location_data is only valid
                    for the duration of a transfer. Once the transfer
                    done procedures start to be called, location_data
                    will no longer be stable.

          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.

     RETURN
          This function returns False if no transfers take place.
          Otherwise, it returns True.

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