mac paths updated

[wxWidgets.git] / interface / dnd.h

diff --git a/interface/dnd.h b/interface/dnd.h
index d1e5f7d8867d7ffe67a0b83b8aca666a453b30f9..a6d5890f2d715e8cd1c272c9025713be5e5df6e7 100644 (file)
--- a/interface/dnd.h
+++ b/interface/dnd.h
@@ -1,6 +1,6 @@
 /////////////////////////////////////////////////////////////////////////////
 // Name:        dnd.h
 /////////////////////////////////////////////////////////////////////////////
 // Name:        dnd.h

-// Purpose:     documentation for wxTextDropTarget class
+// Purpose:     interface of wxDropSource and wx*DropTarget

 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license


@@ -9,15 +9,13 @@
 /**
     @class wxTextDropTarget
     @wxheader{dnd.h}
 /**
     @class wxTextDropTarget
     @wxheader{dnd.h}

-    
+

     A predefined drop target for dealing with text data.
     A predefined drop target for dealing with text data.

-    
+

     @library{wxcore}
     @category{dnd}
     @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
 {
 */
 class wxTextDropTarget : public wxDropTarget
 {


@@ -28,65 +26,69 @@ public:
     wxTextDropTarget();
 
     /**
     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.
     */
     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}
 /**
     @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}
     @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:
     /**
 {
 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.
 
     /**
         Destructor. Deletes the associated data object, if any.


@@ -94,74 +96,67 @@ public:
     ~wxDropTarget();
 
     /**
     ~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();
 
     /**
     */
     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().
     */
     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.
 
     /**
         Called when the mouse leaves the drop target.


@@ -169,145 +164,143 @@ public:
     virtual void OnLeave();
 
     /**
     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);
 };
 
 
     */
     void SetDataObject(wxDataObject* data);
 };
 
 

+

 /**
     @class wxDropSource
     @wxheader{dnd.h}
 /**
     @class wxDropSource
     @wxheader{dnd.h}

-    
+

     This class represents a source for a drag and drop operation.
     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}
     @library{wxcore}
     @category{dnd}

-    
-    @seealso
-    wxDropTarget, wxTextDropTarget, wxFileDropTarget
+
+    @see @ref overview_dnd, @ref overview_dataobject, wxDropTarget,
+         wxTextDropTarget, wxFileDropTarget

 */
 */

-class wxDropSource 
+class wxDropSource

 {
 public:
 {
 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.
         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);
                  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();
 
     /**
     */
     ~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.
     */
     */
     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.
     */
     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);
 
     /**
     */
     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);
 };
 
 
     */
     void SetData(wxDataObject& data);
 };
 
 

+

 /**
     @class wxFileDropTarget
     @wxheader{dnd.h}
 /**
     @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}
     @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
 {
 */
 class wxFileDropTarget : public wxDropTarget
 {


@@ -318,39 +311,49 @@ public:
     wxFileDropTarget();
 
     /**
     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.
     */
     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);
 };
 
 
     */
     virtual bool OnDropFiles(wxCoord x, wxCoord y,
                              const wxArrayString& filenames);
 };
 
 

+

 // ============================================================================
 // Global functions/macros
 // ============================================================================
 
 // ============================================================================
 // 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 <tt>const char*</tt>). 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)
+
+//@}