Партнёры:
Хостинг:
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 ini-
tiate 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 inter-
prets mouse events to determine when a drag should begin.
The only difference between DtDndDragStart() and DtDndVa-
DragStart() is how the argument list is passed. The argu-
ment 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 drag-
Source 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 opera-
tions. A combination of operations is specified by the bit-
wise 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 DtDndConvertCallback-
Struct 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 dragFin-
ishCallback 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 argu-
ments 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 sup-
port 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(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
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 accom-
plished, 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 appli-
cation should free any memory allocated in the convertCall-
back and restore any application state.
Callback Information
Each of the callbacks for DtDndDragStart() and DtDndVaDrag-
Start() has an associated callback structure. These
callbacks cannot be used with the XtAddCallback(3X) inter-
face.
A pointer to the following structure is passed to the con-
vertCallback:
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 con-
tains 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 rea-
son argument is DtCR_DND_CONVERT_DELETE, the application
must delete the original data that completes a move opera-
tion.
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 drag-
FinishCallback:
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 con-
tains 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 call-
back.
In the convertCallback, the application that is acting as
the drag source is responsible for filling in the DtDndCon-
text 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), DtDndDropUnre-
gister(3), XmCreateDragIcon(3X), XmDragContext(3X),
XmDragIcon(3X), XmDragStart(3X).
|
Закладки на сайте Проследить за страницей |
Created 1996-2024 by Maxim Chirkov Добавить, Поддержать, Вебмастеру |