/////////////////////////////////////////////////////////////////////////////
-// Name: runtimeclass
+// Name: runtimeclass.h
// Purpose: topic overview
// Author: wxWidgets team
// RCS-ID: $Id$
/*!
- @page runtimeclass_overview Runtime class information (aka RTTI) overview
-
- Classes: #wxObject, #wxClassInfo.
- 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.
- Another, which still persists, is that instances of a class cannot be created
- just by knowing the name of a class, which makes facilities such as persistent
- storage hard to 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
- addition of RTTI to the C++ standard and as support for it is still missing from
- some (albeit old) compilers, wxWidgets doesn't (yet) use it, but provides its
- own macro-based RTTI system.
- In the future, the standard C++ RTTI will be used though and you're encouraged
- to use whenever possible the #wxDynamicCast() macro which,
- for the implementations that support it, is defined just as dynamic_cast and
- uses wxWidgets RTTI for all the others. This macro is limited to wxWidgets
- classes only and only works with pointers (unlike the real dynamic_cast which
- also accepts references).
- Each class that you wish to be known to the type system should have
- a macro such as DECLARE_DYNAMIC_CLASS just inside the class declaration.
- The macro IMPLEMENT_DYNAMIC_CLASS should be in the implementation file.
- Note that these are entirely optional; use them if you wish to check object
- types, or create instances of classes using the class name. However,
- it is good to get into the habit of adding these macros for all classes.
- Variations on these #macros are used for multiple inheritance, and abstract
- 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
- wxClassInfo object inserts itself into a linked list (accessed through
- wxClassInfo::first 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
- wxClassInfo member, but defines a global function capable of creating a
- dynamic object of the class in question. A pointer to this function is
- stored in wxClassInfo, and is used when an object should be created
- dynamically.
- wxObject::IsKindOf uses the linked list of
- wxClassInfo. It takes a wxClassInfo argument, so use CLASSINFO(className)
- to return an appropriate wxClassInfo 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.
- If you have a pointer to the wxClassInfo object instead, then you
- can simply call wxClassInfo::CreateObject.
- #wxClassInfo
- #Example
-
-
- @section wxclassinfooverview wxClassInfo
-
- #Runtime class information (aka RTTI) overview
- Class: #wxClassInfo
- This class stores meta-information about classes. An application
- may use macros such as DECLARE_DYNAMIC_CLASS and IMPLEMENT_DYNAMIC_CLASS
- to record run-time information about a class, including:
-
-
- its position in the inheritance hierarchy;
- 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:
-
- @code
- class wxFrame : public wxWindow
- {
- DECLARE_DYNAMIC_CLASS(wxFrame)
-
- private:
- wxString m_title;
-
- public:
- ...
- };
- @endcode
-
- In a C++ file frame.cpp:
-
- @code
- IMPLEMENT_DYNAMIC_CLASS(wxFrame, wxWindow)
-
- wxFrame::wxFrame()
- {
- ...
- }
- @endcode
-
- */
+@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
+
+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. Another, which
+still persists, is that instances of a class cannot be created just by knowing
+the name of a class, which makes facilities such as persistent storage hard to
+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
+addition of RTTI to the C++ standard and as support for it is still missing
+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
+to use whenever possible the wxDynamicCast macro which, for the implementations
+that support it, is defined just as dynamic_cast and uses wxWidgets RTTI for
+all the others. This macro is limited to wxWidgets classes only and only works
+with pointers (unlike the real dynamic_cast which also accepts references).
+
+Each class that you wish to be known to the type system should have a macro
+such as DECLARE_DYNAMIC_CLASS just inside the class declaration. The macro
+IMPLEMENT_DYNAMIC_CLASS should be in the implementation file. Note that these
+are entirely optional; use them if you wish to check object types, or create
+instances of classes using the class name. However, it is good to get into the
+habit of adding these macros for all classes.
+
+Variations on these macros are used for multiple inheritance, and abstract
+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 wxClassInfo
+object inserts itself into a linked list (accessed through wxClassInfo::first
+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
+wxClassInfo member, but defines a global function capable of creating a dynamic
+object of the class in question. A pointer to this function is stored in
+wxClassInfo, and is used when an object should be created dynamically.
+
+wxObject::IsKindOf uses the linked list of wxClassInfo. It takes a wxClassInfo
+argument, so use CLASSINFO(className) to return an appropriate wxClassInfo
+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. If you have a pointer to the
+wxClassInfo object instead, then you can simply call wxClassInfo::CreateObject.
+
+
+@section overview_runtimeclass_classinfo wxClassInfo
+
+This class stores meta-information about classes. An application 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
+
+
+@section overview_runtimeclass_example Example
+
+In a header file frame.h:
+
+@code
+class wxFrame : public wxWindow
+{
+ DECLARE_DYNAMIC_CLASS(wxFrame)
+
+private:
+ wxString m_title;
+
+public:
+...
+};
+@endcode
+
+In a C++ file frame.cpp:
+
+@code
+IMPLEMENT_DYNAMIC_CLASS(wxFrame, wxWindow)
+
+wxFrame::wxFrame()
+{
+...
+}
+@endcode
+
+*/
/////////////////////////////////////////////////////////////////////////////
-// Name: scrolling
+// Name: scrolling.h
// Purpose: topic overview
// Author: wxWidgets team
// RCS-ID: $Id$
/*!
- @page scrolling_overview Scrolling overview
-
- Classes: #wxWindow, #wxScrolledWindow, #wxIcon, #wxScrollBar.
- 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.
- However, in practice, not all windows do make use of scrollbars, such as a single-line wxTextCtrl.
- Because any class derived from #wxWindow may have scrollbars,
- 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
- that the window necessarily handles it and physically scrolls the window. The base class
- wxWindow in fact doesn't have any default functionality to handle scroll events.
- If you created a wxWindow object with scrollbars, and then clicked on the scrollbars, nothing
- at all would happen. This is deliberate, because the @e interpretation of scroll
- events varies from one window class to another.
- #wxScrolledWindow (formerly wxCanvas) is an example of a window that
- adds functionality to make scrolling really work. It assumes that scrolling happens in
- 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
- not so suitable for a sophisticated editor in which the amount scrolled may vary according
- to the size of text on a given line. For this, you would derive from wxWindow and
- implement scrolling yourself. #wxGrid is an example of a class
- that implements its own scrolling, largely because columns and rows can vary in size.
- @b The scrollbar model
- The function wxWindow::SetScrollbar gives a clue about
- the way a scrollbar is modeled. This function takes the following arguments:
-
-
-
-
-
-
- orientation
-
-
-
-
- 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
- SetScrollbar(wxVERTICAL, 0, 16, 50);
- @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.
- 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
- scrollbar calculations and SetScrollbar
- call into a function named AdjustScrollbars, which can be called initially and also
- from your #wxSizeEvent handler function.
-
- */
-
+@page overview_scrolling Scrolling Overview
+
+Classes:
+@li wxWindow
+@li wxScrolledWindow
+@li wxScrollBar
+
+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. However, in practice, not all windows do make use of
+scrollbars, such as a single-line wxTextCtrl.
+
+Because any class derived from wxWindow may have scrollbars, 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 that
+the window necessarily handles it and physically scrolls the window. The base
+class wxWindow in fact doesn't have any default functionality to handle scroll
+events. If you created a wxWindow object with scrollbars, and then clicked on
+the scrollbars, nothing at all would happen. This is deliberate, because the
+@e interpretation of scroll events varies from one window class to another.
+
+wxScrolledWindow (formerly wxCanvas) is an example of a window that adds
+functionality to make scrolling really work. It assumes that scrolling happens
+in 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 not so suitable for a sophisticated editor in which
+the amount scrolled may vary according to the size of text on a given line. For
+this, you would derive from wxWindow and implement scrolling yourself. wxGrid
+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
+is sized so that you can only see 16 lines at a time. You would use:
+
+@code
+SetScrollbar(wxVERTICAL, 0, 16, 50);
+@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.
+
+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 scrollbar calculations and SetScrollbar call into a function named
+AdjustScrollbars, which can be called initially and also from your wxSizeEvent
+handler function.
+
+*/
/////////////////////////////////////////////////////////////////////////////
-// Name: sizer
+// Name: sizer.h
// Purpose: topic overview
// Author: wxWidgets team
// RCS-ID: $Id$
/*!
- @page sizer_overview Sizer overview
+@page overview_sizer Sizer Overview
- Classes: #wxSizer, #wxGridSizer,
- #wxFlexGridSizer, #wxBoxSizer,
- #wxStaticBoxSizer,
- #CreateButtonSizer
- Sizers, as represented by the wxSizer class and its descendants in
- the wxWidgets class hierarchy, have become the method of choice to
- define the layout of controls in dialogs in wxWidgets because of
- their ability to create visually appealing dialogs independent of the
- platform, taking into account the differences in size and style of
- the individual controls. Unlike the original wxWidgets Dialog Editor,
- 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 following sections briefly describe how to program with individual sizer classes.
- For information about the new wxWidgets resource system, which can describe
- sizer-based dialogs, see the @ref xrc_overview.
- @ref ideabehindsizers_overview
- @ref boxsizerprogramming_overview
- @ref gridsizerprogramming_overview
- @ref flexgridsizerprogramming_overview
- @ref staticboxsizerprogramming_overview
- #CreateButtonSizer
-
-
- @section ideabehindsizers The idea behind sizers
-
- 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
- based upon the idea of individual subwindows reporting their minimal required
- size and their ability to get stretched if the size of the parent window has changed.
- This will most often mean that the programmer does not set the start-up size of
- a dialog, the dialog will rather be assigned a sizer and this sizer
- will be queried about the recommended size. This sizer in turn will query its
- children (which can be normal windows, empty space or other sizers) so that
- a hierarchy of sizers can be constructed. Note that wxSizer does not derive from wxWindow
- and thus does not interfere with tab ordering and 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.
+Classes: wxSizer, wxGridSizer, wxFlexGridSizer, wxBoxSizer, wxStaticBoxSizer
- @section sizerscommonfeatures Common features
+Sizers, as represented by the wxSizer class and its descendants in the
+wxWidgets class hierarchy, have become the method of choice to define the
+layout of controls in dialogs in wxWidgets because of their ability to create
+visually appealing dialogs independent of the platform, taking into account
+the differences in size and style of the individual controls. Unlike the
+original wxWidgets Dialog Editor, 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
+following sections briefly describe how to program with individual sizer
+classes.
+
+For information about the wxWidgets resource system, which can describe
+sizer-based dialogs, see the @ref overview_xrc.
+
+@li @ref overview_sizer_idea
+@li @ref overview_sizer_features
+@li @ref overview_sizer_hiding
+@li @ref overview_sizer_box
+@li @ref overview_sizer_types
+@li @ref overview_sizer_button
- 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: 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
- 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
- can calculate their height, but not their width (e.g. a single line text control):
+<hr>
+@section overview_sizer_idea The Idea Behind Sizers
+
+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 based upon the idea of individual subwindows reporting their
+minimal required size and their ability to get stretched if the size of the
+parent window has changed. This will most often mean that the programmer does
+not set the start-up size of a dialog, the dialog will rather be assigned a
+sizer and this sizer will be queried about the recommended size. This sizer in
+turn will query its children (which can be normal windows, empty space or other
+sizers) so that a hierarchy of sizers can be constructed. Note that wxSizer
+does not derive from wxWindow and thus does not interfere with tab ordering and
+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 overview_sizer_box.
+@section overview_sizer_features Common Features
- @b A border: 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:
+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
+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 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
- @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.
-
- @section sizershiding Hiding controls using sizers
-
- You can hide controls contained in sizers the same way you would hide any control,
- using the wxWindow::Show method.
- However, wxSizer also offers a separate method which can tell the sizer not to
- consider that control in its 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
- the controls from the sizer and having to add them back later.
- Note: This is supported only by wxBoxSizer and wxFlexGridSizer.
- @b wxBoxSizer
- #wxBoxSizer can lay out its children either vertically
- or horizontally, depending on what flag is being used in its constructor.
- When using a vertical sizer, each child can be centered, aligned to the
- right or aligned to the left. Correspondingly, when using a horizontal
- sizer, each child can be centered, aligned at the bottom or aligned at
- the top. The stretch factor described in the last paragraph is used
- for the main orientation, i.e. when using a 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:
-
-
-
- @b wxStaticBoxSizer
- #wxStaticBoxSixer is the same as a wxBoxSizer, but surrounded by a
- static box. Here is a sample:
-
-
-
- @b 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:
-
-
-
- For programming information, see #wxGridSizer.
- @b 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:
-
-
-
-
- @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.
- 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
- constants or wxALL for all directions (and you may also use wxNORTH, wxWEST etc instead). These
- flags can be used in combination with the alignment flags above as the second parameter 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
- // we want to get a dialog that is stretchable because it
- // has a text ctrl at the top and two buttons at the bottom
-
- MyDialog::MyDialog(wxFrame *parent, wxWindowID id, const wxString )
- : wxDialog(parent, id, title, wxDefaultPosition, wxDefaultSize,
- wxDEFAULT_DIALOG_STYLE | wxRESIZE_BORDER)
- {
- wxBoxSizer *topsizer = new wxBoxSizer( wxVERTICAL );
-
- // create text ctrl with minimal size 100x60
- topsizer-Add(
- new wxTextCtrl( this, -1, "My text.", wxDefaultPosition, wxSize(100,60), wxTE_MULTILINE),
- 1, // make vertically stretchable
- wxEXPAND | // make horizontally stretchable
- wxALL, // and make border all around
- 10 ); // set border width to 10
-
-
- wxBoxSizer *button_sizer = new wxBoxSizer( wxHORIZONTAL );
- button_sizer-Add(
- new wxButton( this, wxID_OK, "OK" ),
- 0, // make horizontally unstretchable
- wxALL, // make border all around (implicit top alignment)
- 10 ); // set border width to 10
- button_sizer-Add(
- new wxButton( this, wxID_CANCEL, "Cancel" ),
- 0, // make horizontally unstretchable
- wxALL, // make border all around (implicit top alignment)
- 10 ); // set border width to 10
-
- topsizer-Add(
- button_sizer,
- 0, // make vertically unstretchable
- wxALIGN_CENTER ); // no border and centre horizontally
-
- SetSizerAndFit(topsizer); // use the sizer for layout and size window
- // accordingly and prevent it from being resized
- // to smaller size
- }
- @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.
- Here's how you'd do the previous example with wxSizerFlags:
-
- @code
- // we want to get a dialog that is stretchable because it
- // has a text ctrl at the top and two buttons at the bottom
-
- MyDialog::MyDialog(wxFrame *parent, wxWindowID id, const wxString )
- : wxDialog(parent, id, title, wxDefaultPosition, wxDefaultSize,
- wxDEFAULT_DIALOG_STYLE | wxRESIZE_BORDER)
- {
- wxBoxSizer *topsizer = new wxBoxSizer( wxVERTICAL );
-
- // create text ctrl with minimal size 100x60 that is horizontally and
- // vertically stretchable with a border width of 10
- topsizer-Add(
- new wxTextCtrl( this, -1, "My text.", wxDefaultPosition, wxSize(100,60), wxTE_MULTILINE),
- wxSizerFlags(1).Align().Expand().Border(wxALL, 10));
-
- wxBoxSizer *button_sizer = new wxBoxSizer( wxHORIZONTAL );
-
- //create two buttons that are horizontally unstretchable,
- // with an all-around border with a width of 10 and implicit top alignment
- button_sizer-Add(
- new wxButton( this, wxID_OK, "OK" ),
- wxSizerFlags(0).Align().Border(wxALL, 10));
-
- button_sizer-Add(
- new wxButton( this, wxID_CANCEL, "Cancel" ),
- wxSizerFlags(0).Align().Border(wxALL, 10));
-
- //create a sizer with no border and centered horizontally
- topsizer-Add(
- button_sizer,
- wxSizerFlags(0).Center() );
-
- SetSizerAndFit(topsizer); // use the sizer for layout and set size and hints
- }
- @endcode
-
-
-
- @section gridsizerprogramming Programming with wxGridSizer
-
- #wxGridSizer is a sizer which lays out its children in a two-dimensional
- table with all table fields having the same size,
- i.e. the width of each field is the width of the widest child,
- the height of each field is the height of the 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.
-
- @section staticboxsizerprogramming Programming with wxStaticBoxSizer
-
- #wxStaticBoxSizer is a sizer derived from wxBoxSizer but adds a static
- 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:
-
-
- @code
- wxYES_NO // Add Yes/No subpanel
- wxYES // return wxID_YES
- wxNO // return wxID_NO
- wxNO_DEFAULT // make the wxNO button the default, otherwise wxYES or wxOK button will be default
-
- wxOK // return wxID_OK
- wxCANCEL // return wxID_CANCEL
- wxHELP // return wxID_HELP
+@image html sizer01.bmp
- wxFORWARD // return wxID_FORWARD
- wxBACKWARD // return wxID_BACKWARD
- wxSETUP // return wxID_SETUP
- wxMORE // return wxID_MORE
- @endcode
+@image html sizer02.bmp
- */
+<b>An alignment</b>: 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:
+@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
+
+Within wxDesigner, this stretch factor gets set from the @e Option menu.
+
+
+@section overview_sizer_hiding Hiding Controls Using Sizers
+
+You can hide controls contained in sizers the same way you would hide any
+control, using the wxWindow::Show method. However, wxSizer also offers a
+separate method which can tell the sizer not to consider that control in its
+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
+the controls from the sizer and having to add them back later.
+
+@note This is supported only by wxBoxSizer and wxFlexGridSizer.
+
+@subsection overview_sizer_hiding_box wxBoxSizer
+
+wxBoxSizer can lay out its children either vertically or horizontally,
+depending on what flag is being used in its constructor. When using a vertical
+sizer, each child can be centered, aligned to the right or aligned to the left.
+Correspondingly, when using a horizontal sizer, each child can be centered,
+aligned at the bottom or aligned at the top. The stretch factor described in
+the last paragraph is used for the main orientation, i.e. when using a
+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
+
+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.
+
+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 constants or wxALL for all directions (and you may
+also use wxNORTH, wxWEST etc instead). These flags can be used in combination
+with the alignment flags above as the second parameter 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
+// We want to get a dialog that is stretchable because it
+// has a text ctrl at the top and two buttons at the bottom.
+
+MyDialog::MyDialog(wxFrame *parent, wxWindowID id, const wxString &title )
+: wxDialog(parent, id, title, wxDefaultPosition, wxDefaultSize,
+ wxDEFAULT_DIALOG_STYLE | wxRESIZE_BORDER)
+{
+ wxBoxSizer *topsizer = new wxBoxSizer( wxVERTICAL );
+
+ // create text ctrl with minimal size 100x60
+ topsizer->Add(
+ new wxTextCtrl( this, -1, "My text.", wxDefaultPosition, wxSize(100,60), wxTE_MULTILINE),
+ 1, // make vertically stretchable
+ wxEXPAND | // make horizontally stretchable
+ wxALL, // and make border all around
+ 10 ); // set border width to 10
+
+ wxBoxSizer *button_sizer = new wxBoxSizer( wxHORIZONTAL );
+ button_sizer->Add(
+ new wxButton( this, wxID_OK, "OK" ),
+ 0, // make horizontally unstretchable
+ wxALL, // make border all around (implicit top alignment)
+ 10 ); // set border width to 10
+ button_sizer->Add(
+ new wxButton( this, wxID_CANCEL, "Cancel" ),
+ 0, // make horizontally unstretchable
+ wxALL, // make border all around (implicit top alignment)
+ 10 ); // set border width to 10
+
+ topsizer->Add(
+ button_sizer,
+ 0, // make vertically unstretchable
+ wxALIGN_CENTER ); // no border and centre horizontally
+
+ SetSizerAndFit(topsizer); // use the sizer for layout and size window
+ // accordingly and prevent it from being resized
+ // to smaller size
+}
+@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.
+
+Here's how you'd do the previous example with wxSizerFlags:
+
+@code
+// We want to get a dialog that is stretchable because it
+// has a text ctrl at the top and two buttons at the bottom.
+
+MyDialog::MyDialog(wxFrame *parent, wxWindowID id, const wxString &title )
+: wxDialog(parent, id, title, wxDefaultPosition, wxDefaultSize,
+ wxDEFAULT_DIALOG_STYLE | wxRESIZE_BORDER)
+{
+ wxBoxSizer *topsizer = new wxBoxSizer( wxVERTICAL );
+
+ // create text ctrl with minimal size 100x60 that is horizontally and
+ // vertically stretchable with a border width of 10
+ topsizer->Add(
+ new wxTextCtrl( this, -1, "My text.", wxDefaultPosition, wxSize(100,60), wxTE_MULTILINE),
+ wxSizerFlags(1).Align().Expand().Border(wxALL, 10));
+
+ wxBoxSizer *button_sizer = new wxBoxSizer( wxHORIZONTAL );
+
+ //create two buttons that are horizontally unstretchable,
+ // with an all-around border with a width of 10 and implicit top alignment
+ button_sizer->Add(
+ new wxButton( this, wxID_OK, "OK" ),
+ wxSizerFlags(0).Align().Border(wxALL, 10));
+
+ button_sizer->Add(
+ new wxButton( this, wxID_CANCEL, "Cancel" ),
+ wxSizerFlags(0).Align().Border(wxALL, 10));
+
+ //create a sizer with no border and centered horizontally
+ topsizer->Add(
+ button_sizer,
+ wxSizerFlags(0).Center() );
+
+ SetSizerAndFit(topsizer); // use the sizer for layout and set size and hints
+}
+@endcode
+
+
+
+@section overview_sizer_types Other Types of Sizers
+
+wxGridSizer is a sizer which lays out its children in a two-dimensional table
+with all table fields having the same size, i.e. the width of each field is the
+width of the widest child, the height of each field is the height of the
+tallest child.
+
+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.
+
+wxStaticBoxSizer is a sizer derived from wxBoxSizer but adds a static box
+around the sizer. Note that this static box has to be created separately.
+
+
+@section overview_sizer_button 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:
+
+@code
+wxYES_NO // Add Yes/No subpanel
+wxYES // return wxID_YES
+wxNO // return wxID_NO
+wxNO_DEFAULT // make the wxNO button the default,
+ // otherwise wxYES or wxOK button will be default
+
+wxOK // return wxID_OK
+wxCANCEL // return wxID_CANCEL
+wxHELP // return wxID_HELP
+
+wxFORWARD // return wxID_FORWARD
+wxBACKWARD // return wxID_BACKWARD
+wxSETUP // return wxID_SETUP
+wxMORE // return wxID_MORE
+@endcode
+
+*/
projects / wxWidgets.git / commitdiff
