X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/23324ae1c7938ba904770fc456d3c07764b9c5e9..3201a1046ba71ba8e5ef2ed694fde34d12f743f3:/interface/dnd.h?ds=inline diff --git a/interface/dnd.h b/interface/dnd.h index d1e5f7d886..a6d5890f2d 100644 --- a/interface/dnd.h +++ b/interface/dnd.h @@ -1,6 +1,6 @@ ///////////////////////////////////////////////////////////////////////////// // Name: dnd.h -// Purpose: documentation for wxTextDropTarget class +// Purpose: interface of wxDropSource and wx*DropTarget // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license @@ -9,15 +9,13 @@ /** @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 { @@ -28,65 +26,69 @@ public: 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. @@ -94,74 +96,67 @@ public: ~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. @@ -169,145 +164,143 @@ public: 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 { @@ -318,39 +311,49 @@ public: 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 const char*). 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) + +//@}