1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxDropSource and wx*DropTarget
4 // Author: wxWidgets team
6 // Licence: wxWindows licence
7 /////////////////////////////////////////////////////////////////////////////
10 Possible flags for drag and drop operations.
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.
20 @class wxTextDropTarget
22 A predefined drop target for dealing with text data.
27 @see @ref overview_dnd, wxDropSource, wxDropTarget, wxFileDropTarget
29 class wxTextDropTarget
: public wxDropTarget
38 See wxDropTarget::OnDrop(). This function is implemented appropriately
39 for text, and calls OnDropText().
41 virtual bool OnDrop(wxCoord x
, wxCoord y
);
44 Override this function to receive dropped text.
47 The x coordinate of the mouse.
49 The y coordinate of the mouse.
51 The data being dropped: a wxString.
53 Return @true to accept the data, or @false to veto the operation.
55 virtual bool OnDropText(wxCoord x
, wxCoord y
, const wxString
& data
) = 0;
61 Result returned from a wxDropSource::DoDragDrop() call.
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).
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.
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().
90 @see @ref overview_dnd, @ref overview_dataobject, wxDropSource,
91 wxTextDropTarget, wxFileDropTarget, wxDataFormat, wxDataObject
97 Constructor. @a data is the data to be associated with the drop target.
99 wxDropTarget(wxDataObject
* data
= NULL
);
102 Destructor. Deletes the associated data object, if any.
104 virtual ~wxDropTarget();
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()
112 virtual bool GetData() = 0;
115 Called after OnDrop() returns @true. By default this will usually
116 GetData() and will return the suggested default value @a def.
118 virtual wxDragResult
OnData(wxCoord x
, wxCoord y
, wxDragResult def
) = 0;
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.
125 The x coordinate of the mouse.
127 The y coordinate of the mouse.
129 Suggested value for return value. Determined by SHIFT or CONTROL
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.
136 virtual wxDragResult
OnDragOver(wxCoord x
, wxCoord y
, wxDragResult def
);
139 Called when the user drops a data object on the target. Return @false
140 to veto the operation.
143 The x coordinate of the mouse.
145 The y coordinate of the mouse.
147 @return @true to accept the data, or @false to veto the operation.
149 virtual bool OnDrop(wxCoord x
, wxCoord y
) = 0;
152 Called when the mouse enters the drop target. By default, this calls
156 The x coordinate of the mouse.
158 The y coordinate of the mouse.
160 Suggested default for return value. Determined by SHIFT or CONTROL
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.
167 virtual wxDragResult
OnEnter(wxCoord x
, wxCoord y
, wxDragResult def
);
170 Called when the mouse leaves the drop target.
172 virtual void OnLeave();
175 Sets the data wxDataObject associated with the drop target and deletes
176 any previously associated data object.
178 void SetDataObject(wxDataObject
* data
);
186 This class represents a source for a drag and drop operation.
191 @see @ref overview_dnd, @ref overview_dataobject, wxDropTarget,
192 wxTextDropTarget, wxFileDropTarget
198 This constructor requires that you must call SetData() later.
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.
205 @onlyfor{wxmsw,wxosx}
208 The window which initiates the drag and drop operation.
210 The icon or cursor used for feedback for copy operation.
212 The icon or cursor used for feedback for move operation.
214 The icon or cursor used for feedback when operation can't be done.
216 wxDropSource(wxWindow
* win
= NULL
,
217 const wxCursor
& iconCopy
= wxNullIcon
,
218 const wxCursor
& iconMove
= wxNullIcon
,
219 const wxCursor
& iconNone
= wxNullIcon
);
222 The constructor taking a wxDataObject.
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.
229 @onlyfor{wxmsw,wxosx}
232 The data associated with the drop source.
234 The window which initiates the drag and drop operation.
236 The icon or cursor used for feedback for copy operation.
238 The icon or cursor used for feedback for move operation.
240 The icon or cursor used for feedback when operation can't be done.
242 wxDropSource(wxDataObject
& data
, wxWindow
* win
= NULL
,
243 const wxCursor
& iconCopy
= wxNullIcon
,
244 const wxCursor
& iconMove
= wxNullIcon
,
245 const wxCursor
& iconNone
= wxNullIcon
);
248 This constructor requires that you must call SetData() later.
250 This is the wxGTK-specific version of the constructor taking wxIcon
251 instead of wxCursor as the other ports.
256 The window which initiates the drag and drop operation.
258 The icon or cursor used for feedback for copy operation.
260 The icon or cursor used for feedback for move operation.
262 The icon or cursor used for feedback when operation can't be done.
264 wxDropSource(wxWindow
* win
= NULL
,
265 const wxIcon
& iconCopy
= wxNullCursor
,
266 const wxIcon
& iconMove
= wxNullCursor
,
267 const wxIcon
& iconNone
= wxNullCursor
);
270 The constructor taking a wxDataObject.
272 This is the wxGTK-specific version of the constructor taking wxIcon
273 instead of wxCursor as the other ports.
278 The data associated with the drop source.
280 The window which initiates the drag and drop operation.
282 The icon or cursor used for feedback for copy operation.
284 The icon or cursor used for feedback for move operation.
286 The icon or cursor used for feedback when operation can't be done.
288 wxDropSource(wxDataObject
& data
, wxWindow
* win
= NULL
,
289 const wxIcon
& iconCopy
= wxNullCursor
,
290 const wxIcon
& iconMove
= wxNullCursor
,
291 const wxIcon
& iconNone
= wxNullCursor
);
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
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.
305 @return The operation requested by the user, may be ::wxDragCopy,
306 ::wxDragMove, ::wxDragLink, ::wxDragCancel or ::wxDragNone if
309 virtual wxDragResult
DoDragDrop(int flags
= wxDrag_CopyOnly
);
312 Returns the wxDataObject object that has been assigned previously.
314 wxDataObject
* GetDataObject();
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.
322 The effect to implement. One of ::wxDragCopy, ::wxDragMove,
323 ::wxDragLink and ::wxDragNone.
325 @return @false if you want default feedback, or @true if you implement
326 your own feedback. The return value is ignored under GTK.
328 virtual bool GiveFeedback(wxDragResult effect
);
331 Set the icon to use for a certain drag result.
334 The drag result to set the icon for.
336 The ion to show when this drag result occurs.
338 void SetCursor(wxDragResult res
, const wxCursor
& cursor
);
341 Sets the data wxDataObject associated with the drop source. This will
342 not delete any previously associated data.
344 void SetData(wxDataObject
& data
);
350 @class wxFileDropTarget
352 This is a drop target which accepts files (dragged from File Manager or
358 @see @ref overview_dnd, wxDropSource, wxDropTarget, wxTextDropTarget
360 class wxFileDropTarget
: public wxDropTarget
369 See wxDropTarget::OnDrop(). This function is implemented appropriately
370 for files, and calls OnDropFiles().
372 virtual bool OnDrop(wxCoord x
, wxCoord y
);
375 Override this function to receive dropped files.
378 The x coordinate of the mouse.
380 The y coordinate of the mouse.
382 An array of filenames.
384 Return @true to accept the data, or @false to veto the operation.
386 virtual bool OnDropFiles(wxCoord x
, wxCoord y
,
387 const wxArrayString
& filenames
) = 0;
392 // ============================================================================
393 // Global functions/macros
394 // ============================================================================
396 /** @addtogroup group_funcmacro_gdi */
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
405 This macro should be used with wxDropSource::wxDropSource().
407 @return wxCursor on MSW, otherwise returns a wxIcon
411 #define wxDROP_ICON(name)