]>
Commit | Line | Data |
---|---|---|
15b6757b | 1 | ///////////////////////////////////////////////////////////////////////////// |
d54cf7ff | 2 | // Name: dnd.h |
15b6757b FM |
3 | // Purpose: topic overview |
4 | // Author: wxWidgets team | |
526954c5 | 5 | // Licence: wxWindows licence |
15b6757b FM |
6 | ///////////////////////////////////////////////////////////////////////////// |
7 | ||
880efa2a | 8 | /** |
36c9828f | 9 | |
dc28cdf8 | 10 | @page overview_dnd Drag and Drop Overview |
36c9828f | 11 | |
ce154616 | 12 | @tableofcontents |
d54cf7ff | 13 | |
dc28cdf8 FM |
14 | It may be noted that data transfer to and from the clipboard is quite |
15 | similar to data transfer with drag and drop and the code to implement | |
16 | these two types is almost the same. In particular, both data transfer | |
17 | mechanisms store data in some kind of wxDataObject and identify its format(s) | |
18 | using the wxDataFormat class. | |
d54cf7ff | 19 | |
ce154616 BP |
20 | Note that @c wxUSE_DRAG_AND_DROP must be defined in @c setup.h in order |
21 | to use drag and drop in wxWidgets. | |
22 | ||
23 | @see @ref overview_dataobject, @ref group_class_dnd, @ref page_samples_dnd | |
24 | ||
25 | ||
26 | ||
27 | @section overview_dnd_dropsource Drop Source Requirements | |
28 | ||
29 | To be a @e "drop source", i.e. to provide the data which may be dragged by | |
dc28cdf8 | 30 | the user elsewhere, you should implement the following steps: |
36c9828f | 31 | |
dc28cdf8 FM |
32 | @li @b Preparation: First of all, a data object must be created and |
33 | initialized with the data you wish to drag. For example: | |
dc28cdf8 FM |
34 | @code |
35 | wxTextDataObject my_data("This text will be dragged."); | |
36 | @endcode | |
dc28cdf8 FM |
37 | @li <b>Drag start</b>: To start the dragging process (typically in response to a |
38 | mouse click) you must call wxDropSource::DoDragDrop like this: | |
dc28cdf8 FM |
39 | @code |
40 | wxDropSource dragSource( this ); | |
41 | dragSource.SetData( my_data ); | |
42 | wxDragResult result = dragSource.DoDragDrop( true ); | |
43 | @endcode | |
ce154616 BP |
44 | @li @b Dragging: The call to DoDragDrop() blocks the program until the user |
45 | releases the mouse button (unless you override the | |
46 | wxDropSource::GiveFeedback function to do something special). When the | |
47 | mouse moves in a window of a program which understands the same | |
48 | drag-and-drop protocol (any program under Windows or any program supporting | |
dc28cdf8 FM |
49 | the XDnD protocol under X Windows), the corresponding wxDropTarget methods |
50 | are called - see below. | |
dc28cdf8 FM |
51 | @li <b>Processing the result</b>: DoDragDrop() returns an @e effect code which |
52 | is one of the values of @c wxDragResult enum (explained in wxDropTarget page): | |
dc28cdf8 FM |
53 | @code |
54 | switch (result) | |
55 | { | |
3c4f71cc | 56 | case wxDragCopy: |
d54cf7ff FM |
57 | // copy the data |
58 | break; | |
59 | case wxDragMove: | |
60 | // move the data | |
61 | break; | |
62 | default: | |
63 | // do nothing | |
64 | break; | |
dc28cdf8 FM |
65 | } |
66 | @endcode | |
67 | ||
68 | ||
ce154616 BP |
69 | |
70 | @section overview_dnd_droptarget Drop Target Requirements | |
71 | ||
72 | To be a @e "drop target", i.e. to receive the data dropped by the user you should | |
dc28cdf8 FM |
73 | follow the instructions below: |
74 | ||
75 | @li @b Initialization: For a window to be a drop target, it needs to have | |
76 | an associated wxDropTarget object. Normally, you will call wxWindow::SetDropTarget | |
77 | during window creation associating your drop target with it. You must derive a class | |
78 | from wxDropTarget and override its pure virtual methods. Alternatively, you may | |
79 | derive from wxTextDropTarget or wxFileDropTarget and override their OnDropText() | |
80 | or OnDropFiles() method. | |
dc28cdf8 FM |
81 | @li @b Drop: When the user releases the mouse over a window, wxWidgets |
82 | asks the associated wxDropTarget object if it accepts the data. For this, | |
83 | a wxDataObject must be associated with the drop target and this data object will | |
84 | be responsible for the format negotiation between the drag source and the drop target. | |
85 | If all goes well, then wxDropTarget::OnData will get called and the wxDataObject belonging | |
86 | to the drop target can get filled with data. | |
dc28cdf8 FM |
87 | @li <b>The end</b>: After processing the data, DoDragDrop() returns either |
88 | wxDragCopy or wxDragMove depending on the state of the keys Ctrl, Shift | |
89 | and Alt at the moment of the drop. There is currently no way for the drop | |
90 | target to change this return code. | |
d54cf7ff FM |
91 | |
92 | */ |