| 1 | ///////////////////////////////////////////////////////////////////////////// |
| 2 | // Name: dnd.h |
| 3 | // Purpose: topic overview |
| 4 | // Author: wxWidgets team |
| 5 | // RCS-ID: $Id$ |
| 6 | // Licence: wxWindows license |
| 7 | ///////////////////////////////////////////////////////////////////////////// |
| 8 | |
| 9 | /** |
| 10 | |
| 11 | @page overview_dnd Drag and Drop Overview |
| 12 | |
| 13 | Classes: wxDataObject, wxTextDataObject, wxDropSource, wxDropTarget, |
| 14 | wxTextDropTarget, wxFileDropTarget |
| 15 | |
| 16 | Note that @c wxUSE_DRAG_AND_DROP must be defined in @c setup.h in order |
| 17 | to use drag and drop in wxWidgets. |
| 18 | |
| 19 | See also: @ref overview_dataobject and @ref page_samples_dnd. |
| 20 | |
| 21 | It may be noted that data transfer to and from the clipboard is quite |
| 22 | similar to data transfer with drag and drop and the code to implement |
| 23 | these two types is almost the same. In particular, both data transfer |
| 24 | mechanisms store data in some kind of wxDataObject and identify its format(s) |
| 25 | using the wxDataFormat class. |
| 26 | |
| 27 | To be a @e drag source, i.e. to provide the data which may be dragged by |
| 28 | the user elsewhere, you should implement the following steps: |
| 29 | |
| 30 | @li @b Preparation: First of all, a data object must be created and |
| 31 | initialized with the data you wish to drag. For example: |
| 32 | |
| 33 | @code |
| 34 | wxTextDataObject my_data("This text will be dragged."); |
| 35 | @endcode |
| 36 | |
| 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: |
| 39 | |
| 40 | @code |
| 41 | wxDropSource dragSource( this ); |
| 42 | dragSource.SetData( my_data ); |
| 43 | wxDragResult result = dragSource.DoDragDrop( true ); |
| 44 | @endcode |
| 45 | |
| 46 | @li @b Dragging: The call to DoDragDrop() blocks the program until the user releases |
| 47 | the mouse button (unless you override the wxDropSource::GiveFeedback function to |
| 48 | do something special). When the mouse moves in a window of a program which understands |
| 49 | the same drag-and-drop protocol (any program under Windows or any program supporting |
| 50 | the XDnD protocol under X Windows), the corresponding wxDropTarget methods |
| 51 | are called - see below. |
| 52 | |
| 53 | @li <b>Processing the result</b>: DoDragDrop() returns an @e effect code which |
| 54 | is one of the values of @c wxDragResult enum (explained in wxDropTarget page): |
| 55 | |
| 56 | @code |
| 57 | switch (result) |
| 58 | { |
| 59 | case wxDragCopy: |
| 60 | // copy the data |
| 61 | break; |
| 62 | case wxDragMove: |
| 63 | // move the data |
| 64 | break; |
| 65 | default: |
| 66 | // do nothing |
| 67 | break; |
| 68 | } |
| 69 | @endcode |
| 70 | |
| 71 | |
| 72 | To be a @e drop target, i.e. to receive the data dropped by the user you should |
| 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. |
| 81 | |
| 82 | @li @b Drop: When the user releases the mouse over a window, wxWidgets |
| 83 | asks the associated wxDropTarget object if it accepts the data. For this, |
| 84 | a wxDataObject must be associated with the drop target and this data object will |
| 85 | be responsible for the format negotiation between the drag source and the drop target. |
| 86 | If all goes well, then wxDropTarget::OnData will get called and the wxDataObject belonging |
| 87 | to the drop target can get filled with data. |
| 88 | |
| 89 | @li <b>The end</b>: After processing the data, DoDragDrop() returns either |
| 90 | wxDragCopy or wxDragMove depending on the state of the keys Ctrl, Shift |
| 91 | and Alt at the moment of the drop. There is currently no way for the drop |
| 92 | target to change this return code. |
| 93 | |
| 94 | */ |
| 95 | |