interface/wx/dnd.h

   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 deafult 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