 |
Index for
Section 3 |
|
 |
Alphabetical
listing for D |
|
 |
Bottom of
page |
|
DtDndDragStart(3)
CDE
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 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
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 "MotifResources"
DtNsourceIcon (Widget)
Specifies the XmDragIcon used to represent the data being dragged. This
icon is created using either DtDndCreateSourceIcon(3) or
XmCreateDragIcon(3X). 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 (XtCallbackList)
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 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
Each of the callbacks for DtDndDragStart and DtDndVaDragStart has an
associated callback structure. These callbacks cannot be used with the
XtAddCallback(3X) 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.
Structures
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.
Motif Resources
When it calls XmDragStart(3X), 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
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
DtDnd(5), DtDtsFileToDataType(3), DtDndCreateSourceIcon(3),
DtDndDropRegister(3), DtDndVaDropRegister(3), DtDndDropUnregister(3),
XmCreateDragIcon(3X), XmDragContext(3X), XmDragIcon(3X), XmDragStart(3X).
DtDndDropUnregister; XmCreateDragIcon, XmDragContext, XmDragIcon,
XmDragStart in the X/Open CAE Specification, X/Open Motif Toolkit API
|
Index for
Section 3 |
|
|
Alphabetical
listing for D |
|
 |
Top of
page |
|