X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/ae3c17b4013e80b99976c750c19fca47729517f6..9e9574fe45b176ee74bba8fad7574cf9906145d1:/interface/wx/dnd.h?ds=sidebyside diff --git a/interface/wx/dnd.h b/interface/wx/dnd.h index a6d5890f2d..f117116871 100644 --- a/interface/wx/dnd.h +++ b/interface/wx/dnd.h @@ -2,52 +2,19 @@ // Name: dnd.h // Purpose: interface of wxDropSource and wx*DropTarget // Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// /** - @class wxTextDropTarget - @wxheader{dnd.h} - - A predefined drop target for dealing with text data. - - @library{wxcore} - @category{dnd} - - @see @ref overview_dnd, wxDropSource, wxDropTarget, wxFileDropTarget -*/ -class wxTextDropTarget : public wxDropTarget + Possible flags for drag and drop operations. + */ +enum { -public: - /** - Constructor. - */ - wxTextDropTarget(); - - /** - 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. - - Return @true to accept the data, or @false to veto the operation. - */ - virtual bool OnDropText(wxCoord x, wxCoord y, const wxString& data); + wxDrag_CopyOnly = 0, ///< Allow only copying. + wxDrag_AllowMove = 1, ///< Allow moving too (copying is always allowed). + wxDrag_DefaultMove = 3 ///< Allow moving and make it default operation. }; - - /** Result returned from a wxDropSource::DoDragDrop() call. */ @@ -61,9 +28,10 @@ enum wxDragResult 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 @@ -93,7 +61,7 @@ public: /** Destructor. Deletes the associated data object, if any. */ - ~wxDropTarget(); + virtual ~wxDropTarget(); /** This method may only be called from within OnData(). By default, this @@ -101,23 +69,23 @@ public: associated with this drop target, calling its wxDataObject::SetData() method. */ - virtual void GetData(); + virtual bool GetData(); /** Called after OnDrop() returns @true. By default this will usually - GetData() and will return the suggested default value @a def. + GetData() and will return the suggested default value @a defResult. */ - virtual wxDragResult OnData(wxCoord x, wxCoord y, wxDragResult def); + virtual wxDragResult OnData(wxCoord x, wxCoord y, wxDragResult defResult) = 0; /** Called when the mouse is being dragged over the drop target. By - default, this calls functions return the suggested return value @a def. + default, this calls functions return the suggested return value @a defResult. @param x The x coordinate of the mouse. @param y The y coordinate of the mouse. - @param def + @param defResult Suggested value for return value. Determined by SHIFT or CONTROL key states. @@ -125,7 +93,7 @@ public: 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 defResult); /** Called when the user drops a data object on the target. Return @false @@ -148,7 +116,7 @@ public: The x coordinate of the mouse. @param y The y coordinate of the mouse. - @param def + @param defResult Suggested default for return value. Determined by SHIFT or CONTROL key states. @@ -156,25 +124,45 @@ public: 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 defResult); /** Called when the mouse leaves the drop target. */ virtual void OnLeave(); + /** + Returns the data wxDataObject associated with the drop target + */ + wxDataObject *GetDataObject() const; + /** Sets the data wxDataObject associated with the drop target and deletes any previously associated data object. */ void SetDataObject(wxDataObject* data); + + + /** + Sets the default action for drag and drop. Use wxDragMove or + wxDragCopy to set deafult action to move or copy and use wxDragNone + (default) to set default action specified by initialization of draging + (see wxDropSource::DoDragDrop()) + */ + void SetDefaultAction(wxDragResult action); + + /** + Returns default action for drag and drop or wxDragNone if this not + specified. + */ + wxDragResult GetDefaultAction(); + }; /** @class wxDropSource - @wxheader{dnd.h} This class represents a source for a drag and drop operation. @@ -190,11 +178,13 @@ public: /** 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 + Note that the type of @a iconCopy and subsequent parameters + differs between different ports: these are cursors under Windows and OS + X but icons for GTK. You should use the macro wxDROP_ICON() in portable programs instead of directly using either of these types. + @onlyfor{wxmsw,wxosx} + @param win The window which initiates the drag and drop operation. @param iconCopy @@ -205,15 +195,22 @@ public: The icon or cursor used for feedback when operation can't be done. */ wxDropSource(wxWindow* win = NULL, - const wxIconOrCursor& iconCopy = wxNullIconOrCursor, - const wxIconOrCursor& iconMove = wxNullIconOrCursor, - const wxIconOrCursor& iconNone = wxNullIconOrCursor); + const wxCursor& iconCopy = wxNullCursor, + const wxCursor& iconMove = wxNullCursor, + const wxCursor& iconNone = wxNullCursor); + /** - 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 + The constructor taking a wxDataObject. + + Note that the type of @a iconCopy and subsequent parameters + differs between different ports: these are cursors under Windows and OS + X but icons for GTK. You should use the macro wxDROP_ICON() in portable programs instead of directly using either of these types. + @onlyfor{wxmsw,wxosx} + + @param data + The data associated with the drop source. @param win The window which initiates the drag and drop operation. @param iconCopy @@ -224,14 +221,55 @@ public: 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); + const wxCursor& iconCopy = wxNullCursor, + const wxCursor& iconMove = wxNullCursor, + const wxCursor& iconNone = wxNullCursor); + + /** + This constructor requires that you must call SetData() later. + + This is the wxGTK-specific version of the constructor taking wxIcon + instead of wxCursor as the other ports. + + @onlyfor{wxgtk} + + @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, + const wxIcon& iconCopy = wxNullIcon, + const wxIcon& iconMove = wxNullIcon, + const wxIcon& iconNone = wxNullIcon); /** - Default constructor. + The constructor taking a wxDataObject. + + This is the wxGTK-specific version of the constructor taking wxIcon + instead of wxCursor as the other ports. + + @onlyfor{wxgtk} + + @param data + The data associated with the drop source. + @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(); + wxDropSource(wxDataObject& data, wxWindow* win = NULL, + const wxIcon& iconCopy = wxNullIcon, + const wxIcon& iconMove = wxNullIcon, + const wxIcon& iconNone = wxNullIcon); /** Starts the drag-and-drop operation which will terminate when the user @@ -239,10 +277,11 @@ public: 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. + If ::wxDrag_AllowMove is included in the flags, data may be moved + and not only copied as is the case for the default + ::wxDrag_CopyOnly. If ::wxDrag_DefaultMove is specified + (which includes the previous flag), moving is not only possible but + becomes the default operation. @return The operation requested by the user, may be ::wxDragCopy, ::wxDragMove, ::wxDragLink, ::wxDragCancel or ::wxDragNone if @@ -263,11 +302,9 @@ public: @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. + your own feedback. The return value is ignored under GTK. */ virtual bool GiveFeedback(wxDragResult effect); @@ -277,10 +314,24 @@ public: @param res The drag result to set the icon for. @param cursor - The ion to show when this drag result occurs. + The icon to show when this drag result occurs. + + @onlyfor{wxmsw,wxosx} */ void SetCursor(wxDragResult res, const wxCursor& cursor); + /** + Set the icon to use for a certain drag result. + + @param res + The drag result to set the icon for. + @param icon + The icon to show when this drag result occurs. + + @onlyfor{wxgtk} + */ + void SetIcon(wxDragResult res, const wxIcon& icon); + /** Sets the data wxDataObject associated with the drop source. This will not delete any previously associated data. @@ -290,9 +341,48 @@ public: +/** + @class wxTextDropTarget + + A predefined drop target for dealing with text data. + + @library{wxcore} + @category{dnd} + + @see @ref overview_dnd, wxDropSource, wxDropTarget, wxFileDropTarget +*/ +class wxTextDropTarget : public wxDropTarget +{ +public: + /** + Constructor. + */ + wxTextDropTarget(); + + /** + See wxDropTarget::OnDrop(). This function is implemented appropriately + for text, and calls OnDropText(). + */ + virtual bool OnDrop(wxCoord x, wxCoord y); + + /** + 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. + + Return @true to accept the data, or @false to veto the operation. + */ + virtual bool OnDropText(wxCoord x, wxCoord y, const wxString& data) = 0; +}; + + /** @class wxFileDropTarget - @wxheader{dnd.h} This is a drop target which accepts files (dragged from File Manager or Explorer). @@ -314,7 +404,7 @@ public: 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); + virtual bool OnDrop(wxCoord x, wxCoord y); /** Override this function to receive dropped files. @@ -329,7 +419,7 @@ public: Return @true to accept the data, or @false to veto the operation. */ virtual bool OnDropFiles(wxCoord x, wxCoord y, - const wxArrayString& filenames); + const wxArrayString& filenames) = 0; }; @@ -338,7 +428,7 @@ public: // Global functions/macros // ============================================================================ -/** @ingroup group_funcmacro_gdi */ +/** @addtogroup group_funcmacro_gdi */ //@{ /** @@ -355,5 +445,11 @@ public: */ #define wxDROP_ICON(name) +/** + Returns true if res indicates that something was done during a DnD operation, + i.e. is neither error nor none nor cancel. +*/ +bool wxIsDragResultOk(wxDragResult res); + //@}