X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/7c913512a4c9f36e11e07ea707002fab1608d324..e333075415c35d2e869ea585fa41f01a2c938897:/interface/dnd.h diff --git a/interface/dnd.h b/interface/dnd.h index 89ebeb8ce7..e93ddeef7e 100644 --- a/interface/dnd.h +++ b/interface/dnd.h @@ -1,6 +1,6 @@ ///////////////////////////////////////////////////////////////////////////// // Name: dnd.h -// Purpose: documentation for wxTextDropTarget class +// Purpose: interface of wxTextDropTarget // 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_wxdndoverview, wxDropSource, wxDropTarget, wxFileDropTarget */ class wxTextDropTarget : public wxDropTarget { @@ -35,21 +33,20 @@ public: /** 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. */ virtual bool OnDropText(wxCoord x, wxCoord y, const wxString& data); }; + /** @class wxDropTarget @wxheader{dnd.h} @@ -70,23 +67,22 @@ public: 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" + See @ref overview_wxdndoverview and @ref overview_wxdataobjectoverview for more information. @library{wxcore} @category{dnd} - @seealso - wxDropSource, wxTextDropTarget, wxFileDropTarget, wxDataFormat, wxDataObject + @see 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. @@ -112,19 +108,17 @@ public: /** 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. - + 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. - + 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. + 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); @@ -132,13 +126,12 @@ public: /** 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. - + The y coordinate of the mouse. + @returns Return @true to accept the data, @false to veto the operation. */ virtual bool OnDrop(wxCoord x, wxCoord y); @@ -146,19 +139,18 @@ public: /** 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. - + 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. + 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); @@ -176,21 +168,20 @@ public: }; + /** @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" + See @ref overview_wxdndoverview and @ref overview_wxdataobjectoverview for more information. @library{wxcore} @category{dnd} - @seealso - wxDropTarget, wxTextDropTarget, wxFileDropTarget + @see wxDropTarget, wxTextDropTarget, wxFileDropTarget */ class wxDropSource { @@ -198,39 +189,34 @@ public: //@{ /** The constructors for wxDataObject. - - If you use the constructor without @e data parameter you must call + If you use the constructor without @a data parameter you must call SetData() later. - - Note that the exact type of @e iconCopy and subsequent parameters differs + 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 + 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, + wxDropSource(wxDataObject& data, wxWindow* win = NULL, const wxIconOrCursor& iconCopy = wxNullIconOrCursor, const wxIconOrCursor& iconMove = wxNullIconOrCursor, const wxIconOrCursor& iconNone = wxNullIconOrCursor); //@} /** - + */ ~wxDropSource(); @@ -238,23 +224,23 @@ public: 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 - + 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. + 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 @@ -262,28 +248,26 @@ public: 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 + The effect to implement. One of wxDragCopy, wxDragMove, wxDragLink and wxDragNone. - @param scrolling - @true if the window is scrolling. MSW only. - + @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. + 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); @@ -295,6 +279,7 @@ public: }; + /** @class wxFileDropTarget @wxheader{dnd.h} @@ -305,9 +290,7 @@ public: @library{wxcore} @category{dnd} - @seealso - @ref overview_wxdndoverview "Drag and drop overview", wxDropSource, - wxDropTarget, wxTextDropTarget + @see @ref overview_wxdndoverview, wxDropSource, wxDropTarget, wxTextDropTarget */ class wxFileDropTarget : public wxDropTarget { @@ -325,32 +308,40 @@ public: /** 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. */ 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 - @ref wxDropSource::wxdropsource "wxDropSource constructor". + This macro should be used with wxDropSource::wxDropSource(). + + @returns 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) + +//@}