Avoid warning about unused variable in wxGetUTCTimeMillis() in wxMSW.

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

diff --git a/interface/wx/scrolwin.h b/interface/wx/scrolwin.h
index b73f8464b4494f1bffc2dbc9acdcc5c1d842f4be..8a9b9093098712ab03ecaa5a2b640fe028b803c2 100644 (file)
--- a/interface/wx/scrolwin.h
+++ b/interface/wx/scrolwin.h
@@ -3,9 +3,19 @@
 // Purpose:     interface of wxScrolled template
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     interface of wxScrolled template
 // Author:      wxWidgets team
 // RCS-ID:      $Id$

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

 /////////////////////////////////////////////////////////////////////////////
 
 /////////////////////////////////////////////////////////////////////////////
 

+/**
+    Possible values for the second argument of wxScrolled::ShowScrollbars().
+ */
+enum wxScrollbarVisibility
+{
+    wxSHOW_SB_NEVER = -1,   ///< Never show the scrollbar at all.
+    wxSHOW_SB_DEFAULT,      ///< Show scrollbar only if it is needed.
+    wxSHOW_SB_ALWAYS        ///< Always show scrollbar, even if not needed.
+};
+

 /**
 
     The wxScrolled class manages scrolling for its client area, transforming
 /**
 
     The wxScrolled class manages scrolling for its client area, transforming


@@ -22,7 +32,7 @@
 
     - ::wxScrolledCanvas, aka wxScrolled<wxWindow>, derives from wxWindow and
       so doesn't handle children specially. This is suitable e.g. for
 
     - ::wxScrolledCanvas, aka wxScrolled<wxWindow>, derives from wxWindow and
       so doesn't handle children specially. This is suitable e.g. for

-      implementating scrollable controls such as tree or list controls.
+      implementing scrollable controls such as tree or list controls.

 
     Starting from version 2.4 of wxWidgets, there are several ways to use a
     ::wxScrolledWindow (and now wxScrolled). In particular, there are
 
     Starting from version 2.4 of wxWidgets, there are several ways to use a
     ::wxScrolledWindow (and now wxScrolled). In particular, there are


@@ -58,6 +68,9 @@
     wxWindow::SetVirtualSizeHints() with wxWindow::SetMinVirtualSize() or
     similar and remove it entirely in future.
 
     wxWindow::SetVirtualSizeHints() with wxWindow::SetMinVirtualSize() or
     similar and remove it entirely in future.
 

+    @todo review docs for this class replacing SetVirtualSizeHints() with
+          SetMinClientSize().
+

     As with all windows, an application can draw onto a wxScrolled using a
     @ref overview_dc "device context".
 
     As with all windows, an application can draw onto a wxScrolled using a
     @ref overview_dc "device context".
 


@@ -90,6 +103,34 @@
            Uses a backing pixmap to speed refreshes. Motif only.
     @endStyleTable
 
            Uses a backing pixmap to speed refreshes. Motif only.
     @endStyleTable
 

+
+    @beginEventEmissionTable{wxScrollWinEvent}
+    @event{EVT_SCROLLWIN(func)}
+        Process all scroll events.
+    @event{EVT_SCROLLWIN_TOP(func)}
+        Process @c wxEVT_SCROLLWIN_TOP scroll-to-top events.
+    @event{EVT_SCROLLWIN_BOTTOM(func)}
+        Process @c wxEVT_SCROLLWIN_BOTTOM scroll-to-bottom events.
+    @event{EVT_SCROLLWIN_LINEUP(func)}
+        Process @c wxEVT_SCROLLWIN_LINEUP line up events.
+    @event{EVT_SCROLLWIN_LINEDOWN(func)}
+        Process @c wxEVT_SCROLLWIN_LINEDOWN line down events.
+    @event{EVT_SCROLLWIN_PAGEUP(func)}
+        Process @c wxEVT_SCROLLWIN_PAGEUP page up events.
+    @event{EVT_SCROLLWIN_PAGEDOWN(func)}
+        Process @c wxEVT_SCROLLWIN_PAGEDOWN page down events.
+    @event{EVT_SCROLLWIN_THUMBTRACK(func)}
+        Process @c wxEVT_SCROLLWIN_THUMBTRACK thumbtrack events
+        (frequent events sent as the user drags the thumbtrack).
+    @event{EVT_SCROLLWIN_THUMBRELEASE(func)}
+        Process @c wxEVT_SCROLLWIN_THUMBRELEASE thumb release events.
+    @endEventTable
+
+    @note
+        Don't confuse wxScrollWinEvents generated by this class with
+        wxScrollEvent objects generated by wxScrollBar and wxSlider.
+
+

     @remarks
     Use wxScrolled for applications where the user scrolls by a fixed amount,
     and where a 'page' can be interpreted to be the current visible portion of
     @remarks
     Use wxScrolled for applications where the user scrolls by a fixed amount,
     and where a 'page' can be interpreted to be the current visible portion of


@@ -122,10 +163,10 @@ public:
         @param id
             Window identifier. The value @c wxID_ANY indicates a default value.
         @param pos
         @param id
             Window identifier. The value @c wxID_ANY indicates a default value.
         @param pos

-            Window position. If a position of @c wxDefaultPosition is specified
+            Window position. If a position of ::wxDefaultPosition is specified

             then a default position is chosen.
         @param size
             then a default position is chosen.
         @param size

-            Window size. If a size of @c wxDefaultSize is specified then the
+            Window size. If a size of ::wxDefaultSize is specified then the

             window is sized appropriately.
         @param style
             Window style. See wxScrolled.
             window is sized appropriately.
         @param style
             Window style. See wxScrolled.


@@ -150,6 +191,11 @@ public:
         10) and so the call to CalcScrolledPosition(0, 10, xx, yy) will return
         0 in yy.
 
         10) and so the call to CalcScrolledPosition(0, 10, xx, yy) will return
         0 in yy.
 

+        @beginWxPerlOnly
+        In wxPerl this method takes two parameters and returns a
+        2-element list (xx, yy).
+        @endWxPerlOnly
+

         @see CalcUnscrolledPosition()
     */
     void CalcScrolledPosition(int x, int y, int* xx, int* yy) const;
         @see CalcUnscrolledPosition()
     */
     void CalcScrolledPosition(int x, int y, int* xx, int* yy) const;


@@ -161,6 +207,11 @@ public:
         10) and so the call to CalcUnscrolledPosition(0, 0, xx, yy) will return
         10 in yy.
 
         10) and so the call to CalcUnscrolledPosition(0, 0, xx, yy) will return
         10 in yy.
 

+        @beginWxPerlOnly
+        In wxPerl this method takes two parameters and returns a
+        2-element list (xx, yy).
+        @endWxPerlOnly
+

         @see CalcScrolledPosition()
     */
     void CalcUnscrolledPosition(int x, int y, int* xx, int* yy) const;
         @see CalcScrolledPosition()
     */
     void CalcUnscrolledPosition(int x, int y, int* xx, int* yy) const;


@@ -176,16 +227,32 @@ public:
                 long style = wxHSCROLL | wxVSCROLL,
                 const wxString& name = "scrolledWindow");
 
                 long style = wxHSCROLL | wxVSCROLL,
                 const wxString& name = "scrolledWindow");
 

+    /**
+        Disable use of keyboard keys for scrolling.
+
+        By default cursor movement keys (including Home, End, Page Up and Down)
+        are used to scroll the window appropriately. If the derived class uses
+        these keys for something else, e.g. changing the currently selected
+        item, this function can be used to disable this behaviour as it's not
+        only not necessary then but can actually be actively harmful if another
+        object forwards a keyboard event corresponding to one of the above keys
+        to us using ProcessWindowEvent() because the event will always be
+        processed which can be undesirable.
+
+        @since 2.9.1
+    */
+    void DisableKeyboardScrolling();
+

     /**
         Call this function to prepare the device context for drawing a scrolled
         image.
 
         It sets the device origin according to the current scroll position.
     /**
         Call this function to prepare the device context for drawing a scrolled
         image.
 
         It sets the device origin according to the current scroll position.

-        DoPrepareDC() is called automatically within the default OnPaint()
-        event handler, so your OnDraw() override will be passed a
+        DoPrepareDC() is called automatically within the default @c wxEVT_PAINT
+        event handler, so your OnDraw() override will be passed an already

         'pre-scrolled' device context. However, if you wish to draw from
         'pre-scrolled' device context. However, if you wish to draw from

-        outside of OnDraw() (via OnPaint()), or you wish to implement OnPaint()
-        yourself, you must call this function yourself.
+        outside of OnDraw() (e.g. from your own @c wxEVT_PAINT handler), you
+        must call this function yourself.

 
         For example:
         @code
 
         For example:
         @code


@@ -206,6 +273,12 @@ public:
         }
         @endcode
 
         }
         @endcode
 

+        Notice that the function sets the origin by moving it relatively to the
+        current origin position, so you shouldn't change the origin before
+        calling DoPrepareDC() or, if you do, reset it to (0, 0) later. If you
+        call DoPrepareDC() immediately after device context creation, as in the
+        example above, this problem doesn't arise, of course, so it is
+        customary to do it like this.

     */
     void DoPrepareDC(wxDC& dc);
 
     */
     void DoPrepareDC(wxDC& dc);
 


@@ -228,6 +301,32 @@ public:
     */
     void EnableScrolling(bool xScrolling, bool yScrolling);
 
     */
     void EnableScrolling(bool xScrolling, bool yScrolling);
 

+    /**
+        Set the scrollbar visibility.
+
+        By default the scrollbar in the corresponding direction is only shown
+        if it is needed, i.e. if the virtual size of the scrolled window in
+        this direction is greater than the current physical window size. Using
+        this function the scrollbar visibility can be changed to be:
+            - wxSHOW_SB_ALWAYS: To always show the scrollbar, even if it is
+                not needed currently (wxALWAYS_SHOW_SB style can be used during
+                the window creation to achieve the same effect but it applies
+                in both directions).
+            - wxSHOW_SB_NEVER: To never show the scrollbar at all. In this case
+                the program should presumably provide some other way for the
+                user to scroll the window.
+            - wxSHOW_SB_DEFAULT: To restore the default behaviour described
+                above.
+
+        @param horz
+            The desired visibility for the horizontal scrollbar.
+        @param vert
+            The desired visibility for the vertical scrollbar.
+
+        @since 2.9.0
+     */
+    void ShowScrollbars(wxScrollbarVisibility horz, wxScrollbarVisibility vert);
+

     /**
         Get the number of pixels per scroll unit (line), in each direction, as
         set by SetScrollbars(). A value of zero indicates no scrolling in that
     /**
         Get the number of pixels per scroll unit (line), in each direction, as
         set by SetScrollbars(). A value of zero indicates no scrolling in that


@@ -238,6 +337,11 @@ public:
         @param yUnit
             Receives the number of pixels per vertical unit.
 
         @param yUnit
             Receives the number of pixels per vertical unit.
 

+        @beginWxPerlOnly
+        In wxPerl this method takes no parameters and returns a
+        2-element list (xUnit, yUnit).
+        @endWxPerlOnly
+

         @see SetScrollbars(), GetVirtualSize()
     */
     void GetScrollPixelsPerUnit(int* xUnit, int* yUnit) const;
         @see SetScrollbars(), GetVirtualSize()
     */
     void GetScrollPixelsPerUnit(int* xUnit, int* yUnit) const;


@@ -250,19 +354,30 @@ public:
         @param y
             Receives the first visible y position in scroll units.
 
         @param y
             Receives the first visible y position in scroll units.
 

-        @remarks If either of the scrollbars is not at the home position, x
-                 and/or y will be greater than zero.  Combined with
-                 wxWindow::GetClientSize(), the application can use this
-                 function to efficiently redraw only the visible portion
-                 of the window.  The positions are in logical scroll
-                 units, not pixels, so to convert to pixels you will
-                 have to multiply by the number of pixels per scroll
-                 increment.
-
-        @see SetScrollbars()
+        @remarks
+            If either of the scrollbars is not at the home position, @a x
+            and/or @a y will be greater than zero.
+            Combined with wxWindow::GetClientSize(), the application can use this
+            function to efficiently redraw only the visible portion of the window.
+            The positions are in logical scroll units, not pixels, so to convert
+            to pixels you will have to multiply by the number of pixels per scroll
+            increment.
+
+        @beginWxPerlOnly
+        In wxPerl this method takes no parameters and returns a
+        2-element list (x, y).
+        @endWxPerlOnly
+
+        @see SetScrollbars(), Scroll()

     */
     void GetViewStart(int* x, int* y) const;
 
     */
     void GetViewStart(int* x, int* y) const;
 

+    /**
+        This is a simple overload of GetViewStart(int*,int*); see that function
+        for more info.
+    */
+    wxPoint GetViewStart() const;
+

     /**
         Gets the size in device units of the scrollable window area (as
         opposed to the client size, which is the area of the window currently
     /**
         Gets the size in device units of the scrollable window area (as
         opposed to the client size, which is the area of the window currently


@@ -276,6 +391,11 @@ public:
         @remarks Use wxDC::DeviceToLogicalX() and wxDC::DeviceToLogicalY() to
                  translate these units to logical units.
 
         @remarks Use wxDC::DeviceToLogicalX() and wxDC::DeviceToLogicalY() to
                  translate these units to logical units.
 

+        @beginWxPerlOnly
+        In wxPerl this method takes no parameters and returns a
+        2-element list (xUnit, yUnit).
+        @endWxPerlOnly
+

         @see SetScrollbars(), GetScrollPixelsPerUnit()
     */
     void GetVirtualSize(int* x, int* y) const;
         @see SetScrollbars(), GetScrollPixelsPerUnit()
     */
     void GetVirtualSize(int* x, int* y) const;


@@ -314,14 +434,19 @@ public:
 
         @remarks The positions are in scroll units, not pixels, so to convert to
                  pixels you will have to multiply by the number of
 
         @remarks The positions are in scroll units, not pixels, so to convert to
                  pixels you will have to multiply by the number of

-                 pixels per scroll increment. If either parameter is -1,
-                 that position will be ignored (no change in that
-                 direction).
+                 pixels per scroll increment. If either parameter is
+                 ::wxDefaultCoord (-1), that position will be ignored (no change
+                 in that direction).

 
         @see SetScrollbars(), GetScrollPixelsPerUnit()
     */
     void Scroll(int x, int y);
 
 
         @see SetScrollbars(), GetScrollPixelsPerUnit()
     */
     void Scroll(int x, int y);
 

+    /**
+        This is an overload of Scroll(int,int); see that function for more info.
+    */
+    void Scroll(const wxPoint& pt);
+

     /**
         Set the horizontal and vertical scrolling increment only. See the
         pixelsPerUnit parameter in SetScrollbars().
     /**
         Set the horizontal and vertical scrolling increment only. See the
         pixelsPerUnit parameter in SetScrollbars().


@@ -381,20 +506,82 @@ public:
                        bool noRefresh = false);
 
     /**
                        bool noRefresh = false);
 
     /**

-        Call this function to tell wxScrolled to perform the actual
-        scrolling on a different window (and not on itself).
+        Call this function to tell wxScrolled to perform the actual scrolling
+        on a different window (and not on itself).
+
+        This method is useful when only a part of the window should be
+        scrolled. A typical example is a control consisting of a fixed header
+        and the scrollable contents window: the scrollbars are attached to the
+        main window itself, hence it, and not the contents window must be
+        derived from wxScrolled, but only the contents window scrolls when the
+        scrollbars are used. To implement such setup, you need to call this
+        method with the contents window as argument.
+
+        Notice that if this method is used, GetSizeAvailableForScrollTarget()
+        method must be overridden.
+    */
+    void SetTargetWindow(wxWindow *window);
+    wxWindow *GetTargetWindow() const;
+
+    
+    void SetTargetRect(const wxRect& rect);
+    wxRect GetTargetRect() const;
+
+    int GetScrollPageSize(int orient) const;
+    void SetScrollPageSize(int orient, int pageSize);
+    int GetScrollLines( int orient ) const;
+    void SetScale(double xs, double ys);
+    double GetScaleX() const;
+    double GetScaleY() const;
+
+    virtual void AdjustScrollbars();
+
+    /**
+       Are we generating the autoscroll events?
+     */
+    bool IsAutoScrolling() const;
+
+    /**
+       Stop generating the scroll events when mouse is held outside the
+       window.
+     */
+    void StopAutoScrolling();
+    
+    /**
+       This method can be overridden in a derived class to forbid sending the
+       auto scroll events - note that unlike StopAutoScrolling() it doesn't
+       stop the timer, so it will be called repeatedly and will typically
+       return different values depending on the current mouse position
+    
+       The base class version just returns true.

     */
     */

-    void SetTargetWindow(wxWindow* window);
+    virtual bool SendAutoScrollEvents(wxScrollWinEvent& event) const;
+
+
+protected:
+    /**
+        Function which must be overridden to implement the size available for
+        the scroll target for the given size of the main window.
+
+        This method must be overridden if SetTargetWindow() is used (it is
+        never called otherwise). The implementation should decrease the @a size
+        to account for the size of the non-scrollable parts of the main window
+        and return only the size available for the scrollable window itself.
+        E.g. in the example given in SetTargetWindow() documentation the
+        function would subtract the height of the header window from the
+        vertical component of @a size.
+     */
+    virtual wxSize GetSizeAvailableForScrollTarget(const wxSize& size);

 };
 
 
 /**
     Scrolled window derived from wxPanel.
 
 };
 
 
 /**
     Scrolled window derived from wxPanel.
 

-    See wxScrolled for detailed description.
+    See wxScrolled for a detailed description.

 
     @note Note that because this class derives from wxPanel, it shares its
 
     @note Note that because this class derives from wxPanel, it shares its

-          behavior with regard to TAB traversal and focus handling (in
+          behaviour with regard to TAB traversal and focus handling (in

           particular, it forwards focus to its children). If you don't want
           this behaviour, use ::wxScrolledCanvas instead.
 
           particular, it forwards focus to its children). If you don't want
           this behaviour, use ::wxScrolledCanvas instead.