Argument Value Pairs

The DtDndDragStart and DtDndVaDragStart functions support the following optional argument-value pairs. Motif resources can be set via the argument list as well, provided they are not resources that are used by the drag and drop subsystem; see Motif Resources.

DtNregisterChildren (Boolean)

Specifies whether children of a composite drop site widget should be registered. If True, then the composite dropSite widget and its children are registered as a single drop site. If False, then only the dropSite widget itself is registered as the drop site. The default is False.

DtNtextIsBuffer (Boolean)

Specifies whether the drops of text selections should be treated as buffer drops. This attribute is only valid if protocols includes DtDND_BUFFER_TRANSFER. If DtNtextIsBuffer is True, text drops are accepted as unnamed buffers; if it is False, only drops of the specified protocols are accepted. The default is False.

DtNpreserveRegistration (Boolean)

Specifies whether to preserve any existing drop site registration for the dropSite widget. The application can disable preserving the drop site registration if the dropSite widget is known not to be registered as a drop site or that registration is not desired. This may improve drop site registration performance. If DtNpreserveRegistration is True, existing drop site registration is preserved; if it is False, the existing drop site registration is replaced. The default is True.

DtNdropAnimateCallback (XtCallbackList)

Specifies the callback to be called when the drop is complete. This enables graphical animation upon successful completion of a drop. This callback is called after the transferCallback is called and after Motif performs the "melt" effect. The arguments for the DtNDropAnimateCallback are the Motif Drag Context, an XtPointer to application-supplied client data, and an XtPointer to a DtDndDropAnimateCallbackStruct structure. The Motif Drag Context is in the process of being destroyed at this point so the application must not use it or any of its values in the dropAnimateCallback. The default is NULL.

Callbacks

Once the rendezvous with the drag source has been accomplished, the application-provided callback functions are called to perform the data transfer.

First, the transferCallback is called with a reason of DtCR_DND_TRANSFER_DATA. The application should access the DtDndContext fields appropriate for the transfer protocol. The application should parse or type the dropped data to determine whether it is acceptable. If the dropped data is not acceptable, the status field of the DtDndTransferCallbackStruct should be set to DtDND_FAILURE.

If the DtNdropAnimateCallback attribute has been specified, the dropAnimateCallback is then called with a reason of DtCR_DND_DROP_ANIMATE. The application should perform any application-provided animations for the drop.

When the transferCallback (or the dropAnimateCallback, if specified) returns, all memory associated with the drop transfer is freed. Any data in the callback structures that will be used after the drop transfer is complete must be copied by the application.

Callback Information

Each of the callbacks for DtDndDropRegister and DtDndVaDropRegister has an associated callback structure. These callbacks cannot be used with the XtAddCallback(3) interface.

A pointer to the following structure is passed to the transferCallback:

typedef struct {
			int 		reason;
			XEvent 		*event;
			Position	     x, y;
			unsigned char 	operation;
			DtDndContext 	*dropData;
			Widget		dragContext;
			Boolean 	completeMove;
			DtDndStatus 	status;
} DtDndTransferCallbackStruct, *DtDndTransferCallback;

The reason argument indicates why the callback was invoked: DtCR_DND_TRANSFER_DATA.

The event argument is always set to NULL by Motif drag and drop.

The x and y arguments indicate the coordinates of the dropped item in relation to the origin of the drop site widget.

The operation argument indicates the type of drop: XmDROP_COPY, XmDROP_MOVE or XmDROP_LINK.

The dropData argument contains the data that has been dropped.

The dragContext argument specifies the ID of the Motif Drag Context widget associated with this drag and drop transaction.

The completeMove argument indicates whether a move operation needs to be completed. If the operation is XmDROP_MOVE and completeMove is set to False in the transferCallback, a delete does not occur. By default, completeMove is True and a delete occurs to complete the move operation. The completeMove field should be set to False if an alternative method will be used to complete the move.

The status argument indicates the success or failure of the data transfer. If the data could not be appropriately moved, copied or linked, the status field must be set to DtDND_FAILURE. By default, the status field is set to DtDND_SUCCESS.

A pointer to the following structure is passed to the dropAnimateCallback:

typedef struct {


        int reason;


        XEvent *event;


        Position x, y;


        unsigned char operation;


        DtDndContext *dropData;
} DtDndDropAnimateCallbackStruct, *DtDndDropAnimateCallback;

The reason argument indicates why the callback was invoked. The valid reason is DtCR_DND_DROP_ANIMATE.

The event argument is always set to NULL by Motif drag and drop.

The x and y arguments indicate the coordinates of the dropped item in relation to the origin of the drop site widget.

The operation argument indicates the type of drop: XmDROP_COPY, XmDROP_MOVE or XmDROP_LINK.

The dropData argument contains the data that has been dropped.

Structures

The following structures are used by the drop site in the transferCallback to get the transferred data from the drag and drop subsystem. The DtDndContext structure is passed as dropData in the DtDndTransferCallbackStruct structure.

typedef struct {


        DtDndProtocol protocol;


        int numItems;


        union {


                XmString *strings;


                String *files;


                DtDndBuffer *buffers;


        } data;
} DtDndContext;

The protocol argument indicates the data transfer protocol under which the data in the DtDndContext is being transferred. Valid values are:

DtDND_TEXT_TRANSFER

A list of text is being transferred.

DtDND_FILENAME_TRANSFER

A list of file names is being transferred.

DtDND_BUFFER_TRANSFER

A list of memory buffers is being transferred.

The numItems argument indicates the number of items being transferred.

The data argument is a union containing data that the drop site should access in the format corresponding to the specified protocol. The data structures corresponding to the transfer protocols are as follows.

The strings argument is valid if the protocol is DtDND_TEXT_TRANSFER. The strings argument is an array of pointers to Motif strings containing the text being transferred.

The files argument is valid if the protocol is DtDND_FILENAME_TRANSFER. It is an array of pointers to the names of the files being transferred. The file names have been converted to local host file names where possible.

The buffers argument is valid if the protocol is DtDND_BUFFER_TRANSFER. It is an array of pointers to DtDndBuffer structures containing the meory buffers being transferred.

The following structure is used with DtDND_FILENAME_TRANSFER:

typedef struct _DtDndBuffer {


        void *bp;


        int size;


        string name;
} DtDndBuffer;

The bp argument points to the buffer data being transferred.

The size argument indicates the number of bytes in the buffer.

The name argument points to the name of the buffer.

Motif Resources

When it calls XmDropSiteRegister(3), the DtDndDropRegister and DtDndVaDropRegister functions set Motif resources; the application must not modify the values of any of these resources. Resources other than those listed here can be used and are passed through to the underlying XmDropRegister. call.

The following resources are modified by DtDndDropRegister and DtDndVaDropRegister in the Motif Drag Context.

•

XmNdestroyCallback

•

XmNdropTransfers

•

XmNnumDropTransfers

•

XmNtransferProc

•

XmNtransferStatus

The following resources are modified by DtDndDropRegister and DtDndVaDropRegister in the Motif Drop Site.

•

XmNdropProc

•

XmNdropSiteOperations

•

XmNdropSiteType

•

XmNimportTargets

•

XmNnumImportTargets