interface/dnd.h

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