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         Returns the data wxDataObject associated with the drop target
 137     */
 138     wxDataObject *GetDataObject() const;
 139
 140     /**
 141         Sets the data wxDataObject associated with the drop target and deletes
 142         any previously associated data object.
 143     */
 144     void SetDataObject(wxDataObject* data);
 145
 146
 147     /**
 148        Sets the default action for drag and drop.  Use wxDragMove or
 149        wxDragCopy to set deafult action to move or copy and use wxDragNone
 150        (default) to set default action specified by initialization of draging
 151        (see wxDropSource::DoDragDrop())
 152     */
 153     void SetDefaultAction(wxDragResult action);
 154
 155     /**
 156        Returns default action for drag and drop or wxDragNone if this not
 157        specified.
 158     */
 159     wxDragResult GetDefaultAction();
 160
 161 };
 162
 163
 164
 165 /**
 166     @class wxDropSource
 167
 168     This class represents a source for a drag and drop operation.
 169
 170     @library{wxcore}
 171     @category{dnd}
 172
 173     @see @ref overview_dnd, @ref overview_dataobject, wxDropTarget,
 174          wxTextDropTarget, wxFileDropTarget
 175 */
 176 class wxDropSource
 177 {
 178 public:
 179     /**
 180         This constructor requires that you must call SetData() later.
 181
 182         Note that the type of @a iconCopy and subsequent parameters
 183         differs between different ports: these are cursors under Windows and OS
 184         X but icons for GTK. You should use the macro wxDROP_ICON() in portable
 185         programs instead of directly using either of these types.
 186
 187         @onlyfor{wxmsw,wxosx}
 188
 189         @param win
 190             The window which initiates the drag and drop operation.
 191         @param iconCopy
 192             The icon or cursor used for feedback for copy operation.
 193         @param iconMove
 194             The icon or cursor used for feedback for move operation.
 195         @param iconNone
 196             The icon or cursor used for feedback when operation can't be done.
 197     */
 198     wxDropSource(wxWindow* win = NULL,
 199                  const wxCursor& iconCopy = wxNullCursor,
 200                  const wxCursor& iconMove = wxNullCursor,
 201                  const wxCursor& iconNone = wxNullCursor);
 202
 203     /**
 204         The constructor taking a wxDataObject.
 205
 206         Note that the type of @a iconCopy and subsequent parameters
 207         differs between different ports: these are cursors under Windows and OS
 208         X but icons for GTK. You should use the macro wxDROP_ICON() in portable
 209         programs instead of directly using either of these types.
 210
 211         @onlyfor{wxmsw,wxosx}
 212
 213         @param data
 214             The data associated with the drop source.
 215         @param win
 216             The window which initiates the drag and drop operation.
 217         @param iconCopy
 218             The icon or cursor used for feedback for copy operation.
 219         @param iconMove
 220             The icon or cursor used for feedback for move operation.
 221         @param iconNone
 222             The icon or cursor used for feedback when operation can't be done.
 223     */
 224     wxDropSource(wxDataObject& data, wxWindow* win = NULL,
 225                  const wxCursor& iconCopy = wxNullCursor,
 226                  const wxCursor& iconMove = wxNullCursor,
 227                  const wxCursor& iconNone = wxNullCursor);
 228
 229     /**
 230         This constructor requires that you must call SetData() later.
 231
 232         This is the wxGTK-specific version of the constructor taking wxIcon
 233         instead of wxCursor as the other ports.
 234
 235         @onlyfor{wxgtk}
 236
 237         @param win
 238             The window which initiates the drag and drop operation.
 239         @param iconCopy
 240             The icon or cursor used for feedback for copy operation.
 241         @param iconMove
 242             The icon or cursor used for feedback for move operation.
 243         @param iconNone
 244             The icon or cursor used for feedback when operation can't be done.
 245     */
 246     wxDropSource(wxWindow* win = NULL,
 247                  const wxIcon& iconCopy = wxNullIcon,
 248                  const wxIcon& iconMove = wxNullIcon,
 249                  const wxIcon& iconNone = wxNullIcon);
 250
 251     /**
 252         The constructor taking a wxDataObject.
 253
 254         This is the wxGTK-specific version of the constructor taking wxIcon
 255         instead of wxCursor as the other ports.
 256
 257         @onlyfor{wxgtk}
 258
 259         @param data
 260             The data associated with the drop source.
 261         @param win
 262             The window which initiates the drag and drop operation.
 263         @param iconCopy
 264             The icon or cursor used for feedback for copy operation.
 265         @param iconMove
 266             The icon or cursor used for feedback for move operation.
 267         @param iconNone
 268             The icon or cursor used for feedback when operation can't be done.
 269     */
 270     wxDropSource(wxDataObject& data, wxWindow* win = NULL,
 271                  const wxIcon& iconCopy = wxNullIcon,
 272                  const wxIcon& iconMove = wxNullIcon,
 273                  const wxIcon& iconNone = wxNullIcon);
 274
 275     /**
 276         Starts the drag-and-drop operation which will terminate when the user
 277         releases the mouse. Call this in response to a mouse button press, for
 278         example.
 279
 280         @param flags
 281             If ::wxDrag_AllowMove is included in the flags, data may be moved
 282             and not only copied as is the case for the default
 283             ::wxDrag_CopyOnly. If ::wxDrag_DefaultMove is specified
 284             (which includes the previous flag), moving is not only possible but
 285             becomes the default operation.
 286
 287         @return The operation requested by the user, may be ::wxDragCopy,
 288                  ::wxDragMove, ::wxDragLink, ::wxDragCancel or ::wxDragNone if
 289                  an error occurred.
 290     */
 291     virtual wxDragResult DoDragDrop(int flags = wxDrag_CopyOnly);
 292
 293     /**
 294         Returns the wxDataObject object that has been assigned previously.
 295     */
 296     wxDataObject* GetDataObject();
 297
 298     /**
 299         You may give some custom UI feedback during the drag and drop operation
 300         by overriding this function. It is called on each mouse move, so your
 301         implementation must not be too slow.
 302
 303         @param effect
 304             The effect to implement. One of ::wxDragCopy, ::wxDragMove,
 305             ::wxDragLink and ::wxDragNone.
 306
 307         @return @false if you want default feedback, or @true if you implement
 308                 your own feedback. The return value is ignored under GTK.
 309     */
 310     virtual bool GiveFeedback(wxDragResult effect);
 311
 312     /**
 313         Set the icon to use for a certain drag result.
 314
 315         @param res
 316             The drag result to set the icon for.
 317         @param cursor
 318             The icon to show when this drag result occurs.
 319
 320         @onlyfor{wxmsw,wxosx}
 321     */
 322     void SetCursor(wxDragResult res, const wxCursor& cursor);
 323
 324     /**
 325         Set the icon to use for a certain drag result.
 326
 327         @param res
 328             The drag result to set the icon for.
 329         @param icon
 330             The icon to show when this drag result occurs.
 331
 332         @onlyfor{wxgtk}
 333     */
 334     void SetIcon(wxDragResult res, const wxIcon& icon);
 335
 336     /**
 337         Sets the data wxDataObject associated with the drop source. This will
 338         not delete any previously associated data.
 339     */
 340     void SetData(wxDataObject& data);
 341 };
 342
 343
 344
 345 /**
 346     @class wxTextDropTarget
 347
 348     A predefined drop target for dealing with text data.
 349
 350     @library{wxcore}
 351     @category{dnd}
 352
 353     @see @ref overview_dnd, wxDropSource, wxDropTarget, wxFileDropTarget
 354 */
 355 class wxTextDropTarget : public wxDropTarget
 356 {
 357 public:
 358     /**
 359         Constructor.
 360     */
 361     wxTextDropTarget();
 362
 363     /**
 364         See wxDropTarget::OnDrop(). This function is implemented appropriately
 365         for text, and calls OnDropText().
 366     */
 367     virtual bool OnDrop(wxCoord x, wxCoord y);
 368
 369     /**
 370         Override this function to receive dropped text.
 371
 372         @param x
 373             The x coordinate of the mouse.
 374         @param y
 375             The y coordinate of the mouse.
 376         @param data
 377             The data being dropped: a wxString.
 378
 379         Return @true to accept the data, or @false to veto the operation.
 380     */
 381     virtual bool OnDropText(wxCoord x, wxCoord y, const wxString& data) = 0;
 382 };
 383
 384
 385 /**
 386     @class wxFileDropTarget
 387
 388     This is a drop target which accepts files (dragged from File Manager or
 389     Explorer).
 390
 391     @library{wxcore}
 392     @category{dnd}
 393
 394     @see @ref overview_dnd, wxDropSource, wxDropTarget, wxTextDropTarget
 395 */
 396 class wxFileDropTarget : public wxDropTarget
 397 {
 398 public:
 399     /**
 400         Constructor.
 401     */
 402     wxFileDropTarget();
 403
 404     /**
 405         See wxDropTarget::OnDrop(). This function is implemented appropriately
 406         for files, and calls OnDropFiles().
 407     */
 408     virtual bool OnDrop(wxCoord x, wxCoord y);
 409
 410     /**
 411         Override this function to receive dropped files.
 412
 413         @param x
 414             The x coordinate of the mouse.
 415         @param y
 416             The y coordinate of the mouse.
 417         @param filenames
 418             An array of filenames.
 419
 420         Return @true to accept the data, or @false to veto the operation.
 421     */
 422     virtual bool OnDropFiles(wxCoord x, wxCoord y,
 423                              const wxArrayString& filenames) = 0;
 424 };
 425
 426
 427
 428 // ============================================================================
 429 // Global functions/macros
 430 // ============================================================================
 431
 432 /** @addtogroup group_funcmacro_gdi */
 433 //@{
 434
 435 /**
 436     This macro creates either a cursor (MSW) or an icon (elsewhere) with the
 437     given @a name (of type <tt>const char*</tt>). Under MSW, the cursor is
 438     loaded from the resource file and the icon is loaded from XPM file under
 439     other platforms.
 440
 441     This macro should be used with wxDropSource::wxDropSource().
 442
 443     @return wxCursor on MSW, otherwise returns a wxIcon
 444
 445     @header{wx/dnd.h}
 446 */
 447 #define wxDROP_ICON(name)
 448
 449 /**
 450    Returns true if res indicates that something was done during a DnD operation,
 451    i.e. is neither error nor none nor cancel.
 452 */
 453 bool wxIsDragResultOk(wxDragResult res);
 454
 455 //@}
 456