docs/doxygen/overviews/windowsizing.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        windowsizing.h
   3 // Purpose:     topic overview
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /*!
  10
  11 @page overview_windowsizing Window Sizing Overview
  12
  13 It can sometimes be confusing to keep track of the various size-related
  14 attributes of a wxWindow, how they relate to each other, and how they interact
  15 with sizers. This document will attempt to clear the fog a little, and give
  16 some simple explanations of things.
  17
  18 @b BestSize: The best size of a widget depends on what kind of widget it is,
  19 and usually also on the contents of the widget. For example a wxListBox's best
  20 size will be calculated based on how many items it has, up to a certain limit,
  21 or a wxButton's best size will be calculated based on its label size, but
  22 normally won't be smaller than the platform default button size (unless a style
  23 flag overrides that). Get the picture? There is a special virtual method in the
  24 C++ window classes called @c DoGetBestSize() that a class needs to override if
  25 it wants to calculate its own best size based on its content. The default
  26 @c DoGetBestSize() is designed for use in container windows, such as wxPanel,
  27 and works something like this:
  28
  29 -# If the window has a sizer then it is used to calculate the best size.
  30 -# Otherwise if the window has layout constraints then that is used to
  31    calculate the best size.
  32 -# Otherwise if the window has children then the best size is set to be large
  33    enough to show all the children.
  34 -# Otherwise if there are no children then the window's min size will be used
  35    for the best size.
  36 -# Otherwise if there is no min size set, then the current size is used for the
  37    best size.
  38
  39 @b MinSize: The min size of a widget is a size that is normally explicitly set
  40 by the programmer either with the @c SetMinSize() method or the
  41 @c SetSizeHints() method. Most controls will also set the min size to the size
  42 given in the control's constructor if a non-default value is passed. Top-level
  43 windows such as wxFrame will not allow the user to resize the frame below the
  44 min size.
  45
  46 @b Size: The size of a widget can be explicitly set or fetched with the
  47 @c SetSize() or @c GetSize() methods. This size value is the size that the
  48 widget is currently using on screen and is the way to change the size of
  49 something that is not being managed by a sizer.
  50
  51 @b ClientSize: The client size represents the widget's area inside of any
  52 borders belonging to the widget and is the area that can be drawn upon in a
  53 @c EVT_PAINT event. If a widget doesn't have a border then its client size is
  54 the same as its size.
  55
  56 @b InitialSize: The initial size of a widget is the size given to the
  57 constructor of the widget, if any.  As mentioned above most controls will also
  58 set this size value as the control's min size. If the size passed to the
  59 constructor is the default @c wxDefaultSize, or if the size is not fully
  60 specified (such as wxSize(150,-1)) then most controls will fill in the missing
  61 size components using the best size and will set the initial size of the
  62 control to the resulting size.
  63
  64 @b GetEffectiveMinSize(): (formerly @c GetBestFittingSize) A blending of the
  65 widget's min size and best size, giving precedence to the min size. For
  66 example, if a widget's min size is set to (150, -1) and the best size is
  67 (80, 22) then the best fitting size is (150, 22). If the min size is (50, 20)
  68 then the best fitting size is (50, 20). This method is what is called by the
  69 sizers when determining what the requirements of each item in the sizer is, and
  70 is used for calculating the overall minimum needs of the sizer.
  71
  72 @b SetInitialSize(size): (formerly @c SetBestFittingSize) This is a little
  73 different than the typical size setters. Rather than just setting an
  74 "initial size" attribute it actually sets the minsize to the value passed in,
  75 blends that value with the best size, and then sets the size of the widget to
  76 be the result. So you can consider this method to be a "Smart SetSize". This
  77 method is what is called by the constructor of most controls to set the minsize
  78 and initial size of the control.
  79
  80 @b window.Fit(): The @c Fit() method sets the size of a window to fit around
  81 its children. If it has no children then nothing is done, if it does have
  82 children then the size of the window is set to the window's best size.
  83
  84 @b sizer.Fit(window): This sets the size of the window to be large enough to
  85 accommodate the minimum size needed by the sizer, (along with a few other
  86 constraints...) If the sizer is the one that is assigned to the window then
  87 this should be equivalent to @c window.Fit().
  88
  89 @b sizer.Layout(): Recalculates the minimum space needed by each item in the
  90 sizer, and then lays out the items within the space currently allotted to the
  91 sizer.
  92
  93 @b window.Layout(): If the window has a sizer then it sets the space given to
  94 the sizer to the current size of the window, which results in a call to
  95 @c sizer.Layout(). If the window has layout constraints instead of a sizer then
  96 the constraints algorithm is run. The @c Layout() method is what is called by
  97 the default @c EVT_SIZE handler for container windows.
  98
  99 */
 100