update minimum GTK2 version requirement to 2.6

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

diff --git a/interface/wx/scrolwin.h b/interface/wx/scrolwin.h
index b3664bee2ef805e7cbd96d48507486aaaeb8f90d..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


@@ -93,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


@@ -125,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.


@@ -153,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;


@@ -164,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;


@@ -179,6 +227,22 @@ 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.
     /**
         Call this function to prepare the device context for drawing a scrolled
         image.


@@ -237,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


@@ -247,11 +337,15 @@ 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;
 

-    //@{

     /**
         Get the position at which the visible portion of the window starts.
 
     /**
         Get the position at which the visible portion of the window starts.
 


@@ -260,20 +354,29 @@ 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.
+        @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;
 
         @see SetScrollbars(), Scroll()
     */
     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;
     wxPoint GetViewStart() const;

-    //@}

 
     /**
         Gets the size in device units of the scrollable window area (as
 
     /**
         Gets the size in device units of the scrollable window area (as


@@ -288,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;


@@ -316,7 +424,6 @@ public:
     */
     void PrepareDC(wxDC& dc);
 
     */
     void PrepareDC(wxDC& dc);
 

-    //@{

     /**
         Scrolls a window so the view start is at the given point.
 
     /**
         Scrolls a window so the view start is at the given point.
 


@@ -328,14 +435,17 @@ public:
         @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
         @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

-                 wxDefaultCoord (-1), that position will be ignored (no change
+                 ::wxDefaultCoord (-1), that position will be ignored (no change

                  in that direction).
 
         @see SetScrollbars(), GetScrollPixelsPerUnit()
     */
     void Scroll(int x, int y);
                  in that direction).
 
         @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);
     void Scroll(const wxPoint& pt);

-    //@}

 
     /**
         Set the horizontal and vertical scrolling increment only. See the
 
     /**
         Set the horizontal and vertical scrolling increment only. See the


@@ -411,6 +521,42 @@ public:
         method must be overridden.
     */
     void SetTargetWindow(wxWindow *window);
         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.
+    */
+    virtual bool SendAutoScrollEvents(wxScrollWinEvent& event) const;
+

 
 protected:
     /**
 
 protected:
     /**


@@ -432,10 +578,10 @@ protected:
 /**
     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.