Motif Widget Writer's Guide Migration Version

Motif 2.1 Widget Writer's Guide

XmeNamedSink

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

Format

#include <Xm/TransferP.h>
Boolean XmeNamedSinkWidget
widgetAtom named_selectionXtEnum
opXtPointer location_dataTime
time

DESCRIPTION

XmeNamedSink transfers data from the specified selection to a widget.

This routine initializes an XmDestinationCallbackStruct with the selection member set to named_selection, the operation member set to the value of the op argument, the location_data member set to the value of the location_data argument, and the time member set to the value of the time argument. The location_data value contains 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.

This routine calls the widget's destinationPreHookProc XmQTtransfer trait method with this XmDestinationCallbackStruct. It then calls the widget's XmNdestinationCallback procedures, if any. Unless an XmNdestinationCallback procedure has called XmTransferDone with a status other than XmTRANSFER_DONE_DEFAULT, this routine calls the widget's destinationProc XmQTtransfer trait method after all transfers initiated by callback procedures have finished. It is the responsibility of the XmNdestinationCallback procedures and the destinationProc method to transfer any data to the widget.

If op is XmMOVE and the data is successfully transferred, XmeNamedSink asks the owner of the selection named by named_selection to convert that selection to the DELETE target. If the selection owner has called XmeNamedSource 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's convertProc XmQTtransfer trait method.

widget

Specifies the widget that is the destination for the data.

named_selection

Specifies the desired selection from which to obtain 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 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), XmeNamedSource(3), XmeSecondarySink(3), XmeSecondarySource(3), XmeSecondaryTransfer(3), XmeStandardConvert(3), XmeStandardTargets(3), and XmeTransferAddDoneProc(3).