XmQTtransfer — A trait that implements data transfer to and from a widget
#include <Xm/TransferT.h>
typedef struct {
int version;
XmConvertCallbackProc convertProc;
XmDestinationCallbackProc destinationProc;
XmDestinationCallbackProc destinationPreHookProc;
} XmTransferTraitRec, *XmTransferTrait;
void (*XmConvertCallbackProc)(, , , void (*XmDestinationCallbackProc), , );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.)
void convertProc(widget, client_data, 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.
| widget | Specifies the widget that is asked to convert the data. | |
| client_data | This argument is currently unused. The value is always NULL. | |
| call_data | Specifies a pointer to an XmConvertCallbackStruct structure. |
Following is a description of the XmConvertCallbackStruct structure:
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;
|
| reason | Indicates why the callback was invoked. | |||||||||||||
| event | Points to the XEvent that triggered the callback. It can be NULL. | |||||||||||||
| selection | Indicates the selection for which conversion is being requested. Possible values are CLIPBOARD, PRIMARY, SECONDARY, and _MOTIF_DROP. | |||||||||||||
| target | Indicates the conversion target. | |||||||||||||
| source_data | Contains information about the selection source. When the selection is _MOTIF_DROP, source_data is the DragContext. Otherwise, it is NULL. | |||||||||||||
| location_data | Contains information about the location of data to be converted. If the value is NULL, the data to be transferred consists of the widget's current selection. Otherwise, the type and interpretation of the value are specific to the widget class. | |||||||||||||
| flag | This member is currently unused. | |||||||||||||
| parm | Contains parameter data for this target. If no parameter data exists, the value is NULL. When selection is CLIPBOARD and target is _MOTIF_CLIPBOARD_TARGETS or _MOTIF_DEFERRED_CLIPBOARD_TARGETS, the value is the requested operation (XmCOPY, XmMOVE, or XmLINK). | |||||||||||||
| parm_format | Specifies whether the data in parm should be viewed as a list of 8-bit, 16-bit, or 32-bit quantities. Possible values are 0 (when parm is NULL), 8, 16, and 32. | |||||||||||||
| parm_length | Specifies the number of elements of data in parm, where each element has the number of bits specified by parm_format. When parm is NULL, the value is 0. | |||||||||||||
| parm_type | Specifies the parameter type of parm. | |||||||||||||
| status | An IN/OUT member that specifies the status of the conversion. The initial value set by the toolkit is XmCONVERT_DEFAULT, but an XmNconvertCallback procedure may have set a different value. Following are the possible values:
Before returning, the convertProc trait method should always set status to either XmCONVERT_DONE, indicating a successful conversion, or XmCONVERT_REFUSE, indicating an unsuccessful conversion. | |||||||||||||
| value | An IN/OUT parameter that contains any data that the callback procedures or the convertProc trait method produces as a result of the conversion. The initial value is NULL. If the convertProc trait method sets this member, it must ensure that the type, format, and length members correspond to the data in value. The convertProc trait method is responsible for allocating memory when it sets this member. The toolkit frees this memory when it is no longer needed. | |||||||||||||
| type | An IN/OUT parameter that indicates the type of the data in the value member. The initial value is INTEGER. | |||||||||||||
| format | An IN/OUT parameter that specifies whether the data in value should be viewed as a list of 8-bit, 16-bit, or 32-bit quantities. The initial value is 8. The convertProc trait method can set this member to 8, 16, or 32. | |||||||||||||
| length | An IN/OUT member that specifies the number of elements of data in value, where each element has the number of bits specified by format. The initial value is 0. |
void destinationProc(widget, client_data, 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.
| widget | Specifies the widget that is the destination for the transfer. | |
| client_data | This argument is currently unused. The value is always NULL. | |
| call_data | Specifies a pointer to an XmDestinationCallbackStruct structure. |
Following is a description of the XmDestinationCallbackStruct structure:
typedef struct {
int reason;
XEvent *event;
Atom selection;
XtEnum operation;
int flags;
XtPointer transfer_id;
XtPointer destination_data;
XtPointer location_data;
Time time;
} XmDestinationCallbackStruct;
|
| reason | Indicates why the callback was invoked. | |||||||
| event | Points to the XEvent that triggered the callback. It can be NULL. | |||||||
| selection | Indicates the selection for which data transfer is being requested. Possible values are CLIPBOARD, PRIMARY, SECONDARY, and _MOTIF_DROP. | |||||||
| operation | Indicates the type of transfer operation requested.
| |||||||
| flags | Indicates whether or not the destination widget is also the source of the data to be transferred. Following are the possible values:
| |||||||
| transfer_id | Serves as a unique ID to identify the transfer transaction. | |||||||
| destination_data | Contains information about the destination. When the selection is _MOTIF_DROP, the destinationProc trait method is called by the drop site's XmNdropProc, and destination_data is a pointer to the XmDropProcCallbackStruct passed to the XmNdropProc procedure. When the selection is SECONDARY, destination_data is an Atom representing a target recommmended by the selection owner for use in converting the selection. Otherwise, destination_data is NULL. | |||||||
| location_data | Contains information about the location where data is to be transferred. The value is always NULL when the selection is SECONDARY or CLIPBOARD. 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. 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 | Indicates the time when the transfer operation began. |
void destinationPreHookProc(widget, client_data, 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.
| widget | Specifies the widget that is the destination for the transfer. | |
| client_data | This argument is currently unused. The value is always NULL. | |
| call_data | Specifies a pointer to an XmDestinationCallbackStruct structure. |
ExmStringTransfer(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), XmeSecondaryTransfer(3), XmeStandardConvert(3), XmeStandardTargets(3), and XmeTransferAddDoneProc(3).