Improve wxWindow best size documentation, mention DoGetBestClientSize().

Custom classes should typically override DoGetBestClientSize() instead of
DoGetBestSize() to avoid having to deal with the borders.

Also don't reference the deprecated SetInitialBestSize() unnecessarily and
document its non-deprecated replacement.

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

diff --git a/docs/doxygen/overviews/windowsizing.h b/docs/doxygen/overviews/windowsizing.h
index 5492c10e38588caec0d6452a41e1844ffd2cbdbe..baf7611eb5650f04df772e37da48befd5fe760c0 100644 (file)
--- a/docs/doxygen/overviews/windowsizing.h
+++ b/docs/doxygen/overviews/windowsizing.h
@@ -24,6 +24,18 @@ some simple explanations of things.
 
 @section overview_windowsizing_glossary Glossary
 
+@li @b "Size": this is the current size of the window and it 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
+    the way to change the size of something that is not being managed by a sizer.
+
+@li @b "Client Size": the client size represents the widget's area inside of any
+    borders belonging to the widget and is the area that can be drawn upon in a
+    @c EVT_PAINT event. For wxFrame, the client size also excludes the frame
+    menu, tool and status bars, if any. If a window doesn't have any border
+    (and is not a wxFrame with some bars) then its client size is the same as
+    its size.
+
 @li @b "Best Size": the best size of a widget depends on what kind of widget it is,
     and usually also on the contents of the widget. For example a wxListBox's best
     size will be calculated based on how many items it has, up to a certain limit,
@@ -31,8 +43,16 @@ some simple explanations of things.
     normally won't be smaller than the platform default button size (unless a style
     flag overrides that).
     There is a special virtual method in the C++ window classes called
-    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 can override if it wants to calculate
+    its own best size based on its content, however notice that usually it is
+    more convenient to override DoGetBestClientSize(), see below.
+
+@li @b "Best Client Size": this is simply the client size corresponding to the
+    best window size. When the fitting size for the given contents is computed,
+    it will usually be the client size and the size of the borders needs to be
+    added to obtain the full best size. For this reason, it's preferable to
+    override DoGetBestClientSize() and let DoGetBestSize() compute the full
+    best size.
 
 @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
@@ -48,16 +68,6 @@ some simple explanations of things.
     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
-    the way to change the size of something that is not being managed by a sizer.
-
-@li @b "Client Size": the client size represents the widget's area inside of any
-    borders belonging to the widget and is the area that can be drawn upon in a
-    @c EVT_PAINT event. If a widget doesn't have a border then its client size is
-    the same as its size.
-
 @li @b "Initial Size": the initial size of a widget is the size given to the
     constructor of the widget, if any.
     As mentioned above most controls will also set this size value as the control's

diff --git a/interface/wx/window.h b/interface/wx/window.h
index 0e8eb7d87fb56ea9aa61943978d703122a37cc84..91981a7537b70c1aa2bb530e19d8be557d5c9747 100644 (file)
--- a/interface/wx/window.h
+++ b/interface/wx/window.h
@@ -737,7 +737,8 @@ public:
     /**
         @name Sizing functions
 
-        See also the protected functions DoGetBestSize() and SetInitialBestSize().
+        See also the protected functions DoGetBestSize() and
+        DoGetBestClientSize().
     */
     //@{
 
@@ -818,8 +819,9 @@ public:
         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 override the
-        DoGetBestSize() function instead of this (non-virtual!) function.
+        Override virtual DoGetBestSize() or, better, because it's usually more
+        convenient, DoGetBestClientSize() when writing your own custom window
+        class to change the value returned by this public non-virtual method.
 
         @see CacheBestSize(), @ref overview_windowsizing
     */
@@ -3438,9 +3440,11 @@ protected:
     virtual void DoCentre(int direction);
 
     /**
-        Gets the size which best suits the window: for a control, it would be
-        the minimal size which doesn't truncate the control, for a panel - the
-        same size as it would have after a call to Fit().
+        Implementation of GetBestSize() that can be overridden.
+
+        Notice that it is usually more convenient to override
+        DoGetBestClientSize() rather than this method itself as you need to
+        explicitly account for the window borders size if you do the latter.
 
         The default implementation of this function is designed for use in container
         windows, such as wxPanel, and works something like this:
@@ -3458,11 +3462,28 @@ protected:
     */
     virtual wxSize DoGetBestSize() const;
 
+    /**
+        Override this method to return the best size for a custom control.
+
+        A typical implementation of this method should compute the minimal size
+        needed to fully display the control contents taking into account the
+        current font size.
+
+        The default implementation simply returns ::wxDefaultSize and
+        GetBestSize() returns an arbitrary hardcoded size for the window, so
+        you must override it when implementing a custom window class.
+
+        @see @ref overview_windowsizing
+
+        @since 2.9.0
+     */
+    virtual wxSize DoGetBestClientSize() const;
+
 
     /**
         Sets the initial window size if none is given (i.e. at least one of the
         components of the size passed to ctor/Create() is wxDefaultCoord).
-        @deprecated @todo provide deprecation description
+        @deprecated Use SetInitialSize() instead.
     */
     virtual void SetInitialBestSize(const wxSize& size);