1 ///////////////////////////////////////////////////////////////////////////// 2 // Name: dnd.h 3 // Purpose: interface of wxDropSource and wx*DropTarget 4 // Author: wxWidgets team 5 // Licence: wxWindows licence 6 ///////////////////////////////////////////////////////////////////////////// 7 8 /** 9 Possible flags for drag and drop operations. 10 */ 11 enum 12 { 13 wxDrag_CopyOnly = 0, ///< Allow only copying. 14 wxDrag_AllowMove = 1, ///< Allow moving too (copying is always allowed). 15 wxDrag_DefaultMove = 3 ///< Allow moving and make it default operation. 16 }; 17 18 /** 19 Result returned from a wxDropSource::DoDragDrop() call. 20 */ 21 enum wxDragResult 22 { 23 wxDragError, ///< Error prevented the D&D operation from completing. 24 wxDragNone, ///< Drag target didn't accept the data. 25 wxDragCopy, ///< The data was successfully copied. 26 wxDragMove, ///< The data was successfully moved (MSW only). 27 wxDragLink, ///< Operation is a drag-link. 28 wxDragCancel ///< The operation was cancelled by user (not an error). 29 }; 30 31 32 33 /** 34 @class wxDropTarget 35 36 This class represents a target for a drag and drop operation. A 37 wxDataObject can be associated with it and by default, this object will be 38 filled with the data from the drag source, if the data formats supported by 39 the data object match the drag source data format. 40 41 There are various virtual handler functions defined in this class which may 42 be overridden to give visual feedback or react in a more fine-tuned way, 43 e.g. by not accepting data on the whole window area, but only a small 44 portion of it. The normal sequence of calls is OnEnter(), OnDragOver() 45 possibly many times, OnDrop() and finally OnData(). 46 47 @library{wxcore} 48 @category{dnd} 49 50 @see @ref overview_dnd, @ref overview_dataobject, wxDropSource, 51 wxTextDropTarget, wxFileDropTarget, wxDataFormat, wxDataObject 52 */ 53 class wxDropTarget 54 { 55 public: 56 /** 57 Constructor. @a data is the data to be associated with the drop target. 58 */ 59 wxDropTarget(wxDataObject* data = NULL); 60 61 /** 62 Destructor. Deletes the associated data object, if any. 63 */ 64 virtual ~wxDropTarget(); 65 66 /** 67 This method may only be called from within OnData(). By default, this 68 method copies the data from the drop source to the wxDataObject 69 associated with this drop target, calling its wxDataObject::SetData() 70 method. 71 */ 72 virtual bool GetData(); 73 74 /** 75 Called after OnDrop() returns @true. By default this will usually 76 GetData() and will return the suggested default value @a defResult. 77 */ 78 virtual wxDragResult OnData(wxCoord x, wxCoord y, wxDragResult defResult) = 0; 79 80 /** 81 Called when the mouse is being dragged over the drop target. By 82 default, this calls functions return the suggested return value @a defResult. 83 84 @param x 85 The x coordinate of the mouse. 86 @param y 87 The y coordinate of the mouse. 88 @param defResult 89 Suggested value for return value. Determined by SHIFT or CONTROL 90 key states. 91 92 @return The desired operation or wxDragNone. This is used for optical 93 feedback from the side of the drop source, typically in form 94 of changing the icon. 95 */ 96 virtual wxDragResult OnDragOver(wxCoord x, wxCoord y, wxDragResult defResult); 97 98 /** 99 Called when the user drops a data object on the target. Return @false 100 to veto the operation. 101 102 @param x 103 The x coordinate of the mouse. 104 @param y 105 The y coordinate of the mouse. 106 107 @return @true to accept the data, or @false to veto the operation. 108 */ 109 virtual bool OnDrop(wxCoord x, wxCoord y); 110 111 /** 112 Called when the mouse enters the drop target. By default, this calls 113 OnDragOver(). 114 115 @param x 116 The x coordinate of the mouse. 117 @param y 118 The y coordinate of the mouse. 119 @param defResult 120 Suggested default for return value. Determined by SHIFT or CONTROL 121 key states. 122 123 @return The desired operation or wxDragNone. This is used for optical 124 feedback from the side of the drop source, typically in form 125 of changing the icon. 126 */ 127 virtual wxDragResult OnEnter(wxCoord x, wxCoord y, wxDragResult defResult); 128 129 /** 130 Called when the mouse leaves the drop target. 131 */ 132 virtual void OnLeave(); 133 134 /** 135 Returns the data wxDataObject associated with the drop target 136 */ 137 wxDataObject *GetDataObject() const; 138 139 /** 140 Sets the data wxDataObject associated with the drop target and deletes 141 any previously associated data object. 142 */ 143 void SetDataObject(wxDataObject* data); 144 145 146 /** 147 Sets the default action for drag and drop. Use wxDragMove or 148 wxDragCopy to set default action to move or copy and use wxDragNone 149 (default) to set default action specified by initialization of draging 150 (see wxDropSource::DoDragDrop()) 151 */ 152 void SetDefaultAction(wxDragResult action); 153 154 /** 155 Returns default action for drag and drop or wxDragNone if this not 156 specified. 157 */ 158 wxDragResult GetDefaultAction(); 159 160 }; 161 162 163 164 /** 165 @class wxDropSource 166 167 This class represents a source for a drag and drop operation. 168 169 @library{wxcore} 170 @category{dnd} 171 172 @see @ref overview_dnd, @ref overview_dataobject, wxDropTarget, 173 wxTextDropTarget, wxFileDropTarget 174 */ 175 class wxDropSource 176 { 177 public: 178 /** 179 This constructor requires that you must call SetData() later. 180 181 Note that the type of @a iconCopy and subsequent parameters 182 differs between different ports: these are cursors under Windows and OS 183 X but icons for GTK. You should use the macro wxDROP_ICON() in portable 184 programs instead of directly using either of these types. 185 186 @onlyfor{wxmsw,wxosx} 187 188 @param win 189 The window which initiates the drag and drop operation. 190 @param iconCopy 191 The icon or cursor used for feedback for copy operation. 192 @param iconMove 193 The icon or cursor used for feedback for move operation. 194 @param iconNone 195 The icon or cursor used for feedback when operation can't be done. 196 */ 197 wxDropSource(wxWindow* win = NULL, 198 const wxCursor& iconCopy = wxNullCursor, 199 const wxCursor& iconMove = wxNullCursor, 200 const wxCursor& iconNone = wxNullCursor); 201 202 /** 203 The constructor taking a wxDataObject. 204 205 Note that the type of @a iconCopy and subsequent parameters 206 differs between different ports: these are cursors under Windows and OS 207 X but icons for GTK. You should use the macro wxDROP_ICON() in portable 208 programs instead of directly using either of these types. 209 210 @onlyfor{wxmsw,wxosx} 211 212 @param data 213 The data associated with the drop source. 214 @param win 215 The window which initiates the drag and drop operation. 216 @param iconCopy 217 The icon or cursor used for feedback for copy operation. 218 @param iconMove 219 The icon or cursor used for feedback for move operation. 220 @param iconNone 221 The icon or cursor used for feedback when operation can't be done. 222 */ 223 wxDropSource(wxDataObject& data, wxWindow* win = NULL, 224 const wxCursor& iconCopy = wxNullCursor, 225 const wxCursor& iconMove = wxNullCursor, 226 const wxCursor& iconNone = wxNullCursor); 227 228 /** 229 This constructor requires that you must call SetData() later. 230 231 This is the wxGTK-specific version of the constructor taking wxIcon 232 instead of wxCursor as the other ports. 233 234 @onlyfor{wxgtk} 235 236 @param win 237 The window which initiates the drag and drop operation. 238 @param iconCopy 239 The icon or cursor used for feedback for copy operation. 240 @param iconMove 241 The icon or cursor used for feedback for move operation. 242 @param iconNone 243 The icon or cursor used for feedback when operation can't be done. 244 */ 245 wxDropSource(wxWindow* win = NULL, 246 const wxIcon& iconCopy = wxNullIcon, 247 const wxIcon& iconMove = wxNullIcon, 248 const wxIcon& iconNone = wxNullIcon); 249 250 /** 251 The constructor taking a wxDataObject. 252 253 This is the wxGTK-specific version of the constructor taking wxIcon 254 instead of wxCursor as the other ports. 255 256 @onlyfor{wxgtk} 257 258 @param data 259 The data associated with the drop source. 260 @param win 261 The window which initiates the drag and drop operation. 262 @param iconCopy 263 The icon or cursor used for feedback for copy operation. 264 @param iconMove 265 The icon or cursor used for feedback for move operation. 266 @param iconNone 267 The icon or cursor used for feedback when operation can't be done. 268 */ 269 wxDropSource(wxDataObject& data, wxWindow* win = NULL, 270 const wxIcon& iconCopy = wxNullIcon, 271 const wxIcon& iconMove = wxNullIcon, 272 const wxIcon& iconNone = wxNullIcon); 273 274 /** 275 Starts the drag-and-drop operation which will terminate when the user 276 releases the mouse. Call this in response to a mouse button press, for 277 example. 278 279 @param flags 280 If ::wxDrag_AllowMove is included in the flags, data may be moved 281 and not only copied as is the case for the default 282 ::wxDrag_CopyOnly. If ::wxDrag_DefaultMove is specified 283 (which includes the previous flag), moving is not only possible but 284 becomes the default operation. 285 286 @return The operation requested by the user, may be ::wxDragCopy, 287 ::wxDragMove, ::wxDragLink, ::wxDragCancel or ::wxDragNone if 288 an error occurred. 289 */ 290 virtual wxDragResult DoDragDrop(int flags = wxDrag_CopyOnly); 291 292 /** 293 Returns the wxDataObject object that has been assigned previously. 294 */ 295 wxDataObject* GetDataObject(); 296 297 /** 298 You may give some custom UI feedback during the drag and drop operation 299 by overriding this function. It is called on each mouse move, so your 300 implementation must not be too slow. 301 302 @param effect 303 The effect to implement. One of ::wxDragCopy, ::wxDragMove, 304 ::wxDragLink and ::wxDragNone. 305 306 @return @false if you want default feedback, or @true if you implement 307 your own feedback. The return value is ignored under GTK. 308 */ 309 virtual bool GiveFeedback(wxDragResult effect); 310 311 /** 312 Set the icon to use for a certain drag result. 313 314 @param res 315 The drag result to set the icon for. 316 @param cursor 317 The icon to show when this drag result occurs. 318 319 @onlyfor{wxmsw,wxosx} 320 */ 321 void SetCursor(wxDragResult res, const wxCursor& cursor); 322 323 /** 324 Set the icon to use for a certain drag result. 325 326 @param res 327 The drag result to set the icon for. 328 @param icon 329 The icon to show when this drag result occurs. 330 331 @onlyfor{wxgtk} 332 */ 333 void SetIcon(wxDragResult res, const wxIcon& icon); 334 335 /** 336 Sets the data wxDataObject associated with the drop source. This will 337 not delete any previously associated data. 338 */ 339 void SetData(wxDataObject& data); 340 }; 341 342 343 344 /** 345 @class wxTextDropTarget 346 347 A predefined drop target for dealing with text data. 348 349 @library{wxcore} 350 @category{dnd} 351 352 @see @ref overview_dnd, wxDropSource, wxDropTarget, wxFileDropTarget 353 */ 354 class wxTextDropTarget : public wxDropTarget 355 { 356 public: 357 /** 358 Constructor. 359 */ 360 wxTextDropTarget(); 361 362 /** 363 See wxDropTarget::OnDrop(). This function is implemented appropriately 364 for text, and calls OnDropText(). 365 */ 366 virtual bool OnDrop(wxCoord x, wxCoord y); 367 368 /** 369 Override this function to receive dropped text. 370 371 @param x 372 The x coordinate of the mouse. 373 @param y 374 The y coordinate of the mouse. 375 @param data 376 The data being dropped: a wxString. 377 378 Return @true to accept the data, or @false to veto the operation. 379 */ 380 virtual bool OnDropText(wxCoord x, wxCoord y, const wxString& data) = 0; 381 }; 382 383 384 /** 385 @class wxFileDropTarget 386 387 This is a drop target which accepts files (dragged from File Manager or 388 Explorer). 389 390 @library{wxcore} 391 @category{dnd} 392 393 @see @ref overview_dnd, wxDropSource, wxDropTarget, wxTextDropTarget 394 */ 395 class wxFileDropTarget : public wxDropTarget 396 { 397 public: 398 /** 399 Constructor. 400 */ 401 wxFileDropTarget(); 402 403 /** 404 See wxDropTarget::OnDrop(). This function is implemented appropriately 405 for files, and calls OnDropFiles(). 406 */ 407 virtual bool OnDrop(wxCoord x, wxCoord y); 408 409 /** 410 Override this function to receive dropped files. 411 412 @param x 413 The x coordinate of the mouse. 414 @param y 415 The y coordinate of the mouse. 416 @param filenames 417 An array of filenames. 418 419 Return @true to accept the data, or @false to veto the operation. 420 */ 421 virtual bool OnDropFiles(wxCoord x, wxCoord y, 422 const wxArrayString& filenames) = 0; 423 }; 424 425 426 427 // ============================================================================ 428 // Global functions/macros 429 // ============================================================================ 430 431 /** @addtogroup group_funcmacro_gdi */ 432 //@{ 433 434 /** 435 This macro creates either a cursor (MSW) or an icon (elsewhere) with the 436 given @a name (of type <tt>const char*</tt>). Under MSW, the cursor is 437 loaded from the resource file and the icon is loaded from XPM file under 438 other platforms. 439 440 This macro should be used with wxDropSource::wxDropSource(). 441 442 @return wxCursor on MSW, otherwise returns a wxIcon 443 444 @header{wx/dnd.h} 445 */ 446 #define wxDROP_ICON(name) 447 448 /** 449 Returns true if res indicates that something was done during a DnD operation, 450 i.e. is neither error nor none nor cancel. 451 */ 452 bool wxIsDragResultOk(wxDragResult res); 453 454 //@} 455 456