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