X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/cded6aa1c3fe6e6b83346eacee04dc485aeccd42..2e18fe7139558b3cb592a04a4e4668319a966ebf:/docs/doxygen/overviews/windowsizing.h

diff --git a/docs/doxygen/overviews/windowsizing.h b/docs/doxygen/overviews/windowsizing.h
index 7c05e6c388..baf7611eb5 100644
--- a/docs/doxygen/overviews/windowsizing.h
+++ b/docs/doxygen/overviews/windowsizing.h
@@ -3,7 +3,7 @@
 // Purpose:     topic overview
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
-// Licence:     wxWindows license
+// Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 
 /**
@@ -15,7 +15,26 @@ attributes of a wxWindow, how they relate to each other, and how they interact
 with sizers. This document will attempt to clear the fog a little, and give
 some simple explanations of things.
 
-Glossary:
+@li @ref overview_windowsizing_glossary
+@li @ref overview_windowsizing_func
+
+
+<hr>
+
+
+@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
@@ -24,26 +43,30 @@ Glossary:
     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.
-
-@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
+    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
     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.
 
-@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 "Maximum Size": just like for the minimal size, the maximum size is normally
+    explicitly 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 "Initial Size": the initial size of a widget is the size given to the
     constructor of the widget, if any.
@@ -53,8 +76,15 @@ Glossary:
     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.
+
 
-Functions related to sizing:
+@section overview_windowsizing_func Functions related to sizing
 
 @li wxWindow::GetEffectiveMinSize(): returns a blending of the widget's minimal size
     and best size, giving precedence to the minimal size.