The drag initiator
The receiver's XmNdropProc routine receives the drop message first if the drop occurred over a widget that was registered as a drop site. It verifies that a drop is possible, and updates fields in its callback structure. These fields become available to the initiator in its XmNdropStartCallback callback structure. The initiator can perform any actions necessary before the information is transferred; for example, providing a new drag icon.
The toolkit initializes the operation, operations, and dropSiteStatus fields as described in Section 17.5.5, with one difference: the initialization for the drag callbacks uses the values at the end of the receiver's XmNdragProc, while the initialization for the drop callbacks uses the values at the end of the receiver's XmNdropProc.
The dropAction field indicates the action that the receiver has taken. XmDROP shows that a normal drop is in progress. XmDROP_CANCEL shows that the receiver has cancelled the drop. If the action is XmDROP_HELP, the initiator is not expected to do anything, although this callback provides the opportunity to do so if desired (for example, changing the drag icon to reflect the Help request).
This procedure will not know the resolution of the help dialog. However, if the user chooses to continue, the initiator's XmNconvertProc routine is called as part of the transfer process and, if the user chooses to cancel, the initiator's XmNdropFinishCallback is called with a dropAction of XmDROP_CANCEL.
As of Motif Release 2.0, the role of the XmNconvertProc can be done more easily through the UTM XmNconvertCallback procedures. Nevertheless, we provide the information in this subsection for those maintaining older drag and drop applications.
The drag initiator must register a callback to process transfers in the XmNconvertProc DragContext resource. This routine is called when the receiver client invokes XmDropTransferStart. Before calling XmDropTransferStart, the receiver makes a list of the target formats it wants.
The initiator's XmNconvertProc callback routine processes transfer requests from the receiver. The routine should be able to return information about each object being dragged in each possible target format for that item.
If the DropTransfer XmNincremental resource is True, information is transferred between the initiator and the toolkit using the Xt selection incremental protocol. If the value is False, the information is transferred between the initiator and the toolkit in one pass. The initiator and receiver need not be using the same incremental or nonincremental protocol.
The XmNconvertProc routine is called for each target type desired by the receiver, a single target type for each request. The XmNconvertProc routine should be able to perform any of the operations listed in the DragContext's XmNdragOperations resource on data in any of the target types listed in the XmNexportTargets resource:
A second transfer request for the data has a target type of DELETE. The receiver does not issue this request until it has received the data and handled it appropriately (such as storing it in a file). Only then should the initiator delete the data.
The XmNdropFinishCallback is called when the receiver's XmNtransferProc routine has finished processing all the transfers desired by the receiver.
The completionStatus field indicates whether the entire drop was successful or not.
The operations, operation, dropSiteStatus, and dropAction fields are initialized as for the XmNdropStartCallback procedure.
The XmdragDropFinishCallback routine is performed when the complete drag and drop transaction has finished. This routine is called immediately after the initiator's XmNdropFinishCallback has finished. The initiator frees any remaining structures it has allocated during the drag.
The following sample code from DNDDemo.c removes the icons when the drop is complete:
static void
ColorDragDropFinishCB(Widget w, XtPointer client, XtPointer call)
{
Widget sourceIcon;
Widget stateIcon = (Widget) client;
Arg args[1];
XtSetArg(args[0], XmNsourceCursorIcon, &sourceIcon);
XtGetValues(w, args, 1);
XtDestroyWidget(sourceIcon);
XtDestroyWidget(stateIcon);
}