add many references to the overview_windowsizing topic in wxWindow's size functions...

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@58676 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

diff --git a/docs/doxygen/overviews/windowsizing.h b/docs/doxygen/overviews/windowsizing.h
index 98dd9bb1ed050a485607d4f0a9891d9205c830bb..a44107d7f22a2dab3dd5e2a49979efaf4b5a6027 100644 (file)
--- a/docs/doxygen/overviews/windowsizing.h
+++ b/docs/doxygen/overviews/windowsizing.h
@@ -34,14 +34,20 @@ some simple explanations of things.
     wxWindow::DoGetBestSize() that a class needs to override if it wants to calculate
     its own best size based on its content.
 
     wxWindow::DoGetBestSize() that a class needs to override if it wants to calculate
     its own best size based on its content.
 

-@li @b "Min Size": the minimal size of a widget is a size that is normally explicitly set
-    by the programmer either with the wxWindow::SetMinSize() method or with the
+@li @b "Minimal Size": the minimal size of a widget is a size that is normally explicitly
+    set by the programmer either with the wxWindow::SetMinSize() method or with the

     wxWindow::SetSizeHints() method.
     wxWindow::SetSizeHints() method.

-    Most controls will also set the min size to the size given in the control's
+    Most controls will also set the minimal size to the size given in the control's

     constructor if a non-default value is passed.
     Top-level windows such as wxFrame will not allow the user to resize the frame below
     the minimal size.
 
     constructor if a non-default value is passed.
     Top-level windows such as wxFrame will not allow the user to resize the frame below
     the minimal size.
 

+@li @b "Maximum Size": just like for the minimal size, the maximum size is normally
+    explicitely set by the programmer with the wxWindow::SetMaxSize() method or
+    with wxWindow::SetSizeHints().
+    Top-level windows such as wxFrame will not allow the user to resize the frame above
+    the maximum size.
+

 @li @b "Size": the size of a widget can be explicitly set or fetched with the
     wxWindow::SetSize() or wxWindow::GetSize() methods.
     This size value is the size that the widget is currently using on screen and is
 @li @b "Size": the size of a widget can be explicitly set or fetched with the
     wxWindow::SetSize() or wxWindow::GetSize() methods.
     This size value is the size that the widget is currently using on screen and is


@@ -60,6 +66,13 @@ some simple explanations of things.
     will fill in the missing size components using the best size and will set the
     initial size of the control to the resulting size.
 
     will fill in the missing size components using the best size and will set the
     initial size of the control to the resulting size.
 

+@li @b "Virtual Size": the virtual size is the size of the potentially viewable
+    area of the widget.
+    The virtual size of a widget may be larger than its actual size and in this
+    case scrollbars will appear to the let the user 'explore' the full contents
+    of the widget.
+    See wxScrolled for more info.
+

 
 @section overview_windowsizing_func Functions related to sizing
 
 
 @section overview_windowsizing_func Functions related to sizing
 

diff --git a/interface/wx/window.h b/interface/wx/window.h
index f54958c3120d0b2c51664ee94f1a8f881bfe0463..d2fe5d73a4c5cfca2c268c90ef19e377c844500e 100644 (file)
--- a/interface/wx/window.h
+++ b/interface/wx/window.h
@@ -416,6 +416,9 @@ public:
 
     /**
         @name Scrolling and scrollbars functions
 
     /**
         @name Scrolling and scrollbars functions

+
+        Note that these methods don't work with native controls which don't use
+        wxWidgets scrolling framework (i.e. don't derive from wxScrolledWindow).

     */
     //@{
 
     */
     //@{
 


@@ -437,7 +440,7 @@ public:
     /**
         Returns the built-in scrollbar position.
 
     /**
         Returns the built-in scrollbar position.
 

-        @see See SetScrollbar()
+        @see SetScrollbar()

     */
     virtual int GetScrollPos(int orientation) const;
 
     */
     virtual int GetScrollPos(int orientation) const;
 


@@ -612,6 +615,8 @@ public:
 
     /**
         Sets the cached best size value.
 
     /**
         Sets the cached best size value.

+
+        @see GetBestSize()

     */
     void CacheBestSize(const wxSize& size) const;
 
     */
     void CacheBestSize(const wxSize& size) const;
 


@@ -684,6 +689,11 @@ public:
         control label is not truncated. For windows containing subwindows (typically
         wxPanel), the size returned by this function will be the same as the size
         the window would have had after calling Fit().
         control label is not truncated. For windows containing subwindows (typically
         wxPanel), the size returned by this function will be the same as the size
         the window would have had after calling Fit().

+
+        Note that when you write your own widget you need to overload the
+        DoGetBestSize() function instead of this (non-virtual!) function.
+
+        @see CacheBestSize(), @ref overview_windowsizing

     */
     wxSize GetBestSize() const;
 
     */
     wxSize GetBestSize() const;
 


@@ -708,7 +718,7 @@ public:
         Merges the window's best size into the min size and returns the result.
         This is the value used by sizers to determine the appropriate
         ammount of space to allocate for the widget.
         Merges the window's best size into the min size and returns the result.
         This is the value used by sizers to determine the appropriate
         ammount of space to allocate for the widget.

-        
+

         This is the method called by any wxSizer when they query the size
         of a certain window or control.
 
         This is the method called by any wxSizer when they query the size
         of a certain window or control.
 


@@ -723,7 +733,7 @@ public:
         possible size as well as the upper bound on window's size settable using
         SetClientSize().
 
         possible size as well as the upper bound on window's size settable using
         SetClientSize().
 

-        @see GetMaxSize()
+        @see GetMaxSize(), @ref overview_windowsizing

     */
     virtual wxSize GetMaxClientSize() const;
 
     */
     virtual wxSize GetMaxClientSize() const;
 


@@ -733,7 +743,7 @@ public:
         This is an indication to the sizer layout mechanism that this is the maximum
         possible size as well as the upper bound on window's size settable using SetSize().
 
         This is an indication to the sizer layout mechanism that this is the maximum
         possible size as well as the upper bound on window's size settable using SetSize().
 

-        @see GetMaxClientSize()
+        @see GetMaxClientSize(), @ref overview_windowsizing

     */
     virtual wxSize GetMaxSize() const;
 
     */
     virtual wxSize GetMaxSize() const;
 


@@ -744,7 +754,7 @@ public:
         It normally just returns the value set by SetMinClientSize(), but it can be
         overridden to do the calculation on demand.
 
         It normally just returns the value set by SetMinClientSize(), but it can be
         overridden to do the calculation on demand.
 

-        @see GetMinSize()
+        @see GetMinSize(), @ref overview_windowsizing

     */
     virtual wxSize GetMinClientSize() const;
 
     */
     virtual wxSize GetMinClientSize() const;
 


@@ -755,7 +765,7 @@ public:
         This method normally just returns the value set by SetMinSize(), but it
         can be overridden to do the calculation on demand.
 
         This method normally just returns the value set by SetMinSize(), but it
         can be overridden to do the calculation on demand.
 

-        @see GetMinClientSize()
+        @see GetMinClientSize(), @ref overview_windowsizing

     */
     virtual wxSize GetMinSize() const;
 
     */
     virtual wxSize GetMinSize() const;
 


@@ -771,7 +781,7 @@ public:
         @param height
             Receives the window height.
 
         @param height
             Receives the window height.
 

-        @see GetClientSize(), GetVirtualSize()
+        @see GetClientSize(), GetVirtualSize(), @ref overview_windowsizing

     */
     void GetSize(int* width, int* height) const;
 
     */
     void GetSize(int* width, int* height) const;
 


@@ -784,6 +794,8 @@ public:
         This gets the virtual size of the window in pixels.
         By default it returns the client size of the window, but after a call to
         SetVirtualSize() it will return the size set with that method.
         This gets the virtual size of the window in pixels.
         By default it returns the client size of the window, but after a call to
         SetVirtualSize() it will return the size set with that method.

+
+        @see @ref overview_windowsizing

     */
     wxSize GetVirtualSize() const;
 
     */
     wxSize GetVirtualSize() const;
 


@@ -806,8 +818,11 @@ public:
     /**
         Resets the cached best size value so it will be recalculated the next time it
         is needed.
     /**
         Resets the cached best size value so it will be recalculated the next time it
         is needed.

+
+        @see CacheBestSize()

     */
     void InvalidateBestSize();
     */
     void InvalidateBestSize();

+

     /**
         Posts a size event to the window.
 
     /**
         Posts a size event to the window.
 


@@ -866,6 +881,8 @@ public:
         than SetSize(), since the application need not worry about what dimensions
         the border or title bar have when trying to fit the window around panel
         items, for example.
         than SetSize(), since the application need not worry about what dimensions
         the border or title bar have when trying to fit the window around panel
         items, for example.

+
+        @see @ref overview_windowsizing

     */
     virtual void SetClientSize(int width, int height);
 
     */
     virtual void SetClientSize(int width, int height);
 


@@ -902,7 +919,12 @@ public:
         Sets the maximum client size of the window, to indicate to the sizer
         layout mechanism that this is the maximum possible size of its client area.
 
         Sets the maximum client size of the window, to indicate to the sizer
         layout mechanism that this is the maximum possible size of its client area.
 

-        @see SetMaxSize()
+        Note that this method is just a shortcut for:
+        @code
+        SetMaxSize(ClientToWindowSize(size));
+        @endcode
+
+        @see SetMaxSize(), @ref overview_windowsizing

     */
     virtual void SetMaxClientSize(const wxSize& size);
 
     */
     virtual void SetMaxClientSize(const wxSize& size);
 


@@ -910,7 +932,7 @@ public:
         Sets the maximum size of the window, to indicate to the sizer layout mechanism
         that this is the maximum possible size.
 
         Sets the maximum size of the window, to indicate to the sizer layout mechanism
         that this is the maximum possible size.
 

-        @see SetMaxClientSize()
+        @see SetMaxClientSize(), @ref overview_windowsizing

     */
     virtual void SetMaxSize(const wxSize& size);
 
     */
     virtual void SetMaxSize(const wxSize& size);
 


@@ -926,7 +948,12 @@ public:
         prevent the program from explicitly making the window smaller than the
         specified size.
 
         prevent the program from explicitly making the window smaller than the
         specified size.
 

-        @see SetMinSize()
+        Note that this method is just a shortcut for:
+        @code
+        SetMinSize(ClientToWindowSize(size));
+        @endcode
+
+        @see SetMinSize(), @ref overview_windowsizing

     */
     virtual void SetMinClientSize(const wxSize& size);
 
     */
     virtual void SetMinClientSize(const wxSize& size);
 


@@ -942,7 +969,7 @@ public:
         SetSize(), it just ensures that it won't become smaller than this size
         during the automatic layout.
 
         SetSize(), it just ensures that it won't become smaller than this size
         during the automatic layout.
 

-        @see SetMinClientSize()
+        @see SetMinClientSize(), @ref overview_windowsizing

     */
     virtual void SetMinSize(const wxSize& size);
 
     */
     virtual void SetMinSize(const wxSize& size);
 


@@ -987,7 +1014,7 @@ public:
                  should be supplied by wxWidgets, or that the current value of the
                  dimension should be used.
 
                  should be supplied by wxWidgets, or that the current value of the
                  dimension should be used.
 

-        @see Move()
+        @see Move(), @ref overview_windowsizing

     */
     void SetSize(int x, int y, int width, int height,
                  int sizeFlags = wxSIZE_AUTO);
     */
     void SetSize(int x, int y, int width, int height,
                  int sizeFlags = wxSIZE_AUTO);


@@ -998,7 +1025,7 @@ public:
 
         @remarks This form must be used with non-default width and height values.
 
 
         @remarks This form must be used with non-default width and height values.
 

-        @see Move()
+        @see Move(), @ref overview_windowsizing

     */
     virtual void SetSize(const wxRect& rect);
 
     */
     virtual void SetSize(const wxRect& rect);
 


@@ -1017,7 +1044,7 @@ public:
         (such as wxDialog or wxFrame) is discouraged.
         Please use SetMinSize() and SetMaxSize() instead.
 
         (such as wxDialog or wxFrame) is discouraged.
         Please use SetMinSize() and SetMaxSize() instead.
 

-        @see wxTopLevelWindow::SetSizeHints
+        @see wxTopLevelWindow::SetSizeHints, @ref overview_windowsizing

     */
     void SetSizeHints( const wxSize& minSize,
                        const wxSize& maxSize=wxDefaultSize,
     */
     void SetSizeHints( const wxSize& minSize,
                        const wxSize& maxSize=wxDefaultSize,


@@ -1025,6 +1052,8 @@ public:
 
     /**
         Sets the virtual size of the window in pixels.
 
     /**
         Sets the virtual size of the window in pixels.

+
+        @see @ref overview_windowsizing

     */
     void SetVirtualSize(int width, int height);
 
     */
     void SetVirtualSize(int width, int height);