DtDndDragStart(library call) DtDndDragStart(library call)
NAME [Toc] [Back]
DtDndDragStart, DtDndVaDragStart - initiate a drag
SYNOPSIS [Toc] [Back]
#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 [Toc] [Back]
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.
- 1 - Formatted: January 24, 2005
DtDndDragStart(library call) DtDndDragStart(library call)
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. The arguments
for the dragFinishCallback are the Motif Drag Context, an XtPointer to
application-supplied client data, and an XtPointer to a
DtDndDragFinishCallbackStruct structure.
Argument Value Pairs [Toc] [Back]
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.
- 2 - Formatted: January 24, 2005
DtDndDragStart(library call) DtDndDragStart(library call)
DtNsourceIcon (Widget)
Specifies the XmDragIcon used to represent the data being
dragged. This icon is created using either
DtDndCreateSourceIconDtNsourceIcon 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 [Toc] [Back]
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 [Toc] [Back]
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.
Callback Information [Toc] [Back]
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:
- 3 - Formatted: January 24, 2005
DtDndDragStart(library call) DtDndDragStart(library call)
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.
- 4 - Formatted: January 24, 2005
DtDndDragStart(library call) DtDndDragStart(library call)
The dragData argument specifies the DtDndContext that contains the
data that was dragged. The application should free any data it
associated with the dragData.
Structures [Toc] [Back]
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.
- 5 - Formatted: January 24, 2005
DtDndDragStart(library call) DtDndDragStart(library call)
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 [Toc] [Back]
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:
+ XmNblendModel
+ XmNclientData
+ XmNconvertProc
+ XmNcursorBackground
+ XmNcursorForeground
+ XmNdragDropFinishCallback
+ XmNdragOperations
+ XmNdropFinishCallback
+ XmNdropStartCallback
- 6 - Formatted: January 24, 2005
DtDndDragStart(library call) DtDndDragStart(library call)
+ 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
RETURN VALUE [Toc] [Back]
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 [Toc] [Back]
Dt/Dnd.h - DtDnd(5), DtDtsFileToDataType(3), DtDndCreateSourceIcon(3),
DtDndDropRegister(3), DtDndDropRegister(3), DtDndDropUnregister(3),
XmCreateDragIcon(3), XmDragContext(3), XmDragIcon(3), XmDragStart(3).
- 7 - Formatted: January 24, 2005 [ Back ] |
