]]> ]]> DtDndDragStart library call DtDndDragStart, DtDndVaDragStart initiate a drag #include <Dt/Dnd.h> Widget DtDndDragStart Widget dragSource XEvent *event DtDndProtocol protocol Cardinal numItems unsigned char operations XtCallbackList convertCallback XtCallbackList dragFinishCallback ArgList argList Cardinal argCount Widget DtDndVaDragStart Widget dragSource XEvent *event DtDndProtocol protocol Cardinal numItems unsigned char operations XtCallbackList convertCallback XtCallbackList dragFinishCallback ... The DtDndDragStart and DtDndVaDragStart functions initiate a Motif drag, with drag visuals appropriate to the type of data being dragged, and updates the translation table of the drag context. Either of the functions is called from the application's event handler, which interprets mouse events to determine when a drag should begin. The only difference between DtDndDragStart and DtDndVaDragStart is how the argument list is passed. The argument list is passed as an ArgList to DtDndDragStart and using varargs for DtDndVaDragStart. The dragSource argument is the widget that received the event that triggered the drag. The event argument is the button press or button motion event that triggered the drag. The protocol argument specifies the protocol used for the data transfer. 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 specifies the number of items being dragged. The operations argument indicates which operations the dragSource supports. The operations are: XmDROP_COPY Copy operations are valid. XmDROP_LINK Link operations are valid. XmDROP_MOVE Move operations are valid. A drag source can support any combination of these operations. A combination of operations is specified by the bitwise inclusive OR of several operation values. For example, to support the move and copy operations, the application can specify: XmDROP_MOVE | XmDROP_COPY The convertCallback argument is a callback function that is invoked when a drop has started and the drop site has requested data from the drag source. The convertCallback is responsible for providing the data that is transferred to the drop site. The arguments for the convertCallback are the Motif Drag Context, an XtPointer to application-supplied client data, and an XtPointer to a DtDndConvertCallbackStruct structure. ]]> The dragFinishCallback argument is a callback function that is invoked when the drag and drop transaction is complete. The dragFinishCallback is called after the convertCallback, if applicable. (The convertCallback is called only after a drop has started on an eligible drop site, whereas dragFinishCallback is called after the drag finishes, whether or not a drop occurred.) The dragFinishCallback should reset any drag motion handler and free any memory allocated by the drag source during the drag and drop transaction. dragFinishCallback are the Motif Drag Context, an XtPointer to application-supplied client data, and an XtPointer to a DtDndDragFinishCallbackStruct structure. ]]> 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. DtNsourceIcon (Widget) Specifies the XmDragIcon used to represent the data being dragged. This icon is created using either &cdeman.DtDndCreateSourceIcon; or &cdeman.XmCreateDragIcon;. If DtNsourceIcon is NULL, then a default icon is used, which is appropriate for the data begin dragged. The default value is NULL. DtNbufferIsText (Boolean) Specifies whether the dragged buffer should also be sourced as text, allowing the buffer to be dropped onto text widgets. This attribute is only valid if protocol DtDND_BUFFER_TRANSFER and is ignored for other transfers. If DtNbufferIsText is True, the buffer is sourced as text in addition to being sourced as buffers; if it is False, the buffers are sourced only as buffers. DtNdropOnRootCallback Specifies the callback to be invoked when the drop occurs on the desktop. This callback is only for use by specialized clients such as file managers. If DtNdropOnRootCallback is NULL, then drops onto the desktop background are not allowed. The default value is NULL. ]]> Once the rendezvous with the drop site has been accomplished, the application-provided callback functions are called to perform the transfer of the dragged data. First, the convertCallback is called with a reason of DtCR_DND_CONVERT_DATA. The application must set the DtDndContext fields appropriate to the transfer protocol to provide the data to be transferred to the drop site. If the drag operation is XmDROP_MOVE and the drop site requests that the move be completed, the convertCallback is called again with a reason of DtCR_DND_CONVERT_DELETE. The application should delete its version of the dragged data. Once the data transfer is complete, the dragFinishCallback is called with a reason of DtCR_DND_DRAG_FINISH. The application should free any memory allocated in the convertCallback and restore any application state. Each of the callbacks for DtDndDragStart and DtDndVaDragStart 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 convertCallback: typedef struct { int reason; XEvent *event; DtDndContext *dragData; DtDndStatus status; } DtDndConvertCallbackStruct, *DtDndConvertCallback; The reason argument indicates why the callback was invoked. The possible reasons for this callback are: DtCR_DND_CONVERT_DATA The callback provides the requested data by setting appropriate fields in the dragData structure. DtCR_DND_CONVERT_DELETE The callback completes the XmDROP_MOVE operation by deleting its copy of the dragged data. The event argument points to the XEvent that triggered the callback. The dragData argument specifies the DtDndContext that contains the data to be dragged. If the reason argument is DtCR_DND_CONVERT_DATA, the application must provide the data by setting the relevant fields in the DtDndContext, as described in the following Structures section. If the reason argument is DtCR_DND_CONVERT_DELETE, the application must delete the original data that completes a move operation. The status argument indicates the status of the conversion. The application can set this to DtDND_FAILURE to cancel the conversion and consequently the drag and drop operation. The value of status is normally DtDND_SUCCESS. A pointer to the following structure is passed to the dragFinishCallback: typedef struct { int reason; XEvent *event; DtDndContext *dragData; Widget sourceIcon; } DtDndDragFinishCallbackStruct, *DtDndDragFinishCallback; The reason argument indicates why the callback was invoked. The valid reason for this callback is DtCR_DND_DRAG_FINISH. The event argument points to the XEvent that triggered the callback. The sourceIcon argument specifies the source icon registered in the call to DtDndDragStart. This widget is provided to allow the application to free data associated with the source icon and optionally destroy the source icon. The dragData argument specifies the DtDndContext that contains the data that was dragged. The application should free any data it associated with the dragData. The following structures are used by the drag source in the convertCallback and dragFinishCallback to communicate data between the application and the drag and drop subsystem. The DtDndContext structure is passed to these callbacks as dragData in the callback structure appropriate to the callback. In the convertCallback, the application that is acting as the drag source is responsible for filling in the DtDndContext structure with the data being transferred. In the dragFinishCallback, the application acting as the drag source is responsible for freeing any data it allocated for use in the DtDndContext structure. typedef struct _DtDndContext { 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 should be stored and read 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. When it calls &cdeman.XmDragStart;, the DtDndDragStart function sets 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 XmDragStart call. The following resources are modified by DtDndDragStart and DtDndVaDragStart in the Motif Drag Context: XmNblendModel XmNclientData XmNconvertProc XmNcursorBackground XmNcursorForeground XmNdragDropFinishCallback XmNdragOperations XmNdropFinishCallback XmNdropStartCallback XmNexportTargets XmNnumExportTargets XmNsourcePixmapIcon XmNtopLevelEnterCallback The following resources are modified by DtDndDragStart and DtDndVaDragStart in the Motif Drag Icon: XmNattachment XmNdepth XmNheight XmNhotX XmNhotY XmNmask XmNoffsetX XmNoffsetY XmNpixmap XmNwidth Upon successful completion, the DtDndDragStart function returns the drag context widget created when the Motif drag is started; otherwise, it returns NULL if the drag could not be started. &cdeman.Dt.Dnd.h;, &cdeman.DtDtsFileToDataType;, &cdeman.DtDndCreateSourceIcon;, &cdeman.DtDndDropRegister;, &cdeman.DtDndDropRegister;, DtDndDropUnregister; XmCreateDragIcon, XmDragContext, XmDragIcon, XmDragStart in the &str-ZM;. ]]>