Add a topc overview about window sizing

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

docs/latex/wx/topics.tex

@@ -10,6 +10,7 @@ This chapter contains a selection of topic overviews.
 \input hworld.tex
 \input tsamples.tex
 \input tapp.tex
+\input twinsizes.tex
 \input truntime.tex
 \input trefcount.tex
 \input tstring.tex

docs/latex/wx/twinsizes.tex

@@ -0,0 +1,102 @@
+\section{Window Sizing Overview}\label{windowsizingoverview}
+
+
+
+
+It can sometimes be confusing to keep track of the various
+size-related attribtes of a \helpref{wxWindow}{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
+explainations of things.
+
+{\bf BestSize}: 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
+\helpref{wxListBox}{wxlistbox}'s best size will be calculated based on
+how many items it has, up to a certain limit, or a
+\helpref{wxButton}{wxbutton}'s best size will be calculated based on
+its label size, but normally won't be smaller than the platform
+deafult button size (unless a style flag overrides that). Get the
+picture? There is a special virtual method in the C++ window classes
+called \texttt{DoGetBestSize()} that a class needs to override if it
+wants to calculate its own best size based on its content. The default
+\texttt{DoGetBestSize()} is designed for use in container windows,
+such as wx.Panel, and works something like this:
+
+\begin{enumerate}
+  \item{If the window has a sizer then it is used to calculate the best size.}
+  \item{Otherwise if the window has layout constraints then that is used to calculate the best size.}
+  \item{Otherwise if the window has children then the best size is set to be large enough to show all the children.}
+  \item{Otherwise if there are no children then the window's min size will be used for the best size.}
+  \item{Otherwise if there is no min size set, then the current size is used for the best size.}
+\end{enumerate}
+
+{\bf MinSize}: The min size of a widget is a size that is normally
+explicitly set by the programmer either with the \texttt{SetMinSize()}
+method or the \texttt{SetSizeHints()} method. Most controls will also
+set the min size to the size given in the control's contstructor if a
+non-default value is passed. Top-level windows such as
+\helpref{wxFrame}{wxframe} will not allow the user to resize the frame
+below the min size.
+
+{\bf Size}: The size of a widget can be explicitly set or fetched with
+the \texttt{SetSize()} or \texttt{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.
+
+{\bf ClientSize}: 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 \texttt{EVT\_PAINT} event. If a widget doesn't have a
+border then its client size is the same as its size.
+
+{\bf InitialSize}: 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 min size. If
+the size passed to the constructor is the default
+\texttt{wxDefaultSize}, or if the size is not fully specified (such as
+\texttt{wxSize(150,-1)}) then most controls will fill in the missing
+size components using the best size and will set the initial size of
+the control to the resulting size.
+
+{\bf GetEffectiveMinSize()}: (formerly \texttt{GetBestFittingSize}) A
+blending of the widget's min size and best size, giving precedence to
+the min size. For example, if a widget's min size is set to (150, -1)
+and the best size is (80, 22) then the best fitting size is (150,
+22). If the min size is (50, 20) then the best fitting size is (50,
+20). This method is what is called by the sizers when determining what
+the requirements of each item in the sizer is, and is used for
+calculating the overall minimum needs of the sizer.
+
+{\bf SetInitialSize(size)}: (formerly \texttt{SetBestFittingSize})
+This is a little different than the typical size setters. Rather than
+just setting an "initial size" attribute it actually sets the minsize
+to the value passed in, blends that value with the best size, and then
+sets the size of the widget to be the result. So you can consider this
+method to be a "Smart SetSize". This method is what is called by the
+constructor of most controls to set the minsize and initial size of
+the control.
+
+{\bf window.Fit()}: The \texttt{Fit()} method sets the size of a
+window to fit around its children. If it has no children then nothing
+is done, if it does have children then the size of the window is set
+to the window's best size.
+
+{\bf sizer.Fit(window)}: This sets the size of the window to be large
+enough to accomodate the minimum size needed by the sizer, (along with
+a few other constraints...) If the sizer is the one that is assigned
+to the window then this should be equivalent to \texttt{window.Fit()}.
+
+{\bf sizer.Layout()}: Recalcualtes the minimum space needed by each
+item in the sizer, and then lays out the items within the space
+currently allotted to the sizer.
+
+{\bf window.Layout()}: If the window has a sizer then it sets the
+space given to the sizer to the current size of the window, which
+results in a call to \texttt{sizer.Layout()}. If the window has layout
+constraints instead of a sizer then the constraints algorithm is
+run. The \texttt{Layout()} method is what is called by the default
+\texttt{EVT\_SIZE} handler for container windows.
+
+
+
+

docs/latex/wx/window.tex

@@ -115,7 +115,8 @@ even if the mode set by \helpref{wxUpdateUIEvent::SetMode}{wxupdateuieventsetmod
 
 \wxheading{See also}
 
-\helpref{Event handling overview}{eventhandlingoverview}
+\helpref{Event handling overview}{eventhandlingoverview}\\
+\helpref{Window sizing overview}{windowsizingoverview}
 
 \latexignore{\rtfignore{\wxheading{Members}}}