mac paths updated

[wxWidgets.git] / interface / dragimag.h

diff --git a/interface/dragimag.h b/interface/dragimag.h
index 63f390f55b758b9b7af5f870421879ca433edfc9..9de1317021b53f1d57d2885a5348bba6cc4d3a33 100644 (file)
--- a/interface/dragimag.h
+++ b/interface/dragimag.h
@@ -1,6 +1,6 @@
 /////////////////////////////////////////////////////////////////////////////
 // Name:        dragimag.h
 /////////////////////////////////////////////////////////////////////////////
 // Name:        dragimag.h

-// Purpose:     documentation for wxDragImage class
+// Purpose:     interface of wxDragImage

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


@@ -9,182 +9,227 @@
 /**
     @class wxDragImage
     @wxheader{dragimag.h}
 /**
     @class wxDragImage
     @wxheader{dragimag.h}

-    
-    This class is used when you wish to drag an object on the screen,
-    and a simple cursor is not enough.
-    
+
+    This class is used when you wish to drag an object on the screen, and a
+    simple cursor is not enough.
+

     On Windows, the Win32 API is used to achieve smooth dragging. On other
     On Windows, the Win32 API is used to achieve smooth dragging. On other

-    platforms,
-    wxGenericDragImage is used. Applications may also prefer to use
+    platforms, wxGenericDragImage is used. Applications may also prefer to use

     wxGenericDragImage on Windows, too.
     wxGenericDragImage on Windows, too.

-    
-    @b wxPython note: wxPython uses wxGenericDragImage on all platforms, but
-    uses the wxDragImage name.
-    
+
+    @beginWxPythonOnly
+    wxPython uses wxGenericDragImage on all platforms, but uses the wxDragImage
+    name.
+    @endWxPythonOnly
+

     To use this class, when you wish to start dragging an image, create a
     To use this class, when you wish to start dragging an image, create a

-    wxDragImage
-    object and store it somewhere you can access it as the drag progresses.
-    Call BeginDrag to start, and EndDrag to stop the drag. To move the image,
-    initially call Show and then Move. If you wish to update the screen contents
-    during the drag (for example, highlight an item as in the dragimag sample),
-    first call Hide,
-    update the screen, call Move, and then call Show.
-    
-    You can drag within one window, or you can use full-screen dragging
-    either across the whole screen, or just restricted to one area
-    of the screen to save resources. If you want the user to drag between
-    two windows, then you will need to use full-screen dragging.
-    
-    If you wish to draw the image yourself, use wxGenericDragImage and
-    override wxDragImage::DoDrawImage and 
-    wxDragImage::GetImageRect.
-    
-    Please see @c samples/dragimag for an example.
-    
+    wxDragImage object and store it somewhere you can access it as the drag
+    progresses. Call BeginDrag() to start, and EndDrag() to stop the drag. To
+    move the image, initially call Show() and then Move(). If you wish to
+    update the screen contents during the drag (for example, highlight an item
+    as in the dragimag sample), first call Hide(), update the screen, call
+    Move(), and then call Show().
+
+    You can drag within one window, or you can use full-screen dragging either
+    across the whole screen, or just restricted to one area of the screen to
+    save resources. If you want the user to drag between two windows, then you
+    will need to use full-screen dragging.
+
+    If you wish to draw the image yourself, use wxGenericDragImage and override
+    DoDrawImage() and GetImageRect().
+

     @library{wxcore}
     @library{wxcore}

-    @category{FIXME}
+    @category{dnd}
+
+    @see @ref page_samples_dragimag

 */
 class wxDragImage : public wxObject
 {
 public:
 */
 class wxDragImage : public wxObject
 {
 public:

-    //@{

     /**
     /**

-        )
-        
-        Constructs a drag image an optional cursor. This constructor is only available
-        for
-        wxGenericDragImage, and can be used when the application
-        supplies DoDrawImage() and GetImageRect().
-        
-        @param image 
-        Icon or bitmap to be used as the drag image. The bitmap can
-        have a mask.
-        
-        @param text 
-        Text used to construct a drag image.
-        
-        @param cursor 
-        Optional cursor to combine with the image.
-        
-        @param hotspot 
-        This parameter is deprecated.
-        
-        @param treeCtrl 
-        Tree control for constructing a tree drag image.
-        
-        @param listCtrl 
-        List control for constructing a list drag image.
-        
-        @param id 
-        Tree or list control item id.
+        Default constructor.

     */
     wxDragImage();
     */
     wxDragImage();

-        wxDragImage(const wxBitmap& image,
-                    const wxCursor& cursor = wxNullCursor);
-        wxDragImage(const wxIcon& image,
-                    const wxCursor& cursor = wxNullCursor);
-        wxDragImage(const wxString& text,
-                    const wxCursor& cursor = wxNullCursor);
-        wxDragImage(const wxTreeCtrl& treeCtrl, wxTreeItemId& id);
-        wxDragImage(const wxListCtrl& treeCtrl, long id);
-        wxDragImage(const wxCursor& cursor = wxNullCursor);
-    //@}
-
-    //@{
-    /**
-        Start dragging the image, using the first window to capture the mouse and the
-        second
-        to specify the bounding area. This form is equivalent to using the first form,
-        but more convenient than working out the bounding rectangle explicitly.
-        
-        You need to then call Show() 
-        and Move() to show the image on the screen.
-        
-        Call EndDrag() when the drag has finished.
-        
-        Note that this call automatically calls CaptureMouse.
-        
-        @param hotspot 
-        The location of the drag position relative to the upper-left corner
-        of the image.
-        
-        @param window 
-        The window that captures the mouse, and within which the dragging
-        is limited unless fullScreen is @true.
-        
-        @param boundingWindow 
-        In the second form of the function, specifies the
-        area within which the drag occurs.
-        
-        @param fullScreen 
-        If @true, specifies that the drag will be visible over the full
-        screen, or over as much of the screen as is specified by rect. Note that the
-        mouse will
-        still be captured in window.
-        
-        @param rect 
-        If non-@NULL, specifies the rectangle (in screen coordinates) that
-        bounds the dragging operation. Specifying this can make the operation more
-        efficient
-        by cutting down on the area under consideration, and it can also make a visual
-        difference
-        since the drag is clipped to this area.
+    /**
+        Constructs a drag image from a bitmap and optional cursor.
+
+        @param image
+            Bitmap to be used as the drag image. The bitmap can have a mask.
+        @param cursor
+            Optional cursor to combine with the image.
+        @param cursorHotspot
+            This parameter is deprecated.
+    */
+    wxDragImage(const wxBitmap& image, const wxCursor& cursor = wxNullCursor,
+                const wxPoint& cursorHotspot = wxPoint(0, 0));
+    /**
+        Constructs a drag image from an icon and optional cursor.
+
+        @param image
+            Icon to be used as the drag image.
+        @param cursor
+            Optional cursor to combine with the image.
+        @param cursorHotspot
+            This parameter is deprecated.
+
+        @beginWxPythonOnly
+        This constructor is called wxDragIcon in wxPython.
+        @endWxPythonOnly
+    */
+    wxDragImage(const wxIcon& image, const wxCursor& cursor = wxNullCursor,
+                const wxPoint& cursorHotspot = wxPoint(0, 0));
+    /**
+        Constructs a drag image from a text string and optional cursor.
+
+        @param text
+            Text used to construct a drag image.
+        @param cursor
+            Optional cursor to combine with the image.
+        @param cursorHotspot
+            This parameter is deprecated.
+
+        @beginWxPythonOnly
+        This constructor is called wxDragString in wxPython.
+        @endWxPythonOnly
+    */
+    wxDragImage(const wxString& text, const wxCursor& cursor = wxNullCursor,
+                const wxPoint& cursorHotspot = wxPoint(0, 0));
+    /**
+        Constructs a drag image from the text in the given tree control item,
+        and optional cursor.
+
+        @param treeCtrl
+            Tree control for constructing a tree drag image.
+        @param id
+            Tree control item id.
+
+        @beginWxPythonOnly
+        This constructor is called wxDragTreeItem in wxPython.
+        @endWxPythonOnly
+    */
+    wxDragImage(const wxTreeCtrl& treeCtrl, wxTreeItemId& id);
+    /**
+        Constructs a drag image from the text in the given list control item,
+        and optional cursor.
+
+        @param listCtrl
+            List control for constructing a list drag image.
+        @param id
+            List control item id.
+
+        @beginWxPythonOnly
+        This constructor is called wxDragListItem in wxPython.
+        @endWxPythonOnly
+    */
+    wxDragImage(const wxListCtrl& listCtrl, long id);
+    /**
+        Constructs a drag image an optional cursor. This constructor is only
+        available for wxGenericDragImage, and can be used when the application
+        supplies DoDrawImage() and GetImageRect().
+
+        @param cursor
+            Optional cursor to combine with the image.
+        @param cursorHotspot
+            This parameter is deprecated.
+    */
+    wxDragImage(const wxCursor& cursor = wxNullCursor,
+                const wxPoint& cursorHotspot = wxPoint(0, 0));
+
+    /**
+        Start dragging the image, in a window or full screen.
+
+        You need to then call Show() and Move() to show the image on the
+        screen. Call EndDrag() when the drag has finished.
+
+        Note that this call automatically calls CaptureMouse().
+
+        @param hotspot
+            The location of the drag position relative to the upper-left corner
+            of the image.
+        @param window
+            The window that captures the mouse, and within which the dragging
+            is limited unless fullScreen is @true.
+        @param fullScreen
+            If @true, specifies that the drag will be visible over the full
+            screen, or over as much of the screen as is specified by rect. Note
+            that the mouse will still be captured in window.
+        @param rect
+            If non-@NULL, specifies the rectangle (in screen coordinates) that
+            bounds the dragging operation. Specifying this can make the
+            operation more efficient by cutting down on the area under
+            consideration, and it can also make a visual difference since the
+            drag is clipped to this area.

     */
     bool BeginDrag(const wxPoint& hotspot, wxWindow* window,
     */
     bool BeginDrag(const wxPoint& hotspot, wxWindow* window,

-                   bool fullScreen = @false,
-                   wxRect* rect = @NULL);
-        bool BeginDrag(const wxPoint& hotspot, wxWindow* window,
-                       wxWindow* boundingWindow);
-    //@}
+                   bool fullScreen = false, wxRect* rect = NULL);
+    /**
+        Start dragging the image, using the first window to capture the mouse
+        and the second to specify the bounding area. This form is equivalent to
+        using the first form, but more convenient than working out the bounding
+        rectangle explicitly.
+
+        You need to then call Show() and Move() to show the image on the
+        screen. Call EndDrag() when the drag has finished.
+
+        Note that this call automatically calls CaptureMouse().
+
+        @param hotspot
+            The location of the drag position relative to the upper-left corner
+            of the image.
+        @param window
+            The window that captures the mouse, and within which the dragging
+            is limited.
+        @param boundingWindow
+            Specifies the area within which the drag occurs.
+    */
+    bool BeginDrag(const wxPoint& hotspot, wxWindow* window,
+                   wxWindow* boundingWindow);

 
     /**
         Draws the image on the device context with top-left corner at the given
         position.
 
     /**
         Draws the image on the device context with top-left corner at the given
         position.

-        
-        This function is only available with wxGenericDragImage, to allow applications
-        to
-        draw their own image instead of using an actual bitmap. If you override this
-        function,
-        you must also override GetImageRect().
+
+        This function is only available with wxGenericDragImage, to allow
+        applications to draw their own image instead of using an actual bitmap.
+        If you override this function, you must also override GetImageRect().

     */
     virtual bool DoDrawImage(wxDC& dc, const wxPoint& pos);
 
     /**
         Call this when the drag has finished.
     */
     virtual bool DoDrawImage(wxDC& dc, const wxPoint& pos);
 
     /**
         Call this when the drag has finished.

-        
-        Note that this call automatically calls ReleaseMouse.
+
+        @note This function automatically releases mouse capture.

     */
     bool EndDrag();
 
     /**
     */
     bool EndDrag();
 
     /**

-        Returns the rectangle enclosing the image, assuming that the image is drawn
-        with its
-        top-left corner at the given point.
-        
-        This function is available in wxGenericDragImage only, and may be overridden
-        (together with 
-        wxDragImage::DoDrawImage) to provide a virtual drawing capability.
+        Returns the rectangle enclosing the image, assuming that the image is
+        drawn with its top-left corner at the given point.
+
+        This function is available in wxGenericDragImage only, and may be
+        overridden (together with DoDrawImage()) to provide a virtual drawing
+        capability.

     */
     */

-    virtual wxRect GetImageRect(const wxPoint& pos);
+    virtual wxRect GetImageRect(const wxPoint& pos) const;

 
     /**
         Hides the image. You may wish to call this before updating the window
 
     /**
         Hides the image. You may wish to call this before updating the window

-        contents (perhaps highlighting an item). Then call Move() 
-        and Show().
+        contents (perhaps highlighting an item). Then call Move() and Show().

     */
     bool Hide();
 
     /**
     */
     bool Hide();
 
     /**

-        Call this to move the image to a new position. The image will only be shown if 
-        Show() has been called previously (for example
-        at the start of the drag).
-        
-        @e pt is the position in client coordinates (relative to the window specified
-        in BeginDrag).
-        
-        You can move the image either when the image is hidden or shown, but in general
-        dragging
-        will be smoother if you move the image when it is shown.
+        Call this to move the image to a new position. The image will only be
+        shown if Show() has been called previously (for example at the start of
+        the drag).
+
+        @param pt
+            The position in client coordinates (relative to the window
+            specified in BeginDrag()).
+
+        You can move the image either when the image is hidden or shown, but in
+        general dragging will be smoother if you move the image when it is
+        shown.

     */
     bool Move(const wxPoint& pt);
 
     */
     bool Move(const wxPoint& pt);
 


@@ -194,25 +239,24 @@ public:
     bool Show();
 
     /**
     bool Show();
 
     /**

-        Override this if you wish to draw the window contents to the backing bitmap
-        yourself. This can be desirable if you wish to avoid flicker by not having to
-        redraw the updated window itself just before dragging, which can cause a
-        flicker just
-        as the drag starts. Instead, paint the drag image's backing bitmap to show the
-        appropriate
-        graphic @e minus the objects to be dragged, and leave the window itself to be
-        updated
-        by the drag image. This can provide eerily smooth, flicker-free drag behaviour.
-        
-        The default implementation copies the window contents to the backing bitmap. A
-        new
-        implementation will normally copy information from another source, such as from
-        its
-        own backing bitmap if it has one, or directly from internal data structures.
-        
+        Override this if you wish to draw the window contents to the backing
+        bitmap yourself. This can be desirable if you wish to avoid flicker by
+        not having to redraw the updated window itself just before dragging,
+        which can cause a flicker just as the drag starts. Instead, paint the
+        drag image's backing bitmap to show the appropriate graphic @e minus
+        the objects to be dragged, and leave the window itself to be updated by
+        the drag image. This can provide eerily smooth, flicker-free drag
+        behaviour.
+
+        The default implementation copies the window contents to the backing
+        bitmap. A new implementation will normally copy information from
+        another source, such as from its own backing bitmap if it has one, or
+        directly from internal data structures.
+

         This function is available in wxGenericDragImage only.
     */
     bool UpdateBackingFromWindow(wxDC& windowDC, wxMemoryDC& destDC,
                                  const wxRect& sourceRect,
         This function is available in wxGenericDragImage only.
     */
     bool UpdateBackingFromWindow(wxDC& windowDC, wxMemoryDC& destDC,
                                  const wxRect& sourceRect,

-                                 const wxRect& destRect);
+                                 const wxRect& destRect) const;

 };
 };

+