2000-07-15 15:51:35 -04:00
|
|
|
\section{Drag and drop overview}\label{wxdndoverview}
|
1998-12-08 17:28:02 -05:00
|
|
|
|
1999-01-13 09:23:31 -05:00
|
|
|
Classes: \helpref{wxDataObject}{wxdataobject},
|
|
|
|
\helpref{wxTextDataObject}{wxtextdataobject},
|
|
|
|
\helpref{wxDropSource}{wxdropsource},
|
|
|
|
\helpref{wxDropTarget}{wxdroptarget},
|
|
|
|
\helpref{wxTextDropTarget}{wxtextdroptarget},
|
|
|
|
\helpref{wxFileDropTarget}{wxfiledroptarget}
|
1998-12-08 17:28:02 -05:00
|
|
|
|
1999-01-30 10:58:31 -05:00
|
|
|
Note that wxUSE\_DRAG\_AND\_DROP must be defined in setup.h in order
|
2000-07-15 15:51:35 -04:00
|
|
|
to use drag and drop in wxWindows.
|
1998-12-09 19:00:46 -05:00
|
|
|
|
1999-12-29 06:52:51 -05:00
|
|
|
See also: \helpref{wxDataObject overview}{wxdataobjectoverview} and \helpref{DnD sample}{samplednd}
|
1998-12-08 17:28:02 -05:00
|
|
|
|
1999-12-29 06:52:51 -05:00
|
|
|
It may be noted that data transfer to and from the clipboard is quite
|
2000-07-15 15:51:35 -04:00
|
|
|
similar to data transfer with drag and drop and the code to implement
|
1999-12-29 06:52:51 -05:00
|
|
|
these two types is almost the same. In particular, both data transfer
|
|
|
|
mechanisms store data in some kind of \helpref{wxDataObject}{wxdataobject}
|
|
|
|
and identify its format(s) using the \helpref{wxDataFormat}{wxdataformat}
|
|
|
|
class.
|
1998-12-08 17:28:02 -05:00
|
|
|
|
1998-12-09 19:00:46 -05:00
|
|
|
To be a {\it drag source}, i.e. to provide the data which may be dragged by
|
2003-02-13 13:28:36 -05:00
|
|
|
the user elsewhere, you should implement the following steps:
|
1998-12-08 18:33:12 -05:00
|
|
|
|
1998-12-08 17:28:02 -05:00
|
|
|
\begin{itemize}\itemsep=0pt
|
1999-12-29 06:52:51 -05:00
|
|
|
\item {\bf Preparation:} First of all, a data object must be created and
|
1998-12-23 04:58:02 -05:00
|
|
|
initialized with the data you wish to drag. For example:
|
1998-12-08 18:33:12 -05:00
|
|
|
|
1998-12-08 17:28:02 -05:00
|
|
|
\begin{verbatim}
|
1999-12-29 06:52:51 -05:00
|
|
|
wxTextDataObject my_data("This text will be dragged.");
|
1998-12-09 19:00:46 -05:00
|
|
|
\end{verbatim}
|
2003-02-13 13:28:36 -05:00
|
|
|
\item{\bf Drag start:} To start the dragging process (typically in response to a
|
1999-12-29 06:52:51 -05:00
|
|
|
mouse click) you must call \helpref{wxDropSource::DoDragDrop}{wxdropsourcedodragdrop}
|
|
|
|
like this:
|
1998-12-08 18:33:12 -05:00
|
|
|
|
1998-12-08 17:28:02 -05:00
|
|
|
\begin{verbatim}
|
1999-01-30 10:58:31 -05:00
|
|
|
wxDropSource dragSource( this );
|
|
|
|
dragSource.SetData( my_data );
|
2003-02-13 13:28:36 -05:00
|
|
|
wxDragResult result = dragSource.DoDragDrop( TRUE );
|
1998-12-09 19:00:46 -05:00
|
|
|
\end{verbatim}
|
2003-02-13 13:28:36 -05:00
|
|
|
\item {\bf Dragging:} The call to DoDragDrop() blocks the program until the user releases the
|
|
|
|
mouse button (unless you override the \helpref{GiveFeedback}{wxdropsourcegivefeedback} function
|
1998-12-09 19:00:46 -05:00
|
|
|
to do something special). When the mouse moves in a window of a program which understands the
|
1999-11-04 12:49:21 -05:00
|
|
|
same drag-and-drop protocol (any program under Windows or any program supporting the
|
|
|
|
XDnD protocol under X Windows), the corresponding \helpref{wxDropTarget}{wxdroptarget} methods
|
1998-12-09 19:00:46 -05:00
|
|
|
are called - see below.
|
1998-12-23 04:58:02 -05:00
|
|
|
\item {\bf Processing the result:} DoDragDrop() returns an {\it effect code} which
|
1999-12-29 06:52:51 -05:00
|
|
|
is one of the values of {\tt wxDragResult} enum (explained \helpref{here}{wxdroptarget}):
|
|
|
|
|
|
|
|
\begin{verbatim}
|
|
|
|
switch (result)
|
|
|
|
{
|
|
|
|
case wxDragCopy: /* copy the data */ break;
|
|
|
|
case wxDragMove: /* move the data */ break;
|
|
|
|
default: /* do nothing */ break;
|
|
|
|
}
|
|
|
|
\end{verbatim}
|
1998-12-09 19:00:46 -05:00
|
|
|
\end{itemize}
|
|
|
|
|
2003-02-13 13:28:36 -05:00
|
|
|
To be a {\it drop target}, i.e. to receive the data dropped by the user you should
|
1998-12-09 19:00:46 -05:00
|
|
|
follow the instructions below:
|
|
|
|
|
|
|
|
\begin{itemize}\itemsep=0pt
|
2003-02-13 13:28:36 -05:00
|
|
|
\item {\bf Initialization:} For a window to be a drop target, it needs to have
|
1998-12-09 19:00:46 -05:00
|
|
|
an associated \helpref{wxDropTarget}{wxdroptarget} object. Normally, you will
|
1998-12-28 07:35:49 -05:00
|
|
|
call \helpref{wxWindow::SetDropTarget}{wxwindowsetdroptarget} during window
|
2003-02-13 13:28:36 -05:00
|
|
|
creation associating your drop target with it. You must derive a class from
|
1998-12-09 19:00:46 -05:00
|
|
|
wxDropTarget and override its pure virtual methods. Alternatively, you may
|
|
|
|
derive from \helpref{wxTextDropTarget}{wxtextdroptarget} or
|
|
|
|
\helpref{wxFileDropTarget}{wxfiledroptarget} and override their OnDropText()
|
|
|
|
or OnDropFiles() method.
|
|
|
|
\item {\bf Drop:} When the user releases the mouse over a window, wxWindows
|
2003-02-13 13:28:36 -05:00
|
|
|
asks the associated wxDropTarget object if it accepts the data. For this,
|
1999-11-04 12:49:21 -05:00
|
|
|
a \helpref{wxDataObject}{wxdataobject} must be associated with the drop target
|
|
|
|
and this data object will be responsible for the format negotiation between
|
|
|
|
the drag source and the drop target. If all goes well, then \helpref{OnData}{wxdroptargetondata}
|
|
|
|
will get called and the wxDataObject belonging to the drop target can get
|
|
|
|
filled with data.
|
1998-12-09 19:00:46 -05:00
|
|
|
\item {\bf The end:} After processing the data, DoDragDrop() returns either
|
2003-02-13 13:28:36 -05:00
|
|
|
wxDragCopy or wxDragMove depending on the state of the keys <Ctrl>, <Shift>
|
|
|
|
and <Alt> at the moment of the drop. There is currently no way for the drop
|
1998-12-09 19:00:46 -05:00
|
|
|
target to change this return code.
|
1998-12-08 17:28:02 -05:00
|
|
|
\end{itemize}
|
|
|
|
|