Motif Widget Writer's Guide Migration Version

Motif 2.1 Widget Writer's Guide

XmeSecondaryTransfer

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

Format

#include <Xm/TransferP.h>
void XmeSecondaryTransferWidget
widgetAtom targetXtEnum
opTime time

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_DESTINATION selection.

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

Sets the selection member to SECONDARY

Sets the operation member to XmLINK if the op argument is XmLINK; sets the operation member to XmCOPY if the op argument is XmCOPY or XmMOVE.

Sets the destination_data member to the value of the target argument

XmeSecondaryTransfer makes the following sequence of calls:

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

Calls the application's XmNdestinationCallback procedures, if any.

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

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

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

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.

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 time value. 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).