interface/wx/dnd.h

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