Motif Widget Writer's Guide Migration Version

Motif 2.1 Widget Writer's Guide

XmePrimarySink

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

Format

#include <Xm/TransferP.h>
Boolean XmePrimarySinkWidget
widgetXtEnum opXtPointer
location_dataTime time

DESCRIPTION

XmePrimarySink transfers data from the primary selection to a widget.

XmePrimarySink initializes an XmDestinationCallbackStruct as follows:

Sets the selection member to PRIMARY

Sets the operation member to the value of the op argument

Sets the location_data member to the value of the location_data argument

Sets the time member to the value of the time argument

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

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

Calls the destination widget's destinationProc trait method, if any, after all transfers initiated by XmNdestinationCallback procedures have finished. However, if an XmNdestinationCallback procedure has called XmTransferDone with a status of XmTRANSFER_DONE_DEFAULT, XmePrimarySink does not call the destinationProc trait 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 convertProc trait method.

widget

Specifies the widget that is the destination for the data.

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