More doxygen topic overview cleanup.
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@52133 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Bryan Petty
parent
07fa8f78f8
commit
58d0deaac1
@ -1,5 +1,5 @@
|
||||
/////////////////////////////////////////////////////////////////////////////
|
||||
// Name: runtimeclass
|
||||
// Name: runtimeclass.h
|
||||
// Purpose: topic overview
|
||||
// Author: wxWidgets team
|
||||
// RCS-ID: $Id$
|
||||
@ -8,104 +8,124 @@
|
||||
|
||||
/*!
|
||||
|
||||
@page runtimeclass_overview Runtime class information (aka RTTI) overview
|
||||
@page overview_runtimeclass Runtime Class Information (RTTI)
|
||||
|
||||
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
|
||||
@li @ref overview_runtimeclass_intro
|
||||
@li @ref overview_runtimeclass_classinfo
|
||||
@li @ref overview_runtimeclass_example
|
||||
|
||||
@seealso
|
||||
|
||||
@li wxObject
|
||||
@li wxClassInfo
|
||||
|
||||
|
||||
@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:
|
||||
<hr>
|
||||
|
||||
|
||||
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.
|
||||
@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.
|
||||
|
||||
|
||||
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 overview_runtimeclass_classinfo wxClassInfo
|
||||
|
||||
@section runtimeclassinformationexample Example
|
||||
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:
|
||||
|
||||
In a header file frame.h:
|
||||
@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.
|
||||
|
||||
@code
|
||||
class wxFrame : public wxWindow
|
||||
{
|
||||
DECLARE_DYNAMIC_CLASS(wxFrame)
|
||||
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.
|
||||
|
||||
private:
|
||||
wxString m_title;
|
||||
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.
|
||||
|
||||
public:
|
||||
...
|
||||
};
|
||||
@endcode
|
||||
@seeaslso
|
||||
|
||||
In a C++ file frame.cpp:
|
||||
|
||||
@code
|
||||
IMPLEMENT_DYNAMIC_CLASS(wxFrame, wxWindow)
|
||||
|
||||
wxFrame::wxFrame()
|
||||
{
|
||||
...
|
||||
}
|
||||
@endcode
|
||||
|
||||
*/
|
||||
@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
|
||||
|
||||
*/
|
||||
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
/////////////////////////////////////////////////////////////////////////////
|
||||
// Name: scrolling
|
||||
// Name: scrolling.h
|
||||
// Purpose: topic overview
|
||||
// Author: wxWidgets team
|
||||
// RCS-ID: $Id$
|
||||
@ -8,124 +8,91 @@
|
||||
|
||||
/*!
|
||||
|
||||
@page scrolling_overview Scrolling overview
|
||||
@page overview_scrolling 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:
|
||||
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:
|
||||
|
||||
orientation
|
||||
@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.
|
||||
|
||||
|
||||
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.
|
||||
|
||||
*/
|
||||
|
||||
*/
|
||||
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
/////////////////////////////////////////////////////////////////////////////
|
||||
// Name: sizer
|
||||
// Name: sizer.h
|
||||
// Purpose: topic overview
|
||||
// Author: wxWidgets team
|
||||
// RCS-ID: $Id$
|
||||
@ -8,335 +8,360 @@
|
||||
|
||||
/*!
|
||||
|
||||
@page sizer_overview 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.
|
||||
@page overview_sizer Sizer Overview
|
||||
|
||||
Classes: wxSizer, wxGridSizer, wxFlexGridSizer, wxBoxSizer, wxStaticBoxSizer
|
||||
|
||||
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
|
||||
|
||||
@section sizerscommonfeatures 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: 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
|
||||
|
||||
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:
|
||||
|
||||
@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:
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@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.
|
||||
@image html sizer00.bmp
|
||||
|
||||
@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
|
||||
@image html sizer01.bmp
|
||||
|
||||
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:
|
||||
@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:
|
||||
|
||||
@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
|
||||
|
||||
*/
|
||||
@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
|
||||
|
||||
*/
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user