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