Amebis/wxWidgets
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

better integration of the window sizing overview in the wx docs; revised it removing python-like syntaxes; misc fixes to the wording

Browse Source 
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@53081 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Francesco Montorsi
2008-04-07 17:41:22 +00:00
parent e84fd6a105
commit cded6aa1c3
2 changed files with 111 additions and 90 deletions
Download Patch File Download Diff File Expand all files Collapse all files

134
docs/doxygen/overviews/windowsizing.h
View File

@@ -8,93 +8,87 @@
/** /**
@page overview_windowsizing Window Sizes @page overview_windowsizing Window Sizing Overview
It can sometimes be confusing to keep track of the various size-related 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 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 with sizers. This document will attempt to clear the fog a little, and give
some simple explanations of things. some simple explanations of things.
@b BestSize: The best size of a widget depends on what kind of widget it is, Glossary:
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. @li @b "Best Size": the best size of a widget depends on what kind of widget it is,
-# Otherwise if the window has layout constraints then that is used to and usually also on the contents of the widget. For example a wxListBox's best
calculate the best size. size will be calculated based on how many items it has, up to a certain limit,
-# Otherwise if the window has children then the best size is set to be large or a wxButton's best size will be calculated based on its label size, but
enough to show all the children. normally won't be smaller than the platform default button size (unless a style
-# Otherwise if there are no children then the window's min size will be used flag overrides that).
for the best size. There is a special virtual method in the C++ window classes called
-# Otherwise if there is no min size set, then the current size is used for the wxWindow::DoGetBestSize() that a class needs to override if it wants to calculate
best size. its own best size based on its content.
@b MinSize: The min size of a widget is a size that is normally explicitly set @li @b "Min Size": the minimal size of a widget is a size that is normally explicitly set
by the programmer either with the @c SetMinSize() method or the by the programmer either with the wxWindow::SetMinSize() method or with the
@c SetSizeHints() method. Most controls will also set the min size to the size wxWindow::SetSizeHints() method.
given in the control's constructor if a non-default value is passed. Top-level Most controls will also set the min size to the size given in the control's
windows such as wxFrame will not allow the user to resize the frame below the constructor if a non-default value is passed.
min size. Top-level windows such as wxFrame will not allow the user to resize the frame below
the minimal size.
@b Size: The size of a widget can be explicitly set or fetched with the @li @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 wxWindow::SetSize() or wxWindow::GetSize() methods.
widget is currently using on screen and is the way to change the size of This size value is the size that the widget is currently using on screen and is
something that is not being managed by a sizer. 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 @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 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 @c EVT_PAINT event. If a widget doesn't have a border then its client size is
the same as its size. the same as its size.
@b InitialSize: The initial size of a widget is the size given to the @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 constructor of the widget, if any.
set this size value as the control's min size. If the size passed to the As mentioned above most controls will also set this size value as the control's
constructor is the default @c wxDefaultSize, or if the size is not fully minimal size. If the size passed to the constructor is the default ::wxDefaultSize,
specified (such as wxSize(150,-1)) then most controls will fill in the missing or if the size is not fully specified (such as wxSize(150,-1)) then most controls
size components using the best size and will set the initial size of the will fill in the missing size components using the best size and will set the
control to the resulting size. 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 Functions related to sizing:
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 @li wxWindow::GetEffectiveMinSize(): returns a blending of the widget's minimal size
its children. If it has no children then nothing is done, if it does have and best size, giving precedence to the minimal size.
children then the size of the window is set to the window's best 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 sizer.Fit(window): This sets the size of the window to be large enough to @li wxWindow::SetInitialSize(): this is a little different than the typical size
accommodate the minimum size needed by the sizer, (along with a few other setters. Rather than just setting an "initial size" attribute it actually sets
constraints...) If the sizer is the one that is assigned to the window then the minimal size to the value passed in, blends that value with the best size,
this should be equivalent to @c window.Fit(). 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.
@b sizer.Layout(): Recalculates the minimum space needed by each item in the @li wxWindow::Fit(): this method sets the size of a window to fit around its children.
sizer, and then lays out the items within the space currently allotted to the If it has no children then nothing is done, if it does have children then the size
sizer. of the window is set to the window's best size.
@b window.Layout(): If the window has a sizer then it sets the space given to @li wxSizer::Fit(): this sets the size of the window to be large enough to
the sizer to the current size of the window, which results in a call to accommodate the minimum size needed by the sizer, (along with a few other
@c sizer.Layout(). If the window has layout constraints instead of a sizer then constraints...). If the sizer is the one that is assigned to the window then
the constraints algorithm is run. The @c Layout() method is what is called by this should be equivalent to wxWindow::Fit().
the default @c EVT_SIZE handler for container windows.
@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.
*/ */

67
interface/window.h
View File

@@ -445,6 +445,20 @@ public:
Gets the size which best suits the window: for a control, it would be 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 the minimal size which doesn't truncate the control, for a panel - the
same size as it would have after a call to Fit(). 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; virtual wxSize DoGetBestSize() const;
@@ -544,13 +558,22 @@ public:
wxWindow* parent = NULL); wxWindow* parent = NULL);
/** /**
Sizes the window so that it fits around its subwindows. This function won't do Sizes the window so that it fits around its subwindows.
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
instead of calling Fit. 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().
@see @ref overview_windowsizing
*/ */
virtual void Fit(); virtual void Fit();
@@ -596,8 +619,7 @@ public:
wxAccessible* GetAccessible(); wxAccessible* GetAccessible();
/** /**
This method is deprecated, use GetEffectiveMinSize() This method is deprecated, use GetEffectiveMinSize() instead.
instead.
*/ */
wxSize GetAdjustedBestSize() const; wxSize GetAdjustedBestSize() const;
@@ -771,11 +793,11 @@ public:
wxDropTarget* GetDropTarget() const; wxDropTarget* GetDropTarget() const;
/** /**
Merges the window's best size into the min size and returns the Merges the window's best size into the min size and returns the result.
result. This is the value used by sizers to determine the appropriate This is the value used by sizers to determine the appropriate
ammount of space to allocate for the widget. ammount of space to allocate for the widget.
@see GetBestSize(), SetInitialSize() @see GetBestSize(), SetInitialSize(), @ref overview_windowsizing
*/ */
wxSize GetEffectiveMinSize() const; wxSize GetEffectiveMinSize() const;
@@ -1375,9 +1397,11 @@ public:
/** /**
Invokes the constraint-based layout algorithm or the sizer-based algorithm Invokes the constraint-based layout algorithm or the sizer-based algorithm
for this window. for this window.
See SetAutoLayout(): when auto
layout is on, this function gets called automatically when the window is See SetAutoLayout(): when auto layout is on, this function gets called automatically
resized. when the window is resized.
@see @ref overview_windowsizing
*/ */
void Layout(); void Layout();
@@ -2055,15 +2079,18 @@ public:
/** /**
A @e smart SetSize that will fill in default size components with the 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 window's @e best size values.
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 Also sets the window's minsize to the value passed in for use with sizers.
size instead of the results of GetBestSize to determine the minimum This means that if a full or partial size is passed to this function then
needs of the window for layout. 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 Most controls will use this to set their initial size, and their min
size to the passed in value (if any.) 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); void SetInitialSize(const wxSize& size = wxDefaultSize);