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

More doxygen topic overview cleanup.

Browse Source 
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@52133 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Bryan Petty
2008-02-27 06:48:16 +00:00
parent 07fa8f78f8
commit 58d0deaac1
3 changed files with 527 additions and 515 deletions
Download Patch File Download Diff File Expand all files Collapse all files

146
docs/doxygen/overviews/runtimeclass.h
View File

@@ -1,5 +1,5 @@
///////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////
// Name: runtimeclass // Name: runtimeclass.h
// Purpose: topic overview // Purpose: topic overview
// Author: wxWidgets team // Author: wxWidgets team
// RCS-ID: $Id$ // RCS-ID: $Id$
@@ -8,77 +8,98 @@
/*! /*!
@page runtimeclass_overview Runtime class information (aka RTTI) overview @page overview_runtimeclass Runtime Class Information (RTTI)
@li @ref overview_runtimeclass_intro
@li @ref overview_runtimeclass_classinfo
@li @ref overview_runtimeclass_example
@seealso
@li wxObject
@li wxClassInfo
<hr>
@section overview_runtimeclass_intro Introduction
Classes: #wxObject, #wxClassInfo.
One of the failings of C++ used to be that no run-time information was provided One of the failings of C++ used to be that no run-time information was provided
about a class and its position in the inheritance hierarchy. about a class and its position in the inheritance hierarchy. Another, which
Another, which still persists, is that instances of a class cannot be created still persists, is that instances of a class cannot be created just by knowing
just by knowing the name of a class, which makes facilities such as persistent the name of a class, which makes facilities such as persistent storage hard to
storage hard to implement. implement.
Most C++ GUI frameworks overcome these limitations by means of a set of
macros and functions and wxWidgets is no exception. As it originated before the Most C++ GUI frameworks overcome these limitations by means of a set of macros
addition of RTTI to the C++ standard and as support for it is still missing from and functions and wxWidgets is no exception. As it originated before the
some (albeit old) compilers, wxWidgets doesn't (yet) use it, but provides its addition of RTTI to the C++ standard and as support for it is still missing
own macro-based RTTI system. from some (albeit old) compilers, wxWidgets doesn't (yet) use it, but provides
it's own macro-based RTTI system.
In the future, the standard C++ RTTI will be used though and you're encouraged In the future, the standard C++ RTTI will be used though and you're encouraged
to use whenever possible the #wxDynamicCast() macro which, to use whenever possible the wxDynamicCast macro which, for the implementations
for the implementations that support it, is defined just as dynamic_cast and that support it, is defined just as dynamic_cast and uses wxWidgets RTTI for
uses wxWidgets RTTI for all the others. This macro is limited to wxWidgets all the others. This macro is limited to wxWidgets classes only and only works
classes only and only works with pointers (unlike the real dynamic_cast which with pointers (unlike the real dynamic_cast which also accepts references).
also accepts references).
Each class that you wish to be known to the type system should have Each class that you wish to be known to the type system should have a macro
a macro such as DECLARE_DYNAMIC_CLASS just inside the class declaration. such as DECLARE_DYNAMIC_CLASS just inside the class declaration. The macro
The macro IMPLEMENT_DYNAMIC_CLASS should be in the implementation file. IMPLEMENT_DYNAMIC_CLASS should be in the implementation file. Note that these
Note that these are entirely optional; use them if you wish to check object are entirely optional; use them if you wish to check object types, or create
types, or create instances of classes using the class name. However, instances of classes using the class name. However, it is good to get into the
it is good to get into the habit of adding these macros for all classes. habit of adding these macros for all classes.
Variations on these #macros are used for multiple inheritance, and abstract
Variations on these macros are used for multiple inheritance, and abstract
classes that cannot be instantiated dynamically or otherwise. classes that cannot be instantiated dynamically or otherwise.
DECLARE_DYNAMIC_CLASS inserts a static wxClassInfo declaration into the
class, initialized by IMPLEMENT_DYNAMIC_CLASS. When initialized, the DECLARE_DYNAMIC_CLASS inserts a static wxClassInfo declaration into the class,
wxClassInfo object inserts itself into a linked list (accessed through initialized by IMPLEMENT_DYNAMIC_CLASS. When initialized, the wxClassInfo
wxClassInfo::first and wxClassInfo::next pointers). The linked list object inserts itself into a linked list (accessed through wxClassInfo::first
is fully created by the time all global initialisation is done. and wxClassInfo::next pointers). The linked list is fully created by the time
all global initialisation is done.
IMPLEMENT_DYNAMIC_CLASS is a macro that not only initialises the static IMPLEMENT_DYNAMIC_CLASS is a macro that not only initialises the static
wxClassInfo member, but defines a global function capable of creating a wxClassInfo member, but defines a global function capable of creating a dynamic
dynamic object of the class in question. A pointer to this function is object of the class in question. A pointer to this function is stored in
stored in wxClassInfo, and is used when an object should be created wxClassInfo, and is used when an object should be created dynamically.
dynamically.
wxObject::IsKindOf uses the linked list of wxObject::IsKindOf uses the linked list of wxClassInfo. It takes a wxClassInfo
wxClassInfo. It takes a wxClassInfo argument, so use CLASSINFO(className) argument, so use CLASSINFO(className) to return an appropriate wxClassInfo
to return an appropriate wxClassInfo pointer to use in this function. pointer to use in this function.
The function #wxCreateDynamicObject can be used
to construct a new object of a given type, by supplying a string name. The function wxCreateDynamicObject can be used to construct a new object of a
If you have a pointer to the wxClassInfo object instead, then you given type, by supplying a string name. If you have a pointer to the
can simply call wxClassInfo::CreateObject. wxClassInfo object instead, then you can simply call wxClassInfo::CreateObject.
#wxClassInfo
#Example
@section wxclassinfooverview wxClassInfo @section overview_runtimeclass_classinfo wxClassInfo
#Runtime class information (aka RTTI) overview This class stores meta-information about classes. An application may use macros
Class: #wxClassInfo such as DECLARE_DYNAMIC_CLASS and IMPLEMENT_DYNAMIC_CLASS to record run-time
This class stores meta-information about classes. An application information about a class, including:
may use macros such as DECLARE_DYNAMIC_CLASS and IMPLEMENT_DYNAMIC_CLASS
to record run-time information about a class, including: @li It's position in the inheritance hierarchy.
@li The base class name(s) (up to two base classes are permitted).
@li A string representation of the class name.
@li A function that can be called to construct an instance of this class.
The DECLARE_... macros declare a static wxClassInfo variable in a class, which
is initialized by macros of the form IMPLEMENT_... in the implementation C++
file. Classes whose instances may be constructed dynamically are given a global
constructor function which returns a new object.
You can get the wxClassInfo for a class by using the CLASSINFO macro, e.g.
CLASSINFO(wxFrame). You can get the wxClassInfo for an object using
wxObject::GetClassInfo.
@seeaslso
@li wxObject
@li wxCreateDynamicObject
its position in the inheritance hierarchy; @section overview_runtimeclass_example Example
the base class name(s) (up to two base classes are permitted);
a string representation of the class name;
a function that can be called to construct an instance of this class.
The DECLARE_... macros declare a static wxClassInfo variable in a class, which is initialized
by macros of the form IMPLEMENT_... in the implementation C++ file. Classes whose instances may be
constructed dynamically are given a global constructor function which returns a new object.
You can get the wxClassInfo for a class by using the CLASSINFO macro, e.g. CLASSINFO(wxFrame).
You can get the wxClassInfo for an object using wxObject::GetClassInfo.
See also #wxObject and #wxCreateDynamicObject.
@section runtimeclassinformationexample Example
In a header file frame.h: In a header file frame.h:
@@ -108,4 +129,3 @@
*/ */

177
docs/doxygen/overviews/scrolling.h
View File

@@ -1,5 +1,5 @@
///////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////
// Name: scrolling // Name: scrolling.h
// Purpose: topic overview // Purpose: topic overview
// Author: wxWidgets team // Author: wxWidgets team
// RCS-ID: $Id$ // RCS-ID: $Id$
@@ -8,124 +8,91 @@
/*! /*!
@page scrolling_overview Scrolling overview @page overview_scrolling Scrolling Overview
Classes:
@li wxWindow
@li wxScrolledWindow
@li wxScrollBar
Classes: #wxWindow, #wxScrolledWindow, #wxIcon, #wxScrollBar.
Scrollbars come in various guises in wxWidgets. All windows have the potential Scrollbars come in various guises in wxWidgets. All windows have the potential
to show a vertical scrollbar and/or a horizontal scrollbar: it is a basic capability of a window. to show a vertical scrollbar and/or a horizontal scrollbar: it is a basic
However, in practice, not all windows do make use of scrollbars, such as a single-line wxTextCtrl. capability of a window. However, in practice, not all windows do make use of
Because any class derived from #wxWindow may have scrollbars, scrollbars, such as a single-line wxTextCtrl.
there are functions to manipulate the scrollbars and event handlers to intercept
scroll events. But just because a window generates a scroll event, doesn't mean Because any class derived from wxWindow may have scrollbars, there are
that the window necessarily handles it and physically scrolls the window. The base class functions to manipulate the scrollbars and event handlers to intercept scroll
wxWindow in fact doesn't have any default functionality to handle scroll events. events. But just because a window generates a scroll event, doesn't mean that
If you created a wxWindow object with scrollbars, and then clicked on the scrollbars, nothing the window necessarily handles it and physically scrolls the window. The base
at all would happen. This is deliberate, because the @e interpretation of scroll class wxWindow in fact doesn't have any default functionality to handle scroll
events varies from one window class to another. events. If you created a wxWindow object with scrollbars, and then clicked on
#wxScrolledWindow (formerly wxCanvas) is an example of a window that the scrollbars, nothing at all would happen. This is deliberate, because the
adds functionality to make scrolling really work. It assumes that scrolling happens in @e interpretation of scroll events varies from one window class to another.
consistent units, not different-sized jumps, and that page size is represented
by the visible portion of the window. It is suited to drawing applications, but perhaps wxScrolledWindow (formerly wxCanvas) is an example of a window that adds
not so suitable for a sophisticated editor in which the amount scrolled may vary according functionality to make scrolling really work. It assumes that scrolling happens
to the size of text on a given line. For this, you would derive from wxWindow and in consistent units, not different-sized jumps, and that page size is
implement scrolling yourself. #wxGrid is an example of a class represented by the visible portion of the window. It is suited to drawing
that implements its own scrolling, largely because columns and rows can vary in size. applications, but perhaps not so suitable for a sophisticated editor in which
@b The scrollbar model the amount scrolled may vary according to the size of text on a given line. For
The function wxWindow::SetScrollbar gives a clue about this, you would derive from wxWindow and implement scrolling yourself. wxGrid
the way a scrollbar is modeled. This function takes the following arguments: is an example of a class that implements its own scrolling, largely because
columns and rows can vary in size.
@section overview_scrolling_model The Scrollbar Model
The function wxWindow::SetScrollbar gives a clue about the way a scrollbar is
modeled. This function takes the following arguments:
@beginTable
@row2col{ @c orientation , Which scrollbar: wxVERTICAL or wxHORIZONTAL. }
@row2col{ @c position , The position of the scrollbar in scroll units. }
@row2col{ @c visible , The size of the visible portion of the scrollbar,
in scroll units. }
@row2col{ @c range , The maximum position of the scrollbar. }
@row2col{ @c refresh , Whether the scrollbar should be repainted. }
@endTable
@c orientation determines whether we're talking about the built-in horizontal
or vertical scrollbar.
@c position is simply the position of the 'thumb' (the bit you drag to scroll
around). It is given in scroll units, and so is relative to the total range of
the scrollbar.
@c visible gives the number of scroll units that represents the portion of the
window currently visible. Normally, a scrollbar is capable of indicating this
visually by showing a different length of thumb.
@c range is the maximum value of the scrollbar, where zero is the start
position. You choose the units that suit you, so if you wanted to display text
that has 100 lines, you would set this to 100. Note that this doesn't have to
correspond to the number of pixels scrolled - it is up to you how you actually
show the contents of the window.
@c refresh just indicates whether the scrollbar should be repainted immediately
or not.
@section overview_scrolling_example An Example
Let's say you wish to display 50 lines of text, using the same font. The window
orientation is sized so that you can only see 16 lines at a time. You would use:
Which scrollbar: wxVERTICAL or wxHORIZONTAL.
position
The position of the scrollbar in scroll units.
visible
The size of the visible portion of the scrollbar, in scroll units.
range
The maximum position of the scrollbar.
refresh
Whether the scrollbar should be repainted.
@e orientation determines whether we're talking about
the built-in horizontal or vertical scrollbar.
@e position is simply the position of the 'thumb' (the bit you drag to scroll around).
It is given in scroll units, and so is relative to the total range of the scrollbar.
@e visible gives the number of scroll units that represents the portion of the
window currently visible. Normally, a scrollbar is capable of indicating this visually
by showing a different length of thumb.
@e range is the maximum value of the scrollbar, where zero is the start
position. You choose the units that suit you,
so if you wanted to display text that has 100 lines, you would set this to 100.
Note that this doesn't have to correspond to the number of pixels scrolled - it is
up to you how you actually show the contents of the window.
@e refresh just indicates whether the scrollbar should be repainted immediately or not.
@b An example
Let's say you wish to display 50 lines of text, using the same font.
The window is sized so that you can only see 16 lines at a time.
You would use:
@code @code
SetScrollbar(wxVERTICAL, 0, 16, 50); SetScrollbar(wxVERTICAL, 0, 16, 50);
@endcode @endcode
Note that with the window at this size, the thumb position can never go above
50 minus 16, or 34. You can determine how many lines are currently visible by
dividing the current view size by the character height in pixels.
Note that with the window at this size, the thumb position can never go
above 50 minus 16, or 34.
You can determine how many lines are currently visible by dividing the current view
size by the character height in pixels.
When defining your own scrollbar behaviour, you will always need to recalculate When defining your own scrollbar behaviour, you will always need to recalculate
the scrollbar settings when the window size changes. You could therefore put your the scrollbar settings when the window size changes. You could therefore put
scrollbar calculations and SetScrollbar your scrollbar calculations and SetScrollbar call into a function named
call into a function named AdjustScrollbars, which can be called initially and also AdjustScrollbars, which can be called initially and also from your wxSizeEvent
from your #wxSizeEvent handler function. handler function.
*/ */

441
docs/doxygen/overviews/sizer.h
View File

@@ -1,5 +1,5 @@
///////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////
// Name: sizer // Name: sizer.h
// Purpose: topic overview // Purpose: topic overview
// Author: wxWidgets team // Author: wxWidgets team
// RCS-ID: $Id$ // RCS-ID: $Id$
@@ -8,240 +8,268 @@
/*! /*!
@page sizer_overview Sizer overview @page overview_sizer Sizer Overview
Classes: #wxSizer, #wxGridSizer, Classes: wxSizer, wxGridSizer, wxFlexGridSizer, wxBoxSizer, wxStaticBoxSizer
#wxFlexGridSizer, #wxBoxSizer,
#wxStaticBoxSizer, Sizers, as represented by the wxSizer class and its descendants in the
#CreateButtonSizer wxWidgets class hierarchy, have become the method of choice to define the
Sizers, as represented by the wxSizer class and its descendants in layout of controls in dialogs in wxWidgets because of their ability to create
the wxWidgets class hierarchy, have become the method of choice to visually appealing dialogs independent of the platform, taking into account
define the layout of controls in dialogs in wxWidgets because of the differences in size and style of the individual controls. Unlike the
their ability to create visually appealing dialogs independent of the original wxWidgets Dialog Editor, editors such as wxDesigner, DialogBlocks,
platform, taking into account the differences in size and style of XRCed and wxWorkshop create dialogs based exclusively on sizers, practically
the individual controls. Unlike the original wxWidgets Dialog Editor, forcing the user to create platform independent layouts without compromises.
editors such as wxDesigner, DialogBlocks, XRCed and wxWorkshop create dialogs based exclusively on sizers,
practically forcing the user to create platform independent layouts without compromises. The next section describes and shows what can be done with sizers. The
The next section describes and shows what can be done with sizers. following sections briefly describe how to program with individual sizer
The following sections briefly describe how to program with individual sizer classes. classes.
For information about the new wxWidgets resource system, which can describe
sizer-based dialogs, see the @ref xrc_overview. For information about the wxWidgets resource system, which can describe
@ref ideabehindsizers_overview sizer-based dialogs, see the @ref overview_xrc.
@ref boxsizerprogramming_overview
@ref gridsizerprogramming_overview @li @ref overview_sizer_idea
@ref flexgridsizerprogramming_overview @li @ref overview_sizer_features
@ref staticboxsizerprogramming_overview @li @ref overview_sizer_hiding
#CreateButtonSizer @li @ref overview_sizer_box
@li @ref overview_sizer_types
@li @ref overview_sizer_button
@section ideabehindsizers The idea behind sizers <hr>
@section overview_sizer_idea The Idea Behind Sizers
The layout algorithm used by sizers in wxWidgets is closely related to layout The layout algorithm used by sizers in wxWidgets is closely related to layout
systems in other GUI toolkits, such as Java's AWT, the GTK toolkit or the Qt toolkit. It is systems in other GUI toolkits, such as Java's AWT, the GTK toolkit or the Qt
based upon the idea of individual subwindows reporting their minimal required toolkit. It is based upon the idea of individual subwindows reporting their
size and their ability to get stretched if the size of the parent window has changed. minimal required size and their ability to get stretched if the size of the
This will most often mean that the programmer does not set the start-up size of parent window has changed. This will most often mean that the programmer does
a dialog, the dialog will rather be assigned a sizer and this sizer not set the start-up size of a dialog, the dialog will rather be assigned a
will be queried about the recommended size. This sizer in turn will query its sizer and this sizer will be queried about the recommended size. This sizer in
children (which can be normal windows, empty space or other sizers) so that turn will query its children (which can be normal windows, empty space or other
a hierarchy of sizers can be constructed. Note that wxSizer does not derive from wxWindow sizers) so that a hierarchy of sizers can be constructed. Note that wxSizer
and thus does not interfere with tab ordering and requires very few resources compared does not derive from wxWindow and thus does not interfere with tab ordering and
to a real window on screen. requires very few resources compared to a real window on screen.
What makes sizers so well fitted for use in wxWidgets is the fact that every control
reports its own minimal size and the algorithm can handle differences in font sizes
or different window (dialog item) sizes on different platforms without problems. For example, if
the standard font as well as the overall design of Linux/GTK widgets requires more space than
on Windows, the initial dialog size will automatically be bigger on Linux/GTK than on Windows.
There are currently five different kinds of sizers available in wxWidgets. Each represents
either a certain way to lay out dialog items in a dialog or it fulfills a special task
such as wrapping a static box around a dialog item (or another sizer). These sizers will
be discussed one by one in the text below. For more detailed information on how to use sizers
programmatically, please refer to the section @ref boxsizerprogramming_overview.
@section sizerscommonfeatures Common features What makes sizers so well fitted for use in wxWidgets is the fact that every
control reports its own minimal size and the algorithm can handle differences
in font sizes or different window (dialog item) sizes on different platforms
without problems. For example, if the standard font as well as the overall
design of Linux/GTK widgets requires more space than on Windows, the initial
dialog size will automatically be bigger on Linux/GTK than on Windows.
All sizers are containers, that is, they are used to lay out one dialog item (or several There are currently five different kinds of sizers available in wxWidgets. Each
dialog items), which they contain. Such items are sometimes referred to as the children represents either a certain way to lay out dialog items in a dialog or it
of the sizer. Independent of how the individual sizers lay out their children, all children fulfills a special task such as wrapping a static box around a dialog item (or
have certain features in common: another sizer). These sizers will be discussed one by one in the text below.
@b A minimal size: This minimal size is usually identical to For more detailed information on how to use sizers programmatically, please
the initial size of the controls and may either be set explicitly in the wxSize field refer to the section @ref overview_sizer_box.
of the control constructor or may be calculated by wxWidgets, typically by setting
@section overview_sizer_features Common Features
All sizers are containers, that is, they are used to lay out one dialog item
(or several dialog items), which they contain. Such items are sometimes
referred to as the children of the sizer. Independent of how the individual
sizers lay out their children, all children have certain features in common:
<b>A minimal size</b>: This minimal size is usually identical to the initial
size of the controls and may either be set explicitly in the wxSize field of
the control constructor or may be calculated by wxWidgets, typically by setting
the height and/or the width of the item to -1. Note that only some controls can the height and/or the width of the item to -1. Note that only some controls can
calculate their size (such as a checkbox) whereas others (such as a listbox) calculate their size (such as a checkbox) whereas others (such as a listbox)
don't have any natural width or height and thus require an explicit size. Some controls don't have any natural width or height and thus require an explicit size. Some
can calculate their height, but not their width (e.g. a single line text control): controls can calculate their height, but not their width (e.g. a single line
text control):
@image html sizer03.bmp
@image html sizer04.bmp
@image html sizer05.bmp
<b>A border</b>: The border is just empty space and is used to separate dialog
items in a dialog. This border can either be all around, or at any combination
of sides such as only above and below the control. The thickness of this border
must be set explicitly, typically 5 points. The following samples show dialogs
with only one dialog item (a button) and a border of 0, 5, and 10 pixels around
the button:
@image html sizer00.bmp
@image html sizer01.bmp
@image html sizer02.bmp
@b A border: The border is just empty space and is used to separate dialog items <b>An alignment</b>: Often, a dialog item is given more space than its minimal
in a dialog. This border can either be all around, or at any combination of sides size plus its border. Depending on what flags are used for the respective
such as only above and below the control. The thickness of this border must be set dialog item, the dialog item can be made to fill out the available space
explicitly, typically 5 points. The following samples show dialogs with only one entirely, i.e. it will grow to a size larger than the minimal size, or it will
dialog item (a button) and a border of 0, 5, and 10 pixels around the button: be moved to either the centre of the available space or to either side of the
space. The following sample shows a listbox and three buttons in a horizontal
box sizer; one button is centred, one is aligned at the top, one is aligned at
the bottom:
@image html sizer06.bmp
<b>A stretch factor</b>: If a sizer contains more than one child and it is
offered more space than its children and their borders need, the question
arises how to distribute the surplus space among the children. For this
purpose, a stretch factor may be assigned to each child, where the default
value of 0 indicates that the child will not get more space than its requested
minimum size. A value of more than zero is interpreted in relation to the sum
of all stretch factors in the children of the respective sizer, i.e. if two
children get a stretch factor of 1, they will get half the extra space each
<em>independent of whether one control has a minimal sizer inferior to the
other or not</em>. The following sample shows a dialog with three buttons, the
first one has a stretch factor of 1 and thus gets stretched, whereas the other
two buttons have a stretch factor of zero and keep their initial width:
@image html sizer07.bmp
@b An alignment: Often, a dialog item is given more space than its minimal size
plus its border. Depending on what flags are used for the respective dialog
item, the dialog item can be made to fill out the available space entirely, i.e.
it will grow to a size larger than the minimal size, or it will be moved to either
the centre of the available space or to either side of the space. The following
sample shows a listbox and three buttons in a horizontal box sizer; one button
is centred, one is aligned at the top, one is aligned at the bottom:
@b A stretch factor: If a sizer contains more than one child and it is offered
more space than its children and their borders need, the question arises how to
distribute the surplus space among the children. For this purpose, a stretch
factor may be assigned to each child, where the default value of 0 indicates that the child
will not get more space than its requested minimum size. A value of more than zero
is interpreted in relation to the sum of all stretch factors in the children
of the respective sizer, i.e. if two children get a stretch factor of 1, they will
get half the extra space each @e independent of whether one control has a minimal
sizer inferior to the other or not. The following sample shows a dialog with
three buttons, the first one has a stretch factor of 1 and thus gets stretched,
whereas the other two buttons have a stretch factor of zero and keep their
initial width:
Within wxDesigner, this stretch factor gets set from the @e Option menu. Within wxDesigner, this stretch factor gets set from the @e Option menu.
@section sizershiding Hiding controls using sizers
You can hide controls contained in sizers the same way you would hide any control, @section overview_sizer_hiding Hiding Controls Using Sizers
using the wxWindow::Show method.
However, wxSizer also offers a separate method which can tell the sizer not to You can hide controls contained in sizers the same way you would hide any
consider that control in its size calculations. To hide a window using the sizer, control, using the wxWindow::Show method. However, wxSizer also offers a
call wxSizer::Show. You must then call Layout on the sizer separate method which can tell the sizer not to consider that control in its
to force an update. size calculations. To hide a window using the sizer, call wxSizer::Show. You
must then call Layout on the sizer to force an update.
This is useful when hiding parts of the interface, since you can avoid removing This is useful when hiding parts of the interface, since you can avoid removing
the controls from the sizer and having to add them back later. the controls from the sizer and having to add them back later.
Note: This is supported only by wxBoxSizer and wxFlexGridSizer.
@b wxBoxSizer @note This is supported only by wxBoxSizer and wxFlexGridSizer.
#wxBoxSizer can lay out its children either vertically
or horizontally, depending on what flag is being used in its constructor. @subsection overview_sizer_hiding_box wxBoxSizer
When using a vertical sizer, each child can be centered, aligned to the
right or aligned to the left. Correspondingly, when using a horizontal wxBoxSizer can lay out its children either vertically or horizontally,
sizer, each child can be centered, aligned at the bottom or aligned at depending on what flag is being used in its constructor. When using a vertical
the top. The stretch factor described in the last paragraph is used sizer, each child can be centered, aligned to the right or aligned to the left.
for the main orientation, i.e. when using a horizontal box sizer, the Correspondingly, when using a horizontal sizer, each child can be centered,
stretch factor determines how much the child can be stretched horizontally. aligned at the bottom or aligned at the top. The stretch factor described in
The following sample shows the same dialog as in the last sample, the last paragraph is used for the main orientation, i.e. when using a
only the box sizer is a vertical box sizer now: horizontal box sizer, the stretch factor determines how much the child can be
stretched horizontally. The following sample shows the same dialog as in the
last sample, only the box sizer is a vertical box sizer now:
@image html sizer08.bmp
@subsection overview_sizer_hiding_static wxStaticBoxSizer
wxStaticBoxSixer is the same as a wxBoxSizer, but surrounded by a static box.
Here is a sample:
@image html sizer09.bmp
@subsection overview_sizer_hiding_grid wxGridSizer
wxGridSizer is a two-dimensional sizer. All children are given the same size,
which is the minimal size required by the biggest child, in this case the text
control in the left bottom border. Either the number of columns or the number
or rows is fixed and the grid sizer will grow in the respectively other
orientation if new children are added:
@image html sizer10.bmp
For programming information, see wxGridSizer.
@subsection overview_sizer_hiding_flexgrid wxFlexGridSizer
Another two-dimensional sizer derived from wxGridSizer. The width of each
column and the height of each row are calculated individually according to the
minimal requirements from the respectively biggest child. Additionally, columns
and rows can be declared to be stretchable if the sizer is assigned a size
different from the one it requested. The following sample shows the same dialog
as the one above, but using a flex grid sizer:
@image html sizer11.bmp
@section overview_sizer_box Programming with wxBoxSizer
@b wxStaticBoxSizer The basic idea behind a wxBoxSizer is that windows will most often be laid out
#wxStaticBoxSixer is the same as a wxBoxSizer, but surrounded by a in rather simple basic geometry, typically in a row or a column or several
static box. Here is a sample: hierarchies of either.
As an example, we will construct a dialog that will contain a text field at the
top and two buttons at the bottom. This can be seen as a top-hierarchy column
with the text at the top and buttons at the bottom and a low-hierarchy row with
an OK button to the left and a Cancel button to the right. In many cases
(particularly dialogs under Unix and normal frames) the main window will be
resizable by the user and this change of size will have to get propagated to
its children. In our case, we want the text area to grow with the dialog,
whereas the button shall have a fixed size. In addition, there will be a thin
border around all controls to make the dialog look nice and - to make matter
worse - the buttons shall be centred as the width of the dialog changes.
It is the unique feature of a box sizer, that it can grow in both directions
@b wxGridSizer (height and width) but can distribute its growth in the main direction
#wxGridSizer is a two-dimensional sizer. All children are given the (horizontal for a row) @e unevenly among its children. In our example case, the
same size, which is the minimal size required by the biggest child, in vertical sizer is supposed to propagate all its height changes to only the text
this case the text control in the left bottom border. Either the number area, not to the button area. This is determined by the @e proportion parameter
of columns or the number or rows is fixed and the grid sizer will grow when adding a window (or another sizer) to a sizer. It is interpreted as a
in the respectively other orientation if new children are added: weight factor, i.e. it can be zero, indicating that the window may not be
resized at all, or above zero. If several windows have a value above zero, the
value is interpreted relative to the sum of all weight factors of the sizer, so
when adding two windows with a value of 1, they will both get resized equally
For programming information, see #wxGridSizer. much and each half as much as the sizer owning them. Then what do we do when a
@b wxFlexGridSizer column sizer changes its width? This behaviour is controlled by @e flags (the
Another two-dimensional sizer derived from second parameter of the Add() function): Zero or no flag indicates that the
wxGridSizer. The width of each column and the height of each row window will preserve it is original size, wxGROW flag (same as wxEXPAND) forces
are calculated individually according to the minimal requirements the window to grow with the sizer, and wxSHAPED flag tells the window to change
from the respectively biggest child. Additionally, columns and it is size proportionally, preserving original aspect ratio. When wxGROW flag
rows can be declared to be stretchable if the sizer is assigned is not used, the item can be aligned within available space. wxALIGN_LEFT,
a size different from the one it requested. The following sample shows wxALIGN_TOP, wxALIGN_RIGHT, wxALIGN_BOTTOM, wxALIGN_CENTER_HORIZONTAL and
the same dialog as the one above, but using a flex grid sizer: wxALIGN_CENTER_VERTICAL do what they say. wxALIGN_CENTRE (same as
wxALIGN_CENTER) is defined as (wxALIGN_CENTER_HORIZONTAL |
@section boxsizerprogramming Programming with wxBoxSizer
The basic idea behind a #wxBoxSizer is that windows will most often be laid out in rather
simple basic geometry, typically in a row or a column or several hierarchies of either.
As an example, we will construct a dialog that will contain a text field at the top and
two buttons at the bottom. This can be seen as a top-hierarchy column with the text at
the top and buttons at the bottom and a low-hierarchy row with an OK button to the left
and a Cancel button to the right. In many cases (particularly dialogs under Unix and
normal frames) the main window will be resizable by the user and this change of size
will have to get propagated to its children. In our case, we want the text area to grow
with the dialog, whereas the button shall have a fixed size. In addition, there will be
a thin border around all controls to make the dialog look nice and - to make matter worse -
the buttons shall be centred as the width of the dialog changes.
It is the unique feature of a box sizer, that it can grow in both directions (height and
width) but can distribute its growth in the main direction (horizontal for a row) @e unevenly
among its children. In our example case, the vertical sizer is supposed to propagate all its
height changes to only the text area, not to the button area. This is determined by the @e proportion parameter
when adding a window (or another sizer) to a sizer. It is interpreted
as a weight factor, i.e. it can be zero, indicating that the window may not be resized
at all, or above zero. If several windows have a value above zero, the value is interpreted
relative to the sum of all weight factors of the sizer, so when adding two windows with
a value of 1, they will both get resized equally much and each half as much as the sizer
owning them. Then what do we do when a column sizer changes its width? This behaviour is
controlled by @e flags (the second parameter of the Add() function): Zero or no flag
indicates that the window will preserve it is original size, wxGROW flag (same as wxEXPAND)
forces the window to grow with the sizer, and wxSHAPED flag tells the window to change it is
size proportionally, preserving original aspect ratio. When wxGROW flag is not used,
the item can be aligned within available space. wxALIGN_LEFT, wxALIGN_TOP, wxALIGN_RIGHT,
wxALIGN_BOTTOM, wxALIGN_CENTER_HORIZONTAL and wxALIGN_CENTER_VERTICAL do what they say.
wxALIGN_CENTRE (same as wxALIGN_CENTER) is defined as (wxALIGN_CENTER_HORIZONTAL |
wxALIGN_CENTER_VERTICAL). Default alignment is wxALIGN_LEFT | wxALIGN_TOP. wxALIGN_CENTER_VERTICAL). Default alignment is wxALIGN_LEFT | wxALIGN_TOP.
As mentioned above, any window belonging to a sizer may have a border, and it can be specified
which of the four sides may have this border, using the wxTOP, wxLEFT, wxRIGHT and wxBOTTOM As mentioned above, any window belonging to a sizer may have a border, and it
constants or wxALL for all directions (and you may also use wxNORTH, wxWEST etc instead). These can be specified which of the four sides may have this border, using the wxTOP,
flags can be used in combination with the alignment flags above as the second parameter of the wxLEFT, wxRIGHT and wxBOTTOM constants or wxALL for all directions (and you may
Add() method using the binary or operator |. The sizer of the border also must be made known, also use wxNORTH, wxWEST etc instead). These flags can be used in combination
and it is the third parameter in the Add() method. This means, that the entire behaviour of with the alignment flags above as the second parameter of the Add() method
a sizer and its children can be controlled by the three parameters of the Add() method. using the binary or operator |. The sizer of the border also must be made
known, and it is the third parameter in the Add() method. This means, that the
entire behaviour of a sizer and its children can be controlled by the three
parameters of the Add() method.
@code @code
// we want to get a dialog that is stretchable because it // We want to get a dialog that is stretchable because it
// has a text ctrl at the top and two buttons at the bottom // has a text ctrl at the top and two buttons at the bottom.
MyDialog::MyDialog(wxFrame *parent, wxWindowID id, const wxString ) MyDialog::MyDialog(wxFrame *parent, wxWindowID id, const wxString &title )
: wxDialog(parent, id, title, wxDefaultPosition, wxDefaultSize, : wxDialog(parent, id, title, wxDefaultPosition, wxDefaultSize,
wxDEFAULT_DIALOG_STYLE | wxRESIZE_BORDER) wxDEFAULT_DIALOG_STYLE | wxRESIZE_BORDER)
{ {
wxBoxSizer *topsizer = new wxBoxSizer( wxVERTICAL ); wxBoxSizer *topsizer = new wxBoxSizer( wxVERTICAL );
// create text ctrl with minimal size 100x60 // create text ctrl with minimal size 100x60
topsizer-Add( topsizer->Add(
new wxTextCtrl( this, -1, "My text.", wxDefaultPosition, wxSize(100,60), wxTE_MULTILINE), new wxTextCtrl( this, -1, "My text.", wxDefaultPosition, wxSize(100,60), wxTE_MULTILINE),
1, // make vertically stretchable 1, // make vertically stretchable
wxEXPAND | // make horizontally stretchable wxEXPAND | // make horizontally stretchable
wxALL, // and make border all around wxALL, // and make border all around
10 ); // set border width to 10 10 ); // set border width to 10
wxBoxSizer *button_sizer = new wxBoxSizer( wxHORIZONTAL ); wxBoxSizer *button_sizer = new wxBoxSizer( wxHORIZONTAL );
button_sizer-Add( button_sizer->Add(
new wxButton( this, wxID_OK, "OK" ), new wxButton( this, wxID_OK, "OK" ),
0, // make horizontally unstretchable 0, // make horizontally unstretchable
wxALL, // make border all around (implicit top alignment) wxALL, // make border all around (implicit top alignment)
10 ); // set border width to 10 10 ); // set border width to 10
button_sizer-Add( button_sizer->Add(
new wxButton( this, wxID_CANCEL, "Cancel" ), new wxButton( this, wxID_CANCEL, "Cancel" ),
0, // make horizontally unstretchable 0, // make horizontally unstretchable
wxALL, // make border all around (implicit top alignment) wxALL, // make border all around (implicit top alignment)
10 ); // set border width to 10 10 ); // set border width to 10
topsizer-Add( topsizer->Add(
button_sizer, button_sizer,
0, // make vertically unstretchable 0, // make vertically unstretchable
wxALIGN_CENTER ); // no border and centre horizontally wxALIGN_CENTER ); // no border and centre horizontally
@@ -252,14 +280,16 @@
} }
@endcode @endcode
Note that the new way of specifying flags to wxSizer is via #wxSizerFlags. This class greatly eases the burden of passing flags to a wxSizer. Note that the new way of specifying flags to wxSizer is via wxSizerFlags. This
class greatly eases the burden of passing flags to a wxSizer.
Here's how you'd do the previous example with wxSizerFlags: Here's how you'd do the previous example with wxSizerFlags:
@code @code
// we want to get a dialog that is stretchable because it // We want to get a dialog that is stretchable because it
// has a text ctrl at the top and two buttons at the bottom // has a text ctrl at the top and two buttons at the bottom.
MyDialog::MyDialog(wxFrame *parent, wxWindowID id, const wxString ) MyDialog::MyDialog(wxFrame *parent, wxWindowID id, const wxString &title )
: wxDialog(parent, id, title, wxDefaultPosition, wxDefaultSize, : wxDialog(parent, id, title, wxDefaultPosition, wxDefaultSize,
wxDEFAULT_DIALOG_STYLE | wxRESIZE_BORDER) wxDEFAULT_DIALOG_STYLE | wxRESIZE_BORDER)
{ {
@@ -267,7 +297,7 @@
// create text ctrl with minimal size 100x60 that is horizontally and // create text ctrl with minimal size 100x60 that is horizontally and
// vertically stretchable with a border width of 10 // vertically stretchable with a border width of 10
topsizer-Add( topsizer->Add(
new wxTextCtrl( this, -1, "My text.", wxDefaultPosition, wxSize(100,60), wxTE_MULTILINE), new wxTextCtrl( this, -1, "My text.", wxDefaultPosition, wxSize(100,60), wxTE_MULTILINE),
wxSizerFlags(1).Align().Expand().Border(wxALL, 10)); wxSizerFlags(1).Align().Expand().Border(wxALL, 10));
@@ -275,16 +305,16 @@
//create two buttons that are horizontally unstretchable, //create two buttons that are horizontally unstretchable,
// with an all-around border with a width of 10 and implicit top alignment // with an all-around border with a width of 10 and implicit top alignment
button_sizer-Add( button_sizer->Add(
new wxButton( this, wxID_OK, "OK" ), new wxButton( this, wxID_OK, "OK" ),
wxSizerFlags(0).Align().Border(wxALL, 10)); wxSizerFlags(0).Align().Border(wxALL, 10));
button_sizer-Add( button_sizer->Add(
new wxButton( this, wxID_CANCEL, "Cancel" ), new wxButton( this, wxID_CANCEL, "Cancel" ),
wxSizerFlags(0).Align().Border(wxALL, 10)); wxSizerFlags(0).Align().Border(wxALL, 10));
//create a sizer with no border and centered horizontally //create a sizer with no border and centered horizontally
topsizer-Add( topsizer->Add(
button_sizer, button_sizer,
wxSizerFlags(0).Center() ); wxSizerFlags(0).Center() );
@@ -294,38 +324,34 @@
@section gridsizerprogramming Programming with wxGridSizer @section overview_sizer_types Other Types of Sizers
#wxGridSizer is a sizer which lays out its children in a two-dimensional wxGridSizer is a sizer which lays out its children in a two-dimensional table
table with all table fields having the same size, with all table fields having the same size, i.e. the width of each field is the
i.e. the width of each field is the width of the widest child, width of the widest child, the height of each field is the height of the
the height of each field is the height of the tallest child. tallest child.
@section flexgridsizerprogramming Programming with wxFlexGridSizer wxFlexGridSizer is a sizer which lays out its children in a two-dimensional
table with all table fields in one row having the same height and all fields in
one column having the same width, but all rows or all columns are not
necessarily the same height or width as in the wxGridSizer.
#wxFlexGridSizer is a sizer which lays out its children in a two-dimensional wxStaticBoxSizer is a sizer derived from wxBoxSizer but adds a static box
table with all table fields in one row having the same around the sizer. Note that this static box has to be created separately.
height and all fields in one column having the same width, but all
rows or all columns are not necessarily the same height or width as in
the #wxGridSizer.
@section staticboxsizerprogramming Programming with wxStaticBoxSizer
#wxStaticBoxSizer is a sizer derived from wxBoxSizer but adds a static @section overview_sizer_button CreateButtonSizer
box around the sizer. Note that this static box has to be created
separately.
@section createbuttonsizer CreateButtonSizer
As a convenience, CreateButtonSizer ( long flags ) can be used to create a standard button sizer
in which standard buttons are displayed. The following flags can be passed to this function:
As a convenience, CreateButtonSizer(long flags) can be used to create a
standard button sizer in which standard buttons are displayed. The following
flags can be passed to this function:
@code @code
wxYES_NO // Add Yes/No subpanel wxYES_NO // Add Yes/No subpanel
wxYES // return wxID_YES wxYES // return wxID_YES
wxNO // return wxID_NO wxNO // return wxID_NO
wxNO_DEFAULT // make the wxNO button the default, otherwise wxYES or wxOK button will be default wxNO_DEFAULT // make the wxNO button the default,
// otherwise wxYES or wxOK button will be default
wxOK // return wxID_OK wxOK // return wxID_OK
wxCANCEL // return wxID_CANCEL wxCANCEL // return wxID_CANCEL
@@ -339,4 +365,3 @@
*/ */