DtDndDragStart(library call) DtDndDragStart(library call)
NAME
DtDndDragStart, DtDndVaDragStart -- initiate a drag
SYNOPSIS
#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,
...);
DESCRIPTION
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 con-
vertCallback 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 dragFinishCall-
back 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. The arguments for the
dragFinishCallback are the Motif Drag Context, an XtPointer to application-supplied client data, and an XtPointer to a DtDndDragFinishCall-
backStruct structure.
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.
DtNsourceIcon (Widget)
Specifies the XmDragIcon used to represent the data being dragged. This icon is created using either DtDndCreateSourceIcon(3) or
XmCreateDragIcon(3). 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.
Callbacks
Once the rendezvous with the drop site has been accomplished, the application-provided callback functions are called to perform the trans-
fer 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 rea-
son 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.
Callback Information
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 applica-
tion 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 associ-
ated with the dragData.
Structures
The following structures are used by the drag source in the convertCallback and dragFinishCallback to communicate data between the applica-
tion and the drag and drop subsystem. The DtDndContext structure is passed to these callbacks as dragData in the callback structure appro-
priate 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 DtDnd-
Context 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 con-
taining 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 trans-
ferred. 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 XmDragStart(3), 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:
o XmNblendModel
o XmNclientData
o XmNconvertProc
o XmNcursorBackground
o XmNcursorForeground
o XmNdragDropFinishCallback
o XmNdragOperations
o XmNdropFinishCallback
o XmNdropStartCallback
o XmNexportTargets
o XmNnumExportTargets
o XmNsourcePixmapIcon
o XmNtopLevelEnterCallback
The following resources are modified by DtDndDragStart and DtDndVaDragStart in the Motif Drag Icon:
o XmNattachment
o XmNdepth
o XmNheight
o XmNhotX
o XmNhotY
o XmNmask
o XmNoffsetX
o XmNoffsetY
o XmNpixmap
o XmNwidth
RETURN VALUE
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.
SEE ALSO
Dt/Dnd.h - DtDnd(5), DtDtsFileToDataType(3), DtDndCreateSourceIcon(3), DtDndDropRegister(3), DtDndDropRegister(3), DtDndDropUnregister(3),
XmCreateDragIcon(3), XmDragContext(3), XmDragIcon(3), XmDragStart(3).
DtDndDragStart(library call)