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