XmQTtransfer

A trait that implements data transfer to and from a widget

Format

#include <Xm/TransferT.h>
 
typedef struct {
        	int                             version;
        	XmConvertCallbackProc           convertProc;
        	XmDestinationCallbackProc       destinationProc;
        	XmDestinationCallbackProc       destinationPreHookProc;
} XmTransferTraitRec, *XmTransferTrait;
void
(*XmConvertCallbackProc)WidgetXtPointerXtPointer
void
(*XmDestinationCallbackProc)WidgetXtPointerXtPointer

DESCRIPTION

The XmQTtransfer trait is installed on any widget that can be a source or destination for data transfer. The usual means of transferring data is the conversion of a selection. The selections supported by Motif are PRIMARY, SECONDARY, CLIPBOARD, and _MOTIF_DROP (for drag and drop operations). A widget can be the source or destination for zero or more of these selections.

If your widget is to be a source of data in a transfer, then your widget must supply a convertProc trait method. This trait method is responsible for converting data to a requested target. If your widget is to be a data transfer destination, then your widget must supply a destinationProc trait method and can optionally supply a destinatinoPreHookProc trait method. The destinationProc trait method is responsible for requesting target(s) from the source and for providing the name of a transfer procedure to handle the returned data. The destinationPreHookProc trait method is used to prepare data for the destinationProc method.

The standard Motif widgets XmContainer, XmLabel, XmLabelGadget, XmList, XmScale, XmText, and XmTextField all hold this trait. XmLabel, XmLabelGadget, XmList, and XmScale provide only convertProc methods. XmContainer, XmText, and XmTextField provide both convertProc and destinationProc methods.

(See the ExmStringTransfer demonstration widget in the demos/widgets/Exm/lib directory for an example usage of this trait.)

The convertProc Trait Method

void convertProcWidget
widgetXtPointer client_dataXtPointer
call_data

The convertProc method is invoked when the widget is the source for a data transfer operation. This method converts a selection to a requested target. The call_data argument is a pointer to an XmConvertCallbackStruct structure. The method typically examines the selection and target members of this structure. It returns the converted data in the value member and returns an indicator of the conversion status in the status member.

When the target member of the structure is TARGETS, the convertProc method usually provides data by calling XmeStandardTargets and then adding any targets to which the convertProc method converts data. The method can call XmeStandardConvert to convert data to any of the standard targets.

The convertProc method is invoked after any XmNconvertCallback procedures are called. The callback procedures can perform all or part of the conversion themselves, refuse the conversion, or let the convertProc method handle the conversion. If the callback procedures perform the complete conversion or refuse the conversion, the convertProc method is not called. More specifically, the convertProc method is not called if, after all callback procedures have returned, the value of the status member of the XmConvertCallbackStruct is other than XmCONVERT_DEFAULT or XmCONVERT_MERGE.

typedef struct	{

       int             reason;
       XEvent          *event;
       Atom            selection;
       Atom            target;
       XtPointer       source_data;
       XtPointer       location_data;
       int             flag;
       XtPointer       parm;
       int             parm_format;
       unsigned long   parm_length;
       Atom            parm_type;
       int             status;
       XtPointer       value;
       Atom            type;
       int             format;
       unsigned long   length;
} XmConvertCallbackStruct;

The destinationProc Trait Method

void destinationProcWidget
widgetXtPointer client_dataXtPointer
call_data

The destinationProc trait method is invoked when the widget is the destination for a data transfer operation. The call_data argument is a pointer to an XmDestinationCallbackStruct structure. This method requests conversion of a selection to an appropriate target, usually by calling XmTransferValue. The method usually supplies a callback to XmTransferValue that receives and possibly inserts the converted data. The XmTransferValue callback returns an indicator of the transfer status. Either the destinationProc trait method or the XmTransferValue callback can also terminate the transfer operation by calling XmTransferDone.

The destinationProc trait method is invoked after any XmNdestinationCallback procedures are called and after all data conversions initiated by those callback procedures are complete. The callback procedures can perform the data transfer themselves, refuse the transfer, or let the destinationProc trait method handle the transfer. If the callback procedures perform the transfer themselves or refuse the transfer, the destinationProc trait method is not called. More specifically, the destinationProc trait method is not invoked if a callback procedure has called XmTransferDone with a transfer status other than XmTRANSFER_DEFAULT.

typedef struct {

       int             reason;
       XEvent          *event;
       Atom            selection;
       XtEnum          operation;
       int             flags;
       XtPointer       transfer_id;
       XtPointer       destination_data;
       XtPointer       location_data;
       Time            time;  
} XmDestinationCallbackStruct;

The destinationPreHookProc Trait Method

void destinationPreHookProcWidget
widgetXtPointer client_dataXtPointer
call_data

The destinationPreHookProc trait method is invoked when the widget is the destination for a data transfer operation. This method is called before any XmNdestinationCallback procedures are invoked. The call_data argument is a pointer to an XmDestinationCallbackStruct structure. The method can provide any information, such as a value for the location_data member of the structure, that the XmNdestinationCallback procedures or the destinationProc trait method may need.