interface/dnd.h

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