/////////////////////////////////////////////////////////////////////////////
// Name: dnd.h
-// Purpose: documentation for wxTextDropTarget class
+// Purpose: interface of wxDropSource and wx*DropTarget
// Author: wxWidgets team
// RCS-ID: $Id$
// Licence: wxWindows license
/**
@class wxTextDropTarget
@wxheader{dnd.h}
-
+
A predefined drop target for dealing with text data.
-
+
@library{wxcore}
@category{dnd}
-
- @seealso
- @ref overview_wxdndoverview "Drag and drop overview", wxDropSource,
- wxDropTarget, wxFileDropTarget
+
+ @see @ref overview_dnd, wxDropSource, wxDropTarget, wxFileDropTarget
*/
class wxTextDropTarget : public wxDropTarget
{
wxTextDropTarget();
/**
- See wxDropTarget::OnDrop. This function is implemented
- appropriately for text, and calls OnDropText().
+ See wxDropTarget::OnDrop(). This function is implemented appropriately
+ for text, and calls OnDropText().
*/
virtual bool OnDrop(long x, long y, const void data, size_t size);
/**
Override this function to receive dropped text.
-
- @param x
- The x coordinate of the mouse.
-
- @param y
- The y coordinate of the mouse.
-
- @param data
- The data being dropped: a wxString.
+
+ @param x
+ The x coordinate of the mouse.
+ @param y
+ The y coordinate of the mouse.
+ @param data
+ The data being dropped: a wxString.
+
+ Return @true to accept the data, or @false to veto the operation.
*/
- virtual bool OnDropText(wxCoord x, wxCoord y,
- const wxString& data);
+ virtual bool OnDropText(wxCoord x, wxCoord y, const wxString& data);
};
+
+/**
+ Result returned from a wxDropSource::DoDragDrop() call.
+*/
+enum wxDragResult
+{
+ wxDragError, ///< Error prevented the D&D operation from completing.
+ wxDragNone, ///< Drag target didn't accept the data.
+ wxDragCopy, ///< The data was successfully copied.
+ wxDragMove, ///< The data was successfully moved (MSW only).
+ wxDragLink, ///< Operation is a drag-link.
+ wxDragCancel ///< The operation was cancelled by user (not an error).
+};
+
/**
@class wxDropTarget
@wxheader{dnd.h}
-
- This class represents a target for a drag and drop operation. A wxDataObject
- can be associated with it and by default, this object will be filled with the
- data from the
- drag source, if the data formats supported by the data object match the drag
- source data
- format.
-
- There are various virtual handler functions defined in this class which may be
- overridden
- to give visual feedback or react in a more fine-tuned way, e.g. by not
- accepting data on
- the whole window area, but only a small portion of it. The normal sequence of
- calls is
- wxDropTarget::OnEnter, possibly many times wxDropTarget::OnDragOver,
- wxDropTarget::OnDrop and finally wxDropTarget::OnData.
-
- See @ref overview_wxdndoverview "Drag and drop overview" and @ref
- overview_wxdataobjectoverview "wxDataObject overview"
- for more information.
-
+
+ This class represents a target for a drag and drop operation. A
+ wxDataObject can be associated with it and by default, this object will be
+ filled with the data from the drag source, if the data formats supported by
+ the data object match the drag source data format.
+
+ There are various virtual handler functions defined in this class which may
+ be overridden to give visual feedback or react in a more fine-tuned way,
+ e.g. by not accepting data on the whole window area, but only a small
+ portion of it. The normal sequence of calls is OnEnter(), OnDragOver()
+ possibly many times, OnDrop() and finally OnData().
+
@library{wxcore}
@category{dnd}
-
- @seealso
- wxDropSource, wxTextDropTarget, wxFileDropTarget, wxDataFormat, wxDataObject
+
+ @see @ref overview_dnd, @ref overview_dataobject, wxDropSource,
+ wxTextDropTarget, wxFileDropTarget, wxDataFormat, wxDataObject
*/
-class wxDropTarget
+class wxDropTarget
{
public:
/**
- Constructor. @e data is the data to be associated with the drop target.
+ Constructor. @a data is the data to be associated with the drop target.
*/
- wxDropTarget(wxDataObject* data = @NULL);
+ wxDropTarget(wxDataObject* data = NULL);
/**
Destructor. Deletes the associated data object, if any.
~wxDropTarget();
/**
- This method may only be called from within OnData().
- By default, this method copies the data from the drop source to the
- wxDataObject associated with this drop target,
- calling its wxDataObject::SetData method.
+ This method may only be called from within OnData(). By default, this
+ method copies the data from the drop source to the wxDataObject
+ associated with this drop target, calling its wxDataObject::SetData()
+ method.
*/
virtual void GetData();
/**
- Called after OnDrop() returns @true. By default this
- will usually GetData() and will return the suggested
- default value @e def.
+ Called after OnDrop() returns @true. By default this will usually
+ GetData() and will return the suggested default value @a def.
*/
- virtual wxDragResult OnData(wxCoord x, wxCoord y,
- wxDragResult def);
+ virtual wxDragResult OnData(wxCoord x, wxCoord y, wxDragResult def);
/**
- Called when the mouse is being dragged over the drop target. By default,
- this calls functions return the suggested return value @e def.
-
- @param x
- The x coordinate of the mouse.
-
- @param y
- The y coordinate of the mouse.
-
- @param def
- Suggested value for return value. Determined by SHIFT or CONTROL key states.
-
- @returns Returns the desired operation or wxDragNone. This is used for
- optical feedback from the side of the drop source,
- typically in form of changing the icon.
+ Called when the mouse is being dragged over the drop target. By
+ default, this calls functions return the suggested return value @a def.
+
+ @param x
+ The x coordinate of the mouse.
+ @param y
+ The y coordinate of the mouse.
+ @param def
+ Suggested value for return value. Determined by SHIFT or CONTROL
+ key states.
+
+ @return The desired operation or wxDragNone. This is used for optical
+ feedback from the side of the drop source, typically in form
+ of changing the icon.
*/
- virtual wxDragResult OnDragOver(wxCoord x, wxCoord y,
- wxDragResult def);
+ virtual wxDragResult OnDragOver(wxCoord x, wxCoord y, wxDragResult def);
/**
- Called when the user drops a data object on the target. Return @false to veto
- the operation.
-
- @param x
- The x coordinate of the mouse.
-
- @param y
- The y coordinate of the mouse.
-
- @returns Return @true to accept the data, @false to veto the operation.
+ Called when the user drops a data object on the target. Return @false
+ to veto the operation.
+
+ @param x
+ The x coordinate of the mouse.
+ @param y
+ The y coordinate of the mouse.
+
+ @return @true to accept the data, or @false to veto the operation.
*/
virtual bool OnDrop(wxCoord x, wxCoord y);
/**
Called when the mouse enters the drop target. By default, this calls
OnDragOver().
-
- @param x
- The x coordinate of the mouse.
-
- @param y
- The y coordinate of the mouse.
-
- @param def
- Suggested default for return value. Determined by SHIFT or CONTROL key states.
-
- @returns Returns the desired operation or wxDragNone. This is used for
- optical feedback from the side of the drop source,
- typically in form of changing the icon.
+
+ @param x
+ The x coordinate of the mouse.
+ @param y
+ The y coordinate of the mouse.
+ @param def
+ Suggested default for return value. Determined by SHIFT or CONTROL
+ key states.
+
+ @return The desired operation or wxDragNone. This is used for optical
+ feedback from the side of the drop source, typically in form
+ of changing the icon.
*/
- virtual wxDragResult OnEnter(wxCoord x, wxCoord y,
- wxDragResult def);
+ virtual wxDragResult OnEnter(wxCoord x, wxCoord y, wxDragResult def);
/**
Called when the mouse leaves the drop target.
virtual void OnLeave();
/**
- Sets the data wxDataObject associated with the
- drop target and deletes any previously associated data object.
+ Sets the data wxDataObject associated with the drop target and deletes
+ any previously associated data object.
*/
void SetDataObject(wxDataObject* data);
};
+
/**
@class wxDropSource
@wxheader{dnd.h}
-
+
This class represents a source for a drag and drop operation.
-
- See @ref overview_wxdndoverview "Drag and drop overview" and @ref
- overview_wxdataobjectoverview "wxDataObject overview"
- for more information.
-
+
@library{wxcore}
@category{dnd}
-
- @seealso
- wxDropTarget, wxTextDropTarget, wxFileDropTarget
+
+ @see @ref overview_dnd, @ref overview_dataobject, wxDropTarget,
+ wxTextDropTarget, wxFileDropTarget
*/
-class wxDropSource
+class wxDropSource
{
public:
- //@{
/**
- The constructors for wxDataObject.
-
- If you use the constructor without @e data parameter you must call
- SetData() later.
-
- Note that the exact type of @e iconCopy and subsequent parameters differs
- between wxMSW and wxGTK: these are cursors under Windows but icons for GTK.
- You should use the macro wxDROP_ICON in portable
+ This constructor requires that you must call SetData() later.
+
+ Note that the exact type of @a iconCopy and subsequent parameters
+ differs between wxMSW and wxGTK: these are cursors under Windows but
+ icons for GTK. You should use the macro wxDROP_ICON() in portable
programs instead of directly using either of these types.
-
- @param win
- The window which initiates the drag and drop operation.
-
- @param iconCopy
- The icon or cursor used for feedback for copy operation.
-
- @param iconMove
- The icon or cursor used for feedback for move operation.
-
- @param iconNone
- The icon or cursor used for feedback when operation can't be done.
+
+ @param win
+ The window which initiates the drag and drop operation.
+ @param iconCopy
+ The icon or cursor used for feedback for copy operation.
+ @param iconMove
+ The icon or cursor used for feedback for move operation.
+ @param iconNone
+ The icon or cursor used for feedback when operation can't be done.
*/
- wxDropSource(wxWindow* win = @NULL,
+ wxDropSource(wxWindow* win = NULL,
+ const wxIconOrCursor& iconCopy = wxNullIconOrCursor,
+ const wxIconOrCursor& iconMove = wxNullIconOrCursor,
+ const wxIconOrCursor& iconNone = wxNullIconOrCursor);
+ /**
+ Note that the exact type of @a iconCopy and subsequent parameters
+ differs between wxMSW and wxGTK: these are cursors under Windows but
+ icons for GTK. You should use the macro wxDROP_ICON() in portable
+ programs instead of directly using either of these types.
+
+ @param win
+ The window which initiates the drag and drop operation.
+ @param iconCopy
+ The icon or cursor used for feedback for copy operation.
+ @param iconMove
+ The icon or cursor used for feedback for move operation.
+ @param iconNone
+ The icon or cursor used for feedback when operation can't be done.
+ */
+ wxDropSource(wxDataObject& data, wxWindow* win = NULL,
const wxIconOrCursor& iconCopy = wxNullIconOrCursor,
const wxIconOrCursor& iconMove = wxNullIconOrCursor,
const wxIconOrCursor& iconNone = wxNullIconOrCursor);
- wxDropSource(wxDataObject& data, wxWindow* win = @NULL,
- const wxIconOrCursor& iconCopy = wxNullIconOrCursor,
- const wxIconOrCursor& iconMove = wxNullIconOrCursor,
- const wxIconOrCursor& iconNone = wxNullIconOrCursor);
- //@}
/**
-
+ Default constructor.
*/
~wxDropSource();
/**
- Do it (call this in response to a mouse button press, for example). This starts
- the drag-and-drop operation which will terminate when the user releases the
- mouse.
-
- @param flags
- If wxDrag_AllowMove is included in the flags, data may
- be moved and not only copied (default). If wxDrag_DefaultMove is
- specified (which includes the previous flag), this is even the default
- operation
-
- @returns Returns the operation requested by the user, may be wxDragCopy,
- wxDragMove, wxDragLink, wxDragCancel or wxDragNone if
- an error occurred.
+ Starts the drag-and-drop operation which will terminate when the user
+ releases the mouse. Call this in response to a mouse button press, for
+ example.
+
+ @param flags
+ If wxDrag_AllowMove is included in the flags, data may be moved and
+ not only copied (default). If wxDrag_DefaultMove is specified
+ (which includes the previous flag), this is even the default
+ operation.
+
+ @return The operation requested by the user, may be ::wxDragCopy,
+ ::wxDragMove, ::wxDragLink, ::wxDragCancel or ::wxDragNone if
+ an error occurred.
*/
virtual wxDragResult DoDragDrop(int flags = wxDrag_CopyOnly);
/**
Returns the wxDataObject object that has been assigned previously.
*/
- wxDataObject * GetDataObject();
+ wxDataObject* GetDataObject();
/**
- Overridable: you may give some custom UI feedback during the drag and drop
- operation
- in this function. It is called on each mouse move, so your implementation must
- not be too
- slow.
-
- @param effect
- The effect to implement. One of wxDragCopy, wxDragMove, wxDragLink and
- wxDragNone.
-
- @param scrolling
- @true if the window is scrolling. MSW only.
-
- @returns Return @false if you want default feedback, or @true if you
- implement your own feedback. The return values is
- ignored under GTK.
+ You may give some custom UI feedback during the drag and drop operation
+ by overriding this function. It is called on each mouse move, so your
+ implementation must not be too slow.
+
+ @param effect
+ The effect to implement. One of ::wxDragCopy, ::wxDragMove,
+ ::wxDragLink and ::wxDragNone.
+ @param scrolling
+ @true if the window is scrolling. MSW only.
+
+ @return @false if you want default feedback, or @true if you implement
+ your own feedback. The return values is ignored under GTK.
*/
virtual bool GiveFeedback(wxDragResult effect);
/**
Set the icon to use for a certain drag result.
-
- @param res
- The drag result to set the icon for.
-
- @param cursor
- The ion to show when this drag result occurs.
+
+ @param res
+ The drag result to set the icon for.
+ @param cursor
+ The ion to show when this drag result occurs.
*/
void SetCursor(wxDragResult res, const wxCursor& cursor);
/**
- Sets the data wxDataObject associated with the
- drop source. This will not delete any previously associated data.
+ Sets the data wxDataObject associated with the drop source. This will
+ not delete any previously associated data.
*/
void SetData(wxDataObject& data);
};
+
/**
@class wxFileDropTarget
@wxheader{dnd.h}
-
- This is a @ref overview_wxdroptarget "drop target" which accepts files (dragged
- from File Manager or Explorer).
-
+
+ This is a drop target which accepts files (dragged from File Manager or
+ Explorer).
+
@library{wxcore}
@category{dnd}
-
- @seealso
- @ref overview_wxdndoverview "Drag and drop overview", wxDropSource,
- wxDropTarget, wxTextDropTarget
+
+ @see @ref overview_dnd, wxDropSource, wxDropTarget, wxTextDropTarget
*/
class wxFileDropTarget : public wxDropTarget
{
wxFileDropTarget();
/**
- See wxDropTarget::OnDrop. This function is implemented
- appropriately for files, and calls OnDropFiles().
+ See wxDropTarget::OnDrop(). This function is implemented appropriately
+ for files, and calls OnDropFiles().
*/
virtual bool OnDrop(long x, long y, const void data, size_t size);
/**
Override this function to receive dropped files.
-
- @param x
- The x coordinate of the mouse.
-
- @param y
- The y coordinate of the mouse.
-
- @param filenames
- An array of filenames.
+
+ @param x
+ The x coordinate of the mouse.
+ @param y
+ The y coordinate of the mouse.
+ @param filenames
+ An array of filenames.
+
+ Return @true to accept the data, or @false to veto the operation.
*/
virtual bool OnDropFiles(wxCoord x, wxCoord y,
const wxArrayString& filenames);
};
+
// ============================================================================
// Global functions/macros
// ============================================================================
+/** @ingroup group_funcmacro_gdi */
+//@{
+
/**
- This macro creates either a cursor (MSW) or an icon (elsewhere) with the given
- name. Under MSW, the cursor is loaded from the resource file and the icon is
- loaded from XPM file under other platforms.
-
- This macro should be used with
- @ref wxDropSource::wxdropsource "wxDropSource constructor".
+ This macro creates either a cursor (MSW) or an icon (elsewhere) with the
+ given @a name (of type <tt>const char*</tt>). Under MSW, the cursor is
+ loaded from the resource file and the icon is loaded from XPM file under
+ other platforms.
+
+ This macro should be used with wxDropSource::wxDropSource().
+
+ @return wxCursor on MSW, otherwise returns a wxIcon
+
+ @header{wx/dnd.h}
*/
-#define wxIconOrCursor wxDROP_ICON(const char * name) /* implementation is private */
+#define wxDROP_ICON(name)
+
+//@}
projects / wxWidgets.git / blobdiff