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 licence
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10
  11 @page overview_windowsizing Window Sizing Overview
  12
  13 @tableofcontents
  14
  15 It can sometimes be confusing to keep track of the various size-related
  16 attributes of a wxWindow, how they relate to each other, and how they interact
  17 with sizers. This document will attempt to clear the fog a little, and give
  18 some simple explanations of things.
  19
  20
  21
  22 @section overview_windowsizing_glossary Glossary
  23
  24 @li @b "Size": this is the current size of the window and it can be explicitly
  25     set or fetched with the wxWindow::SetSize() or wxWindow::GetSize() methods.
  26     This size value is the size that the widget is currently using on screen and is
  27     the way to change the size of something that is not being managed by a sizer.
  28
  29 @li @b "Client Size": the client size represents the widget's area inside of any
  30     borders belonging to the widget and is the area that can be drawn upon in a
  31     @c EVT_PAINT event. For wxFrame, the client size also excludes the frame
  32     menu, tool and status bars, if any. If a window doesn't have any border
  33     (and is not a wxFrame with some bars) then its client size is the same as
  34     its size.
  35
  36 @li @b "Best Size": the best size of a widget depends on what kind of widget it is,
  37     and usually also on the contents of the widget. For example a wxListBox's best
  38     size will be calculated based on how many items it has, up to a certain limit,
  39     or a wxButton's best size will be calculated based on its label size, but
  40     normally won't be smaller than the platform default button size (unless a style
  41     flag overrides that).
  42     There is a special virtual method in the C++ window classes called
  43     wxWindow::DoGetBestSize() that a class can override if it wants to calculate
  44     its own best size based on its content, however notice that usually it is
  45     more convenient to override DoGetBestClientSize(), see below.
  46
  47 @li @b "Best Client Size": this is simply the client size corresponding to the
  48     best window size. When the fitting size for the given contents is computed,
  49     it will usually be the client size and the size of the borders needs to be
  50     added to obtain the full best size. For this reason, it's preferable to
  51     override DoGetBestClientSize() and let DoGetBestSize() compute the full
  52     best size.
  53
  54 @li @b "Minimal Size": the minimal size of a widget is a size that is normally explicitly
  55     set by the programmer either with the wxWindow::SetMinSize() method or with the
  56     wxWindow::SetSizeHints() method.
  57     Most controls will also set the minimal size to the size given in the control's
  58     constructor if a non-default value is passed.
  59     Top-level windows such as wxFrame will not allow the user to resize the frame below
  60     the minimal size.
  61
  62 @li @b "Maximum Size": just like for the minimal size, the maximum size is normally
  63     explicitly set by the programmer with the wxWindow::SetMaxSize() method or
  64     with wxWindow::SetSizeHints().
  65     Top-level windows such as wxFrame will not allow the user to resize the frame above
  66     the maximum size.
  67
  68 @li @b "Initial Size": the initial size of a widget is the size given to the
  69     constructor of the widget, if any.
  70     As mentioned above most controls will also set this size value as the control's
  71     minimal size. If the size passed to the constructor is the default ::wxDefaultSize,
  72     or if the size is not fully specified (such as wxSize(150,-1)) then most controls
  73     will fill in the missing size components using the best size and will set the
  74     initial size of the control to the resulting size.
  75
  76 @li @b "Virtual Size": the virtual size is the size of the potentially viewable
  77     area of the widget.
  78     The virtual size of a widget may be larger than its actual size and in this
  79     case scrollbars will appear to the let the user 'explore' the full contents
  80     of the widget.
  81     See wxScrolled for more info.
  82
  83
  84 @section overview_windowsizing_func Functions related to sizing
  85
  86 @li wxWindow::GetEffectiveMinSize(): returns a blending of the widget's minimal size
  87     and best size, giving precedence to the minimal size.
  88     For example, if a widget's min size is set to (150, -1) and the best size is
  89     (80, 22) then the best fitting size is (150, 22). If the min size is (50, 20)
  90     then the best fitting size is (50, 20). This method is what is called by the
  91     sizers when determining what the requirements of each item in the sizer is,
  92     and is used for calculating the overall minimum needs of the sizer.
  93
  94 @li wxWindow::SetInitialSize(): this is a little different than the typical size
  95     setters. Rather than just setting an "initial size" attribute it actually sets
  96     the minimal size to the value passed in, blends that value with the best size,
  97     and then sets the size of the widget to be the result.
  98     So you can consider this method to be a "Smart SetSize". This method is what is
  99     called by the constructor of most controls to set the minimal size and the initial
 100     size of the control.
 101
 102 @li wxWindow::Fit(): this method sets the size of a window to fit around its children.
 103     If it has no children then nothing is done, if it does have children then the size
 104     of the window is set to the window's best size.
 105
 106 @li wxSizer::Fit(): this sets the size of the window to be large enough to
 107     accommodate the minimum size needed by the sizer, (along with a few other
 108     constraints...). If the sizer is the one that is assigned to the window then
 109     this should be equivalent to wxWindow::Fit().
 110
 111 @li wxSizer::Layout(): recalculates the minimum space needed by each item in the
 112     sizer, and then lays out the items within the space currently allotted to the sizer.
 113
 114 @li wxWindow::Layout(): if the window has a sizer then it sets the space given to
 115     the sizer to the current size of the window, which results in a call to
 116     wxSizer::Layout(). If the window has layout constraints instead of a sizer then
 117     the constraints algorithm is run. The @c Layout() method is what is called by
 118     the default @c EVT_SIZE handler for container windows.
 119
 120 */