/**
-@page overview_windowsizing Window Sizes
+@page overview_windowsizing Window Sizing Overview
It can sometimes be confusing to keep track of the various size-related
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.
-@b 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 wxListBox's best
-size will be calculated based on how many items it has, up to a certain limit,
-or a wxButton's best size will be calculated based on its label size, but
-normally won't be smaller than the platform default button size (unless a style
-flag overrides that). Get the picture? There is a special virtual method in the
-C++ window classes called @c DoGetBestSize() that a class needs to override if
-it wants to calculate its own best size based on its content. The default
-@c DoGetBestSize() is designed for use in container windows, such as wxPanel,
-and works something like this:
-
--# If the window has a sizer then it is used to calculate the best size.
--# Otherwise if the window has layout constraints then that is used to
- calculate the best size.
--# Otherwise if the window has children then the best size is set to be large
- enough to show all the children.
--# Otherwise if there are no children then the window's min size will be used
- for the best size.
--# Otherwise if there is no min size set, then the current size is used for the
- best size.
-
-@b MinSize: The min size of a widget is a size that is normally explicitly set
-by the programmer either with the @c SetMinSize() method or the
-@c SetSizeHints() method. Most controls will also set the min 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
-min size.
-
-@b Size: The size of a widget can be explicitly set or fetched with the
-@c SetSize() or @c 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.
-
-@b 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
-@c EVT_PAINT event. If a widget doesn't have a border then its client size is
-the same as its size.
-
-@b 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 @c wxDefaultSize, or if the size is not fully
-specified (such as 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.
-
-@b GetEffectiveMinSize(): (formerly @c 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.
-
-@b SetInitialSize(size): (formerly @c 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.
-
-@b window.Fit(): The @c 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.
-
-@b sizer.Fit(window): This sets the size of the window to be large enough to
-accommodate 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 @c window.Fit().
-
-@b sizer.Layout(): Recalculates the minimum space needed by each item in the
-sizer, and then lays out the items within the space currently allotted to the
-sizer.
-
-@b 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
-@c sizer.Layout(). If the window has layout constraints instead of a sizer then
-the constraints algorithm is run. The @c Layout() method is what is called by
-the default @c EVT_SIZE handler for container windows.
+Glossary:
+
+@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,
+ or a wxButton's best size will be calculated based on its label size, but
+ 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::SetSizeHints() method.
+ Most controls will also set the min 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 "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
+ minimal size. If the size passed to the constructor is the default ::wxDefaultSize,
+ or if the size is not fully specified (such as 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.
+
+
+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.
+ 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.
+
+@li wxWindow::SetInitialSize(): this is a little different than the typical size
+ setters. Rather than just setting an "initial size" attribute it actually sets
+ the minimal size 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 minimal size and the initial
+ size of the control.
+
+@li wxWindow::Fit(): this 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.
+
+@li wxSizer::Fit(): this sets the size of the window to be large enough to
+ accommodate 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 wxWindow::Fit().
+
+@li wxSizer::Layout(): recalculates the minimum space needed by each item in the
+ sizer, and then lays out the items within the space currently allotted to the sizer.
+
+@li wxWindow::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
+ wxSizer::Layout(). If the window has layout constraints instead of a sizer then
+ the constraints algorithm is run. The @c Layout() method is what is called by
+ the default @c EVT_SIZE handler for container windows.
*/
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().
+
+ The default implementation of this function is designed for use in container
+ windows, such as wxPanel, and works something like this:
+ -# If the window has a sizer then it is used to calculate the best size.
+ -# Otherwise if the window has layout constraints then those are used to
+ calculate the best size.
+ -# Otherwise if the window has children then the best size is set to be large
+ enough to show all the children.
+ -# Otherwise if there are no children then the window's minimal size will be
+ used as its best size.
+ -# Otherwise if there is no minimal size set, then the current size is used
+ for the best size.
+
+ @see @ref overview_windowsizing
*/
virtual wxSize DoGetBestSize() const;
wxWindow* parent = NULL);
/**
- Sizes the window so that it fits around its subwindows. This function won't do
- anything if there are no subwindows and will only really work correctly if
- sizers are used for the subwindows layout. Also, if the window has exactly one
- subwindow it is better (faster and the result is more precise as Fit adds some
- margin to account for fuzziness of its calculations) to call
+ Sizes the window so that it fits around its subwindows.
+
+ This function won't do anything if there are no subwindows and will only really
+ work correctly if sizers are used for the subwindows layout.
+
+ Also, if the window has exactly one subwindow it is better (faster and the result
+ is more precise as Fit() adds some margin to account for fuzziness of its calculations)
+ to call:
+
+ @begincode
+ window->SetClientSize(child->GetSize());
+ @endcode
+
+ instead of calling Fit().
- instead of calling Fit.
+ @see @ref overview_windowsizing
*/
virtual void Fit();
wxAccessible* GetAccessible();
/**
- This method is deprecated, use GetEffectiveMinSize()
- instead.
+ This method is deprecated, use GetEffectiveMinSize() instead.
*/
wxSize GetAdjustedBestSize() const;
wxDropTarget* GetDropTarget() const;
/**
- Merges the window's best size into the min size and returns the
- result. This is the value used by sizers to determine the appropriate
+ Merges the window's best size into the min size and returns the result.
+ This is the value used by sizers to determine the appropriate
ammount of space to allocate for the widget.
- @see GetBestSize(), SetInitialSize()
+ @see GetBestSize(), SetInitialSize(), @ref overview_windowsizing
*/
wxSize GetEffectiveMinSize() const;
/**
Invokes the constraint-based layout algorithm or the sizer-based algorithm
for this window.
- See SetAutoLayout(): when auto
- layout is on, this function gets called automatically when the window is
- resized.
+
+ See SetAutoLayout(): when auto layout is on, this function gets called automatically
+ when the window is resized.
+
+ @see @ref overview_windowsizing
*/
void Layout();
/**
A @e smart SetSize that will fill in default size components with the
- window's @e best size values. Also sets the window's minsize to
- the value passed in for use with sizers. This means that if a full or
- partial size is passed to this function then the sizers will use that
- size instead of the results of GetBestSize to determine the minimum
- needs of the window for layout.
+ window's @e best size values.
+
+ Also sets the window's minsize to the value passed in for use with sizers.
+ This means that if a full or partial size is passed to this function then
+ the sizers will use that size instead of the results of GetBestSize() to
+ determine the minimum needs of the window for layout.
+
Most controls will use this to set their initial size, and their min
size to the passed in value (if any.)
- @see SetSize(), GetBestSize(), GetEffectiveMinSize()
+ @see SetSize(), GetBestSize(), GetEffectiveMinSize(),
+ @ref overview_windowsizing
*/
void SetInitialSize(const wxSize& size = wxDefaultSize);
projects / wxWidgets.git / commitdiff
