Commit | Line | Data |
---|---|---|
457814b5 JS |
1 | Drag-and-Drop Support in wxWindows |
2 | ================================== | |
3 | ||
4 | 1. Overview | |
5 | -------- | |
6 | ||
7 | a) What is it? | |
8 | ||
9 | We're calling drag-and-drop (or d&d for short) the OLE mechanism of data | |
10 | transfer. Please note that it's not the same thing as the file oriented d&d | |
11 | of Windows 3.1 "File Manager" which is designed for and limited to the file | |
12 | names only. | |
13 | ||
14 | OLE d&d allows application to transfer data of any type to the same or | |
15 | another process. | |
16 | ||
17 | ||
18 | b) How is it done? (user's point of view) | |
19 | ||
20 | To start a d&d operation the user presses the mouse button 1 (left) and | |
21 | drags the selected object to another window (which must be at least partially | |
22 | visible on the screen) or to an icon on the taskbar in which case the | |
23 | corresponding window will be automatically restored. To finish the operation, | |
24 | the user releases the button. Default d&d operation is "move", but several key | |
25 | act as modifiers: keeping down the <Ctrl> key at the moment of drop does | |
26 | "copy", while <Shift> or <Alt> force the "move" (makes sense if default isn't | |
27 | "move"). | |
28 | ||
29 | ||
30 | c) How is it done? (programmer's point of view) | |
31 | ||
32 | There are several objects participating in a d&d operation. First of all, | |
33 | there is the data object itself. Second, there is the drop source which is | |
34 | responsible for creating the data object (if it doesn't exist yet) and starting | |
4c51a665 | 35 | the d&d operation. Finally, the drop target receives the notification when |
457814b5 JS |
36 | the data is dropped onto the associated window (see below) and is responsible |
37 | for pasting the data and returning the result code (copy, move or failure). | |
38 | There is one class for each one of these roles in wxWindows d&d implementation, | |
39 | plese see their descriptions below for details. | |
40 | ||
41 | ||
42 | ||
43 | 2. Drop Target | |
44 | ----------- | |
45 | ||
46 | a) Being a drop target | |
47 | ||
48 | ... is as easy as deriving your window class from wxDropTarget and | |
49 | associating it with a wxWindow object (or perhaps some wxWindow-derived class, | |
50 | such as wxFrame). The pure virtual function wxDropTarget::OnDrop() must be | |
51 | implemented in your application and will be called whenever the mouse button | |
52 | is released over the window in question. Other virtual functions that will be | |
53 | called in the process of the d&d operation are OnEnter and OnLeave. | |
54 | ||
55 | @@ should OnDragOver() be user overridable also? | |
56 | ||
57 | You should associate wxDropTarget and wxWindow calling SetDropTarget: | |
58 | wxWindow *pWindow = GetTopWindow(); | |
59 | pWindow->SetDropTarget(new MyDropTarget); | |
60 | ||
61 | The object created passed to SetDropTarget becomes the propriety of wxWindow | |
62 | and will be deleted with the window (or when you call SetDropTarget next | |
63 | time). You can always break the association by calling SetDropTarget(NULL). | |
64 | ||
65 | When some data is dragged over a window, the program must decide if it's | |
66 | going to accept this data or not. The virtual function IsAcceptedData() is | |
67 | called to do it. The default implementation takes care of OLE interface | |
68 | pointer manipulations and only requires you to override GetCountFormats() | |
69 | and GetFormat(n) functions to let it know what data formats you support. | |
70 | If it's not flexible enough for your application (i.e. the set of supported | |
71 | formats changes over time...), you should override IsAcceptedData(). In 99% | |
72 | of cases the default implementation is ok and you only have to return count | |
73 | of supported formats (CF_xxx constants or one of your custom formats which | |
74 | must have been registered) and their values. | |
75 | ||
76 | b) OnDrop(long x, long y, const void *pData) | |
77 | ||
78 | (x, y) are drop point (client) coordinates, pData is the pointer to data | |
79 | (whatever it is). | |
80 | ||
81 | If 'true' is returned from OnDrop, the operation is considered to be | |
82 | successful and the corresponding code (MOVE or COPY depending on the | |
83 | keyboard control keys) is returned. Otherwise, the operation is cancelled. | |
84 | ||
85 | Please remember that returning 'true' here may mean 'move' and so the | |
86 | drop source will delete the corresponding data - which would lead to | |
87 | data loss if you didn't paste it properly. | |
88 | ||
89 | c) OnEnter() | |
90 | ||
91 | called when the mouse enters the window: you might use this function to | |
92 | give some additional visual feedback. | |
93 | ||
94 | d) OnLeave() | |
95 | ||
96 | called when the mouse leaves the window; might be a good place to clean | |
97 | up things allocated in OnEnter. | |
98 | ||
99 | e) Simple wxDropTarget specializations | |
100 | ||
101 | Two (very simple) wxDropTarget-derived classes are provided for two most | |
102 | common situations: d&d of text and file d&d. To use them you only need to | |
103 | override one virtual function OnDropText in wxTextDropTarget's case and | |
104 | OnDropFiles for wxFileDropTarget. | |
105 | ||
106 | The (x, y) are the same as for OnDrop() function. OnDropText's last | |
107 | parameter points to a (always ANSI, not Unicode) text string, while | |
108 | OnDropFiles() parameter is the array of file names just dropped (and the | |
109 | count of them is passed in the 3rd parameter). | |
110 | ||
111 | 3. Data Object | |
112 | ----------- | |
113 | ||
114 | a) Drag and drop and clipboard | |
115 | ||
116 | The effect of a d&d operation is the same as using the clipboard to | |
117 | cut/copy and paste data and it would be nice to use the same code to implement | |
118 | these two data transfer mechanisms. The wxDataObject allows you to do exactly | |
119 | this. It encapsulates the data which can be passed either through the clipboard | |
120 | or d&d. | |
121 | ||
122 | ||
123 | b) Data format | |
124 | ||
125 | There are several standard clipboard formats, such as text, bitmap or | |
126 | metafile picture. All of them are defined in wxDataObject::StdFormats | |
127 | enumeration. Of course, it's not always enough and you'll often need your | |
128 | own format for data transfer. The simple helper class wxDataFormat may help | |
129 | you: when you create an object of this class, it registers a new clipboard | |
e3778b4d | 130 | data format identified by the string passed to its ctor. |
457814b5 JS |
131 | |
132 | After your new format is registered, you may use it as any other one. | |
133 | ||
134 | 4. Drop Source | |
135 | ----------- | |
136 | ||
137 | a) Starting the d&d operation | |
138 | ||
139 | In order to start the d&d operation you should call the DoDragDrop function | |
140 | (typically in reply to a "mouse button press" message). NB: DoDragDrop() is a | |
e3778b4d | 141 | blocking function which enters into its own message loop and may return after |
457814b5 JS |
142 | an arbitrarily long time interval. During it, the QueryContinueDrag() is called |
143 | whenever the mouse or keyboard state changes. The default behaviour is quite | |
144 | reasonable for 99% of cases: the drag operation is cancelled if the <Esc> key | |
145 | is preessed and the drop is initiated if the mouse button is released. | |
146 | ||
147 | b) After the end of d&d | |
148 | ||
149 | The drop source behaviour depends on DoDragDrop() return code. If it | |
150 | returns wxDropSource::None or wxDropSource::Copy there is normally nothing to | |
151 | do, but you shouldn't forget to delete your data if it returns the | |
152 | wxDropSource::Move code. | |
153 | ||
154 | c) DoDragDrop | |
155 | ||
156 | d) QueryContinueDrag | |
157 | ||
158 | ||
159 | 5. Remarks | |
160 | ------- | |
161 | ||
162 | ||
163 | @@@@ TODO: support tymed != TYMED_HGLOBAL; | |
164 | better support of CF_BMP, CF_METAFILE | |
165 | scrolling support!! (how?) | |
166 | sample demonstrating use of user-defined formats | |
167 | sample which really does something useful |