]> git.saurik.com Git - wxWidgets.git/blame_incremental - docs/latex/wx/tdnd.tex
Fixed to work with the new wxMacControl system.
[wxWidgets.git] / docs / latex / wx / tdnd.tex
... / ...
CommitLineData
1\section{Drag and drop overview}\label{wxdndoverview}
2
3Classes: \helpref{wxDataObject}{wxdataobject},
4\helpref{wxTextDataObject}{wxtextdataobject},
5\helpref{wxDropSource}{wxdropsource},
6\helpref{wxDropTarget}{wxdroptarget},
7\helpref{wxTextDropTarget}{wxtextdroptarget},
8\helpref{wxFileDropTarget}{wxfiledroptarget}
9
10Note that wxUSE\_DRAG\_AND\_DROP must be defined in setup.h in order
11to use drag and drop in wxWidgets.
12
13See also: \helpref{wxDataObject overview}{wxdataobjectoverview} and \helpref{DnD sample}{samplednd}
14
15It may be noted that data transfer to and from the clipboard is quite
16similar to data transfer with drag and drop and the code to implement
17these two types is almost the same. In particular, both data transfer
18mechanisms store data in some kind of \helpref{wxDataObject}{wxdataobject}
19and identify its format(s) using the \helpref{wxDataFormat}{wxdataformat}
20class.
21
22To be a {\it drag source}, i.e. to provide the data which may be dragged by
23the user elsewhere, you should implement the following steps:
24
25\begin{itemize}\itemsep=0pt
26\item {\bf Preparation:} First of all, a data object must be created and
27initialized with the data you wish to drag. For example:
28
29\begin{verbatim}
30 wxTextDataObject my_data("This text will be dragged.");
31\end{verbatim}
32\item{\bf Drag start:} To start the dragging process (typically in response to a
33mouse click) you must call \helpref{wxDropSource::DoDragDrop}{wxdropsourcedodragdrop}
34like this:
35
36\begin{verbatim}
37 wxDropSource dragSource( this );
38 dragSource.SetData( my_data );
39 wxDragResult result = dragSource.DoDragDrop( TRUE );
40\end{verbatim}
41\item {\bf Dragging:} The call to DoDragDrop() blocks the program until the user releases the
42mouse button (unless you override the \helpref{GiveFeedback}{wxdropsourcegivefeedback} function
43to do something special). When the mouse moves in a window of a program which understands the
44same drag-and-drop protocol (any program under Windows or any program supporting the
45XDnD protocol under X Windows), the corresponding \helpref{wxDropTarget}{wxdroptarget} methods
46are called - see below.
47\item {\bf Processing the result:} DoDragDrop() returns an {\it effect code} which
48is one of the values of {\tt wxDragResult} enum (explained \helpref{here}{wxdroptarget}):
49
50\begin{verbatim}
51 switch (result)
52 {
53 case wxDragCopy: /* copy the data */ break;
54 case wxDragMove: /* move the data */ break;
55 default: /* do nothing */ break;
56 }
57\end{verbatim}%
58\end{itemize}
59
60To be a {\it drop target}, i.e. to receive the data dropped by the user you should
61follow the instructions below:
62
63\begin{itemize}\itemsep=0pt
64\item {\bf Initialization:} For a window to be a drop target, it needs to have
65an associated \helpref{wxDropTarget}{wxdroptarget} object. Normally, you will
66call \helpref{wxWindow::SetDropTarget}{wxwindowsetdroptarget} during window
67creation associating your drop target with it. You must derive a class from
68wxDropTarget and override its pure virtual methods. Alternatively, you may
69derive from \helpref{wxTextDropTarget}{wxtextdroptarget} or
70\helpref{wxFileDropTarget}{wxfiledroptarget} and override their OnDropText()
71or OnDropFiles() method.
72\item {\bf Drop:} When the user releases the mouse over a window, wxWidgets
73asks the associated wxDropTarget object if it accepts the data. For this,
74a \helpref{wxDataObject}{wxdataobject} must be associated with the drop target
75and this data object will be responsible for the format negotiation between
76the drag source and the drop target. If all goes well, then \helpref{OnData}{wxdroptargetondata}
77will get called and the wxDataObject belonging to the drop target can get
78filled with data.
79\item {\bf The end:} After processing the data, DoDragDrop() returns either
80wxDragCopy or wxDragMove depending on the state of the keys <Ctrl>, <Shift>
81and <Alt> at the moment of the drop. There is currently no way for the drop
82target to change this return code.
83\end{itemize}
84