synchronize GTK2 minimum version in docs

[wxWidgets.git] / interface / wx / dnd.h

diff --git a/interface/wx/dnd.h b/interface/wx/dnd.h
index 79466fab801a038801553719f8248002d0d255af..719ab9943354fda25dc1b7800c075cf7d8594dbe 100644 (file)
--- a/interface/wx/dnd.h
+++ b/interface/wx/dnd.h
@@ -3,50 +3,19 @@
 // Purpose:     interface of wxDropSource and wx*DropTarget
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     interface of wxDropSource and wx*DropTarget
 // Author:      wxWidgets team
 // RCS-ID:      $Id$

-// Licence:     wxWindows license
+// Licence:     wxWindows licence

 /////////////////////////////////////////////////////////////////////////////
 
 /**
 /////////////////////////////////////////////////////////////////////////////
 
 /**

-    @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
+    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.
 */
 /**
     Result returned from a wxDropSource::DoDragDrop() call.
 */


@@ -60,6 +29,8 @@ enum wxDragResult
     wxDragCancel    ///< The operation was cancelled by user (not an error).
 };
 
     wxDragCancel    ///< The operation was cancelled by user (not an error).
 };
 

+
+

 /**
     @class wxDropTarget
 
 /**
     @class wxDropTarget
 


@@ -99,23 +70,23 @@ public:
         associated with this drop target, calling its wxDataObject::SetData()
         method.
     */
         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
 
     /**
         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
 
     /**
         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 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.
 
             Suggested value for return value. Determined by SHIFT or CONTROL
             key states.
 


@@ -123,7 +94,7 @@ public:
                  feedback from the side of the drop source, typically in form
                  of changing the icon.
     */
                  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
 
     /**
         Called when the user drops a data object on the target. Return @false


@@ -146,7 +117,7 @@ public:
             The x coordinate of the mouse.
         @param y
             The y coordinate of the mouse.
             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.
 
             Suggested default for return value. Determined by SHIFT or CONTROL
             key states.
 


@@ -154,7 +125,7 @@ public:
                  feedback from the side of the drop source, typically in form
                  of changing the icon.
     */
                  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.
 
     /**
         Called when the mouse leaves the drop target.


@@ -166,6 +137,22 @@ public:
         any previously associated data object.
     */
     void SetDataObject(wxDataObject* data);
         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();
+

 };
 
 
 };
 
 


@@ -187,11 +174,13 @@ public:
     /**
         This constructor requires that you must call SetData() later.
 
     /**
         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.
 
         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
         @param win
             The window which initiates the drag and drop operation.
         @param iconCopy


@@ -202,15 +191,22 @@ public:
             The icon or cursor used for feedback when operation can't be done.
     */
     wxDropSource(wxWindow* win = NULL,
             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.
 
         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
         @param win
             The window which initiates the drag and drop operation.
         @param iconCopy


@@ -221,14 +217,55 @@ public:
             The icon or cursor used for feedback when operation can't be done.
     */
     wxDropSource(wxDataObject& data, wxWindow* win = NULL,
             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);

 
     /**
 
     /**

-        Default constructor.
+        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.

     */
     */

-    virtual ~wxDropSource();
+    wxDropSource(wxWindow* win = NULL,
+                 const wxIcon& iconCopy = wxNullIcon,
+                 const wxIcon& iconMove = wxNullIcon,
+                 const wxIcon& iconNone = wxNullIcon);
+
+    /**
+        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(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
 
     /**
         Starts the drag-and-drop operation which will terminate when the user


@@ -236,10 +273,11 @@ public:
         example.
 
         @param flags
         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
 
         @return The operation requested by the user, may be ::wxDragCopy,
                  ::wxDragMove, ::wxDragLink, ::wxDragCancel or ::wxDragNone if


@@ -260,8 +298,6 @@ public:
         @param effect
             The effect to implement. One of ::wxDragCopy, ::wxDragMove,
             ::wxDragLink and ::wxDragNone.
         @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 value is ignored under GTK.
 
         @return @false if you want default feedback, or @true if you implement
                 your own feedback. The return value is ignored under GTK.


@@ -274,10 +310,24 @@ public:
         @param res
             The drag result to set the icon for.
         @param cursor
         @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);
 
     */
     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.
     /**
         Sets the data wxDataObject associated with the drop source. This will
         not delete any previously associated data.


@@ -287,6 +337,46 @@ 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
 
 /**
     @class wxFileDropTarget
 


@@ -310,7 +400,7 @@ public:
         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);
+    virtual bool OnDrop(wxCoord x, wxCoord y);

 
     /**
         Override this function to receive dropped files.
 
     /**
         Override this function to receive dropped files.


@@ -325,7 +415,7 @@ public:
         Return @true to accept the data, or @false to veto the operation.
     */
     virtual bool OnDropFiles(wxCoord x, wxCoord y,
         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;

 };
 
 
 };
 
 


@@ -334,7 +424,7 @@ public:
 // Global functions/macros
 // ============================================================================
 
 // Global functions/macros
 // ============================================================================
 

-/** @ingroup group_funcmacro_gdi */
+/** @addtogroup group_funcmacro_gdi */

 //@{
 
 /**
 //@{
 
 /**


@@ -351,5 +441,11 @@ public:
 */
 #define wxDROP_ICON(name)
 
 */
 #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);
+

 //@}
 
 //@}