]>
git.saurik.com Git - wxWidgets.git/blob - interface/wx/dnd.h
1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxDropSource and wx*DropTarget
4 // Author: wxWidgets team
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
10 @class wxTextDropTarget
12 A predefined drop target for dealing with text data.
17 @see @ref overview_dnd, wxDropSource, wxDropTarget, wxFileDropTarget
19 class wxTextDropTarget
: public wxDropTarget
28 See wxDropTarget::OnDrop(). This function is implemented appropriately
29 for text, and calls OnDropText().
31 virtual bool OnDrop(wxCoord x
, wxCoord y
);
34 Override this function to receive dropped text.
37 The x coordinate of the mouse.
39 The y coordinate of the mouse.
41 The data being dropped: a wxString.
43 Return @true to accept the data, or @false to veto the operation.
45 virtual bool OnDropText(wxCoord x
, wxCoord y
, const wxString
& data
) = 0;
51 Result returned from a wxDropSource::DoDragDrop() call.
55 wxDragError
, ///< Error prevented the D&D operation from completing.
56 wxDragNone
, ///< Drag target didn't accept the data.
57 wxDragCopy
, ///< The data was successfully copied.
58 wxDragMove
, ///< The data was successfully moved (MSW only).
59 wxDragLink
, ///< Operation is a drag-link.
60 wxDragCancel
///< The operation was cancelled by user (not an error).
66 This class represents a target for a drag and drop operation. A
67 wxDataObject can be associated with it and by default, this object will be
68 filled with the data from the drag source, if the data formats supported by
69 the data object match the drag source data format.
71 There are various virtual handler functions defined in this class which may
72 be overridden to give visual feedback or react in a more fine-tuned way,
73 e.g. by not accepting data on the whole window area, but only a small
74 portion of it. The normal sequence of calls is OnEnter(), OnDragOver()
75 possibly many times, OnDrop() and finally OnData().
80 @see @ref overview_dnd, @ref overview_dataobject, wxDropSource,
81 wxTextDropTarget, wxFileDropTarget, wxDataFormat, wxDataObject
87 Constructor. @a data is the data to be associated with the drop target.
89 wxDropTarget(wxDataObject
* data
= NULL
);
92 Destructor. Deletes the associated data object, if any.
94 virtual ~wxDropTarget();
97 This method may only be called from within OnData(). By default, this
98 method copies the data from the drop source to the wxDataObject
99 associated with this drop target, calling its wxDataObject::SetData()
102 virtual bool GetData();
105 Called after OnDrop() returns @true. By default this will usually
106 GetData() and will return the suggested default value @a def.
108 virtual wxDragResult
OnData(wxCoord x
, wxCoord y
, wxDragResult def
);
111 Called when the mouse is being dragged over the drop target. By
112 default, this calls functions return the suggested return value @a def.
115 The x coordinate of the mouse.
117 The y coordinate of the mouse.
119 Suggested value for return value. Determined by SHIFT or CONTROL
122 @return The desired operation or wxDragNone. This is used for optical
123 feedback from the side of the drop source, typically in form
124 of changing the icon.
126 virtual wxDragResult
OnDragOver(wxCoord x
, wxCoord y
, wxDragResult def
);
129 Called when the user drops a data object on the target. Return @false
130 to veto the operation.
133 The x coordinate of the mouse.
135 The y coordinate of the mouse.
137 @return @true to accept the data, or @false to veto the operation.
139 virtual bool OnDrop(wxCoord x
, wxCoord y
);
142 Called when the mouse enters the drop target. By default, this calls
146 The x coordinate of the mouse.
148 The y coordinate of the mouse.
150 Suggested default for return value. Determined by SHIFT or CONTROL
153 @return The desired operation or wxDragNone. This is used for optical
154 feedback from the side of the drop source, typically in form
155 of changing the icon.
157 virtual wxDragResult
OnEnter(wxCoord x
, wxCoord y
, wxDragResult def
);
160 Called when the mouse leaves the drop target.
162 virtual void OnLeave();
165 Sets the data wxDataObject associated with the drop target and deletes
166 any previously associated data object.
168 void SetDataObject(wxDataObject
* data
);
176 This class represents a source for a drag and drop operation.
181 @see @ref overview_dnd, @ref overview_dataobject, wxDropTarget,
182 wxTextDropTarget, wxFileDropTarget
188 This constructor requires that you must call SetData() later.
190 Note that the exact type of @a iconCopy and subsequent parameters
191 differs between wxMSW and wxGTK: these are cursors under Windows but
192 icons for GTK. You should use the macro wxDROP_ICON() in portable
193 programs instead of directly using either of these types.
196 The window which initiates the drag and drop operation.
198 The icon or cursor used for feedback for copy operation.
200 The icon or cursor used for feedback for move operation.
202 The icon or cursor used for feedback when operation can't be done.
204 wxDropSource(wxWindow
* win
= NULL
,
205 const wxIconOrCursor
& iconCopy
= wxNullIconOrCursor
,
206 const wxIconOrCursor
& iconMove
= wxNullIconOrCursor
,
207 const wxIconOrCursor
& iconNone
= wxNullIconOrCursor
);
210 The constructor for wxDataObject.
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.
218 The data associated with the drop source.
220 The window which initiates the drag and drop operation.
222 The icon or cursor used for feedback for copy operation.
224 The icon or cursor used for feedback for move operation.
226 The icon or cursor used for feedback when operation can't be done.
228 wxDropSource(wxDataObject
& data
, wxWindow
* win
= NULL
,
229 const wxIconOrCursor
& iconCopy
= wxNullIconOrCursor
,
230 const wxIconOrCursor
& iconMove
= wxNullIconOrCursor
,
231 const wxIconOrCursor
& iconNone
= wxNullIconOrCursor
);
236 virtual ~wxDropSource();
239 Starts the drag-and-drop operation which will terminate when the user
240 releases the mouse. Call this in response to a mouse button press, for
244 If wxDrag_AllowMove is included in the flags, data may be moved and
245 not only copied (default). If wxDrag_DefaultMove is specified
246 (which includes the previous flag), this is even the default
249 @return The operation requested by the user, may be ::wxDragCopy,
250 ::wxDragMove, ::wxDragLink, ::wxDragCancel or ::wxDragNone if
253 virtual wxDragResult
DoDragDrop(int flags
= wxDrag_CopyOnly
);
256 Returns the wxDataObject object that has been assigned previously.
258 wxDataObject
* GetDataObject();
261 You may give some custom UI feedback during the drag and drop operation
262 by overriding this function. It is called on each mouse move, so your
263 implementation must not be too slow.
266 The effect to implement. One of ::wxDragCopy, ::wxDragMove,
267 ::wxDragLink and ::wxDragNone.
269 @return @false if you want default feedback, or @true if you implement
270 your own feedback. The return value is ignored under GTK.
272 virtual bool GiveFeedback(wxDragResult effect
);
275 Set the icon to use for a certain drag result.
278 The drag result to set the icon for.
280 The ion to show when this drag result occurs.
282 void SetCursor(wxDragResult res
, const wxCursor
& cursor
);
285 Sets the data wxDataObject associated with the drop source. This will
286 not delete any previously associated data.
288 void SetData(wxDataObject
& data
);
294 @class wxFileDropTarget
296 This is a drop target which accepts files (dragged from File Manager or
302 @see @ref overview_dnd, wxDropSource, wxDropTarget, wxTextDropTarget
304 class wxFileDropTarget
: public wxDropTarget
313 See wxDropTarget::OnDrop(). This function is implemented appropriately
314 for files, and calls OnDropFiles().
316 virtual bool OnDrop(wxCoord x
, wxCoord y
);
319 Override this function to receive dropped files.
322 The x coordinate of the mouse.
324 The y coordinate of the mouse.
326 An array of filenames.
328 Return @true to accept the data, or @false to veto the operation.
330 virtual bool OnDropFiles(wxCoord x
, wxCoord y
,
331 const wxArrayString
& filenames
) = 0;
336 // ============================================================================
337 // Global functions/macros
338 // ============================================================================
340 /** @ingroup group_funcmacro_gdi */
344 This macro creates either a cursor (MSW) or an icon (elsewhere) with the
345 given @a name (of type <tt>const char*</tt>). Under MSW, the cursor is
346 loaded from the resource file and the icon is loaded from XPM file under
349 This macro should be used with wxDropSource::wxDropSource().
351 @return wxCursor on MSW, otherwise returns a wxIcon
355 #define wxDROP_ICON(name)