synchronize GTK2 minimum version in docs

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

diff --git a/interface/wx/vscroll.h b/interface/wx/vscroll.h
index c5acde34e3d6ab49e84bc7f12f5aa4264ffa5e7c..75c8a736a9ff4c55e42f2417a17667f8d2a7c0cd 100644 (file)
--- a/interface/wx/vscroll.h
+++ b/interface/wx/vscroll.h
@@ -3,12 +3,11 @@
 // Purpose:     interface of wxVarHScrollHelper
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     interface of wxVarHScrollHelper
 // Author:      wxWidgets team
 // RCS-ID:      $Id$

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

 /////////////////////////////////////////////////////////////////////////////
 
 /**
     @class wxVarScrollHelperBase
 /////////////////////////////////////////////////////////////////////////////
 
 /**
     @class wxVarScrollHelperBase

-    @wxheader{vscroll.h}

 
     This class provides all common base functionality for scroll calculations
     shared among all variable scrolled window implementations as well as
 
     This class provides all common base functionality for scroll calculations
     shared among all variable scrolled window implementations as well as


@@ -75,21 +74,6 @@ public:
     */
     void EnablePhysicalScrolling(bool scrolling = true);
 
     */
     void EnablePhysicalScrolling(bool scrolling = true);
 

-    /**
-        When the number of scroll units change, we try to estimate the total
-        size of all units when the full window size is needed (i.e. to
-        calculate the scrollbar thumb size). This is a rather expensive
-        operation in terms of unit access, so if the user code may estimate the
-        average size better or faster than we do, it should override this
-        function to implement its own logic. This function should return the
-        best guess for the total virtual window size.
-
-        @note Although returning a totally wrong value would still work, it
-              risks resulting in very strange scrollbar behaviour so this
-              function should really try to make the best guess possible.
-    */
-    virtual wxCoord EstimateTotalSize() const;
-

     /**
         This function needs to be overridden in the in the derived class to
         return the window size with respect to the opposing orientation. If
     /**
         This function needs to be overridden in the in the derived class to
         return the window size with respect to the opposing orientation. If


@@ -97,13 +81,13 @@ public:
 
         @see GetOrientationTargetSize()
     */
 
         @see GetOrientationTargetSize()
     */

-    virtual int GetNonOrientationTargetSize() const;
+    virtual int GetNonOrientationTargetSize() const = 0;

 
     /**
         This function need to be overridden to return the orientation that this
         helper is working with, either @c wxHORIZONTAL or @c wxVERTICAL.
     */
 
     /**
         This function need to be overridden to return the orientation that this
         helper is working with, either @c wxHORIZONTAL or @c wxVERTICAL.
     */

-    virtual wxOrientation GetOrientation() const;
+    virtual wxOrientation GetOrientation() const = 0;

 
     /**
         This function needs to be overridden in the in the derived class to
 
     /**
         This function needs to be overridden in the in the derived class to


@@ -113,7 +97,7 @@ public:
 
         @see GetNonOrientationTargetSize()
     */
 
         @see GetNonOrientationTargetSize()
     */

-    virtual int GetOrientationTargetSize() const;
+    virtual int GetOrientationTargetSize() const = 0;

 
     /**
         This function will return the target window this helper class is
 
     /**
         This function will return the target window this helper class is


@@ -121,7 +105,7 @@ public:
 
         @see SetTargetWindow()
     */
 
         @see SetTargetWindow()
     */

-    wxWindow* GetTargetWindow() const;
+    virtual wxWindow* GetTargetWindow() const;

 
     /**
         Returns the index of the first visible unit based on the scroll
 
     /**
         Returns the index of the first visible unit based on the scroll


@@ -143,10 +127,34 @@ public:
     bool IsVisible(size_t unit) const;
 
     /**
     bool IsVisible(size_t unit) const;
 
     /**

-        This function must be overridden in the derived class, and should
-        return the size of the given unit in pixels.
+        Recalculate all parameters and repaint all units.

     */
     */

-    virtual wxCoord OnGetUnitSize(size_t unit) const;
+    virtual void RefreshAll();
+
+    /**
+        Normally the window will scroll itself, but in some rare occasions you
+        might want it to scroll (part of) another window (e.g. a child of it in
+        order to scroll only a portion the area between the scrollbars like a
+        spreadsheet where only the cell area will move).
+
+        @see GetTargetWindow()
+    */
+    virtual void SetTargetWindow(wxWindow* target);
+
+    /**
+        Update the thumb size shown by the scrollbar.
+    */
+    virtual void UpdateScrollbar();
+
+    /**
+        Returns the virtual scroll unit under the device unit given accounting
+        for scroll position or @c wxNOT_FOUND if none (i.e. if it is below the
+        last item).
+    */
+    int VirtualHitTest(wxCoord coord) const;
+
+
+protected:

 
     /**
         This function doesn't have to be overridden but it may be useful to do
 
     /**
         This function doesn't have to be overridden but it may be useful to do


@@ -166,38 +174,31 @@ public:
     virtual void OnGetUnitsSizeHint(size_t unitMin, size_t unitMax) const;
 
     /**
     virtual void OnGetUnitsSizeHint(size_t unitMin, size_t unitMax) const;
 
     /**

-        Recalculate all parameters and repaint all units.
-    */
-    virtual void RefreshAll();
-
-    /**
-        Normally the window will scroll itself, but in some rare occasions you
-        might want it to scroll (part of) another window (e.g. a child of it in
-        order to scroll only a portion the area between the scrollbars like a
-        spreadsheet where only the cell area will move).
-
-        @see GetTargetWindow()
-    */
-    void SetTargetWindow(wxWindow* target);
+        When the number of scroll units change, we try to estimate the total
+        size of all units when the full window size is needed (i.e. to
+        calculate the scrollbar thumb size). This is a rather expensive
+        operation in terms of unit access, so if the user code may estimate the
+        average size better or faster than we do, it should override this
+        function to implement its own logic. This function should return the
+        best guess for the total virtual window size.

 
 

-    /**
-        Update the thumb size shown by the scrollbar.
+        @note Although returning a totally wrong value would still work, it
+              risks resulting in very strange scrollbar behaviour so this
+              function should really try to make the best guess possible.

     */
     */

-    virtual void UpdateScrollbar();
+    virtual wxCoord EstimateTotalSize() const;

 
     /**
 
     /**

-        Returns the virtual scroll unit under the device unit given accounting
-        for scroll position or @c wxNOT_FOUND if none (i.e. if it is below the
-        last item).
+        This function must be overridden in the derived class, and should
+        return the size of the given unit in pixels.

     */
     */

-    int VirtualHitTest(wxCoord coord) const;
+    virtual wxCoord OnGetUnitSize(size_t unit) const = 0;

 };
 
 
 
 /**
     @class wxVarVScrollHelper
 };
 
 
 
 /**
     @class wxVarVScrollHelper

-    @wxheader{vscroll.h}

 
     This class provides functions wrapping the wxVarScrollHelperBase class,
     targeted for vertical-specific scrolling.
 
     This class provides functions wrapping the wxVarScrollHelperBase class,
     targeted for vertical-specific scrolling.


@@ -223,17 +224,6 @@ public:
     */
     wxVarVScrollHelper(wxWindow* winToScroll);
 
     */
     wxVarVScrollHelper(wxWindow* winToScroll);
 

-    /**
-        This class forwards calls from EstimateTotalSize() to this function so
-        derived classes can override either just the height or the width
-        estimation, or just estimate both differently if desired in any
-        wxHVScrolledWindow derived class.
-
-        @note This function will not be called if EstimateTotalSize() is
-              overridden in your derived class.
-    */
-    virtual wxCoord EstimateTotalHeight() const;
-

     /**
         Returns the number of rows the target window contains.
 
     /**
         Returns the number of rows the target window contains.
 


@@ -259,29 +249,6 @@ public:
     */
     bool IsRowVisible(size_t row) const;
 
     */
     bool IsRowVisible(size_t row) const;
 

-    /**
-        This function must be overridden in the derived class, and should
-        return the height of the given row in pixels.
-    */
-    virtual wxCoord OnGetRowHeight(size_t row) const;
-
-    /**
-        This function doesn't have to be overridden but it may be useful to do
-        so if calculating the rows' sizes is a relatively expensive operation
-        as it gives your code a chance to calculate several of them at once and
-        cache the result if necessary.
-
-        OnGetRowsHeightHint() is normally called just before OnGetRowHeight()
-        but you shouldn't rely on the latter being called for all rows in the
-        interval specified here. It is also possible that OnGetRowHeight() will
-        be called for units outside of this interval, so this is really just a
-        hint, not a promise.
-
-        Finally, note that @a rowMin is inclusive, while @a rowMax is
-        exclusive.
-    */
-    virtual void OnGetRowsHeightHint(size_t rowMin, size_t rowMax) const;
-

     /**
         Triggers a refresh for just the given row's area of the window if it's
         visible.
     /**
         Triggers a refresh for just the given row's area of the window if it's
         visible.


@@ -326,13 +293,48 @@ public:
         @see GetRowCount()
     */
     void SetRowCount(size_t rowCount);
         @see GetRowCount()
     */
     void SetRowCount(size_t rowCount);

+
+protected:
+
+    /**
+        This function doesn't have to be overridden but it may be useful to do
+        so if calculating the rows' sizes is a relatively expensive operation
+        as it gives your code a chance to calculate several of them at once and
+        cache the result if necessary.
+
+        OnGetRowsHeightHint() is normally called just before OnGetRowHeight()
+        but you shouldn't rely on the latter being called for all rows in the
+        interval specified here. It is also possible that OnGetRowHeight() will
+        be called for units outside of this interval, so this is really just a
+        hint, not a promise.
+
+        Finally, note that @a rowMin is inclusive, while @a rowMax is
+        exclusive.
+    */
+    virtual void OnGetRowsHeightHint(size_t rowMin, size_t rowMax) const;
+
+    /**
+        This class forwards calls from EstimateTotalSize() to this function so
+        derived classes can override either just the height or the width
+        estimation, or just estimate both differently if desired in any
+        wxHVScrolledWindow derived class.
+
+        @note This function will not be called if EstimateTotalSize() is
+              overridden in your derived class.
+    */
+    virtual wxCoord EstimateTotalHeight() const;
+
+    /**
+        This function must be overridden in the derived class, and should
+        return the height of the given row in pixels.
+    */
+    virtual wxCoord OnGetRowHeight(size_t row) const = 0;

 };
 
 
 
 /**
     @class wxVarHScrollHelper
 };
 
 
 
 /**
     @class wxVarHScrollHelper

-    @wxheader{vscroll.h}

 
     This class provides functions wrapping the wxVarScrollHelperBase class,
     targeted for horizontal-specific scrolling.
 
     This class provides functions wrapping the wxVarScrollHelperBase class,
     targeted for horizontal-specific scrolling.


@@ -358,17 +360,6 @@ public:
     */
     wxVarHScrollHelper(wxWindow* winToScroll);
 
     */
     wxVarHScrollHelper(wxWindow* winToScroll);
 

-    /**
-        This class forwards calls from EstimateTotalSize() to this function so
-        derived classes can override either just the height or the width
-        estimation, or just estimate both differently if desired in any
-        wxHVScrolledWindow derived class.
-
-        @note This function will not be called if EstimateTotalSize() is
-              overridden in your derived class.
-    */
-    virtual wxCoord EstimateTotalWidth() const;
-

     /**
         Returns the number of columns the target window contains.
 
     /**
         Returns the number of columns the target window contains.
 


@@ -395,30 +386,6 @@ public:
     */
     bool IsColumnVisible(size_t column) const;
 
     */
     bool IsColumnVisible(size_t column) const;
 

-    /**
-        This function must be overridden in the derived class, and should
-        return the width of the given column in pixels.
-    */
-    virtual wxCoord OnGetColumnWidth(size_t column) const;
-
-    /**
-        This function doesn't have to be overridden but it may be useful to do
-        so if calculating the columns' sizes is a relatively expensive
-        operation as it gives your code a chance to calculate several of them
-        at once and cache the result if necessary.
-
-        OnGetColumnsWidthHint() is normally called just before
-        OnGetColumnWidth() but you shouldn't rely on the latter being called
-        for all columns in the interval specified here. It is also possible
-        that OnGetColumnWidth() will be called for units outside of this
-        interval, so this is really just a hint, not a promise.
-
-        Finally, note that @a columnMin is inclusive, while @a columnMax is
-        exclusive.
-    */
-    virtual void OnGetColumnsWidthHint(size_t columnMin,
-                                       size_t columnMax) const;
-

     /**
         Triggers a refresh for just the given column's area of the window if
         it's visible.
     /**
         Triggers a refresh for just the given column's area of the window if
         it's visible.


@@ -463,13 +430,49 @@ public:
         @see GetColumnCount()
     */
     void SetColumnCount(size_t columnCount);
         @see GetColumnCount()
     */
     void SetColumnCount(size_t columnCount);

+
+protected:
+
+    /**
+        This class forwards calls from EstimateTotalSize() to this function so
+        derived classes can override either just the height or the width
+        estimation, or just estimate both differently if desired in any
+        wxHVScrolledWindow derived class.
+
+        @note This function will not be called if EstimateTotalSize() is
+              overridden in your derived class.
+    */
+    virtual wxCoord EstimateTotalWidth() const;
+
+    /**
+        This function doesn't have to be overridden but it may be useful to do
+        so if calculating the columns' sizes is a relatively expensive
+        operation as it gives your code a chance to calculate several of them
+        at once and cache the result if necessary.
+
+        OnGetColumnsWidthHint() is normally called just before
+        OnGetColumnWidth() but you shouldn't rely on the latter being called
+        for all columns in the interval specified here. It is also possible
+        that OnGetColumnWidth() will be called for units outside of this
+        interval, so this is really just a hint, not a promise.
+
+        Finally, note that @a columnMin is inclusive, while @a columnMax is
+        exclusive.
+    */
+    virtual void OnGetColumnsWidthHint(size_t columnMin,
+                                       size_t columnMax) const;
+
+    /**
+        This function must be overridden in the derived class, and should
+        return the width of the given column in pixels.
+    */
+    virtual wxCoord OnGetColumnWidth(size_t column) const = 0;

 };
 
 
 
 /**
     @class wxVarHVScrollHelper
 };
 
 
 
 /**
     @class wxVarHVScrollHelper

-    @wxheader{vscroll.h}

 
     This class provides functions wrapping the wxVarHScrollHelper and
     wxVarVScrollHelper classes, targeted for scrolling a window in both axis.
 
     This class provides functions wrapping the wxVarHScrollHelper and
     wxVarVScrollHelper classes, targeted for scrolling a window in both axis.


@@ -604,7 +607,6 @@ public:
 
 /**
     @class wxVScrolledWindow
 
 /**
     @class wxVScrolledWindow

-    @wxheader{vscroll.h}

 
     In the name of this class, "V" may stand for "variable" because it can be
     used for scrolling rows of variable heights; "virtual", because it is not
 
     In the name of this class, "V" may stand for "variable" because it can be
     used for scrolling rows of variable heights; "virtual", because it is not


@@ -627,7 +629,7 @@ public:
     shifted so the first visible row always appears at the point (0, 0) in
     physical as well as logical coordinates.
 
     shifted so the first visible row always appears at the point (0, 0) in
     physical as well as logical coordinates.
 

-    @section wxWidgets 2.8 Compatibility Functions
+    @section vscrolledwindow_compat wxWidgets 2.8 Compatibility Functions

 
     The following functions provide backwards compatibility for applications
     originally built using wxVScrolledWindow in 2.6 or 2.8. Originally,
 
     The following functions provide backwards compatibility for applications
     originally built using wxVScrolledWindow in 2.6 or 2.8. Originally,


@@ -713,7 +715,7 @@ public:
                       const wxString& name = wxPanelNameStr);
 
     /**
                       const wxString& name = wxPanelNameStr);
 
     /**

-        Same as the non-default constuctor, but returns a status code: @true if
+        Same as the non-default constructor, but returns a status code: @true if

         ok, @false if the window couldn't be created.
 
         Just as with the constructor, the @c wxVSCROLL style is always used,
         ok, @false if the window couldn't be created.
 
         Just as with the constructor, the @c wxVSCROLL style is always used,


@@ -729,7 +731,6 @@ public:
 
 /**
     @class wxHScrolledWindow
 
 /**
     @class wxHScrolledWindow

-    @wxheader{vscroll.h}

 
     In the name of this class, "H" stands for "horizontal" because it can be
     used for scrolling columns of variable widths. It is not necessary to know
 
     In the name of this class, "H" stands for "horizontal" because it can be
     used for scrolling columns of variable widths. It is not necessary to know


@@ -790,7 +791,7 @@ public:
                       const wxString& name = wxPanelNameStr);
 
     /**
                       const wxString& name = wxPanelNameStr);
 
     /**

-        Same as the non-default constuctor, but returns a status code: @true if
+        Same as the non-default constructor, but returns a status code: @true if

         ok, @false if the window couldn't be created.
 
         Just as with the constructor, the @c wxHSCROLL style is always used,
         ok, @false if the window couldn't be created.
 
         Just as with the constructor, the @c wxHSCROLL style is always used,


@@ -806,7 +807,6 @@ public:
 
 /**
     @class wxHVScrolledWindow
 
 /**
     @class wxHVScrolledWindow

-    @wxheader{vscroll.h}

 
     This window inherits all functionality of both vertical and horizontal,
     variable scrolled windows. It automatically handles everything needed to
 
     This window inherits all functionality of both vertical and horizontal,
     variable scrolled windows. It automatically handles everything needed to


@@ -868,7 +868,7 @@ public:
                        const wxString& name = wxPanelNameStr);
 
     /**
                        const wxString& name = wxPanelNameStr);
 
     /**

-        Same as the non-default constuctor, but returns a status code: @true if
+        Same as the non-default constructor, but returns a status code: @true if

         ok, @false if the window couldn't be created.
 
         Just as with the constructor, the @c wxHSCROLL and @c wxVSCROLL styles
         ok, @false if the window couldn't be created.
 
         Just as with the constructor, the @c wxHSCROLL and @c wxVSCROLL styles