X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/7c913512a4c9f36e11e07ea707002fab1608d324..3201a1046ba71ba8e5ef2ed694fde34d12f743f3:/interface/dnd.h diff --git a/interface/dnd.h b/interface/dnd.h index 89ebeb8ce7..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 @@ -15,9 +15,7 @@ @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. - + The x coordinate of the mouse. @param y - The y coordinate of the mouse. - + The y coordinate of the mouse. @param data - The data being dropped: a wxString. + 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 { 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. - + 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. - + The x coordinate of the mouse. @param y - The y coordinate of the mouse. - + 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. + 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. - + 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. - + 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. + 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. - + The x coordinate of the mouse. @param y - The y coordinate of the mouse. - + 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. + 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 { 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. - + The window which initiates the drag and drop operation. @param iconCopy - The icon or cursor used for feedback for copy operation. - + The icon or cursor used for feedback for copy operation. @param iconMove - The icon or cursor used for feedback for move operation. - + 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. + 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); - wxDropSource(wxDataObject& data, wxWindow* win = @NULL, + /** + 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); - //@} /** - + 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. - + 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 - - @returns Returns the operation requested by the user, may be wxDragCopy, - wxDragMove, wxDragLink, wxDragCancel or wxDragNone if - an error occurred. + 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. - + 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. - + 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. + @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. - + The drag result to set the icon for. @param cursor - The ion to show when this drag result occurs. + 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. - + The x coordinate of the mouse. @param y - The y coordinate of the mouse. - + The y coordinate of the mouse. @param filenames - An array of 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 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(). - This macro should be used with - @ref wxDropSource::wxdropsource "wxDropSource constructor". + @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) + +//@}