The basic idea behind a box sizer 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) {\it 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 {\it option} 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 {\it 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 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.
-
-\begin{verbatim}
-// 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
-
- SetAutoLayout( TRUE ); // tell dialog to use sizer
- SetSizer( topsizer ); // actually set the sizer
-
- topsizer->Fit( this ); // set size to minimum size as calculated by the sizer
- topsizer->SetSizeHints( this ); // set size hints to honour mininum size
-}
-\end{verbatim}
+For more information, please see \helpref{Programming with wxBoxSizer}{boxsizerprogramming}.
\wxheading{Derived from}
\helpref{wxSizer}{wxsizer}\\
\helpref{wxObject}{wxobject}
+\wxheading{See also}
+
+\helpref{wxSizer}{wxsizer}, \helpref{Sizer overview}{sizeroverview}
+
\membersection{wxBoxSizer::wxBoxSizer}\label{wxboxsizerwxboxsizer}
\func{}{wxBoxSizer}{\param{int }{orient}}
\setfooter{\thepage}{}{}{}{}{\thepage}%
A classification of wxWindows classes by category.
-\twocolwidtha{5cm}
{\large {\bf Managed windows}}
window manager (such as MS Windows, or the Motif Window Manager).
Frames may contain windows, and dialog boxes may directly contain controls.
+\twocolwidtha{6cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{\helpref{wxDialog}{wxdialog}}{Dialog box}
\twocolitem{\helpref{wxFrame}{wxframe}}{Normal frame}
The following are a variety of classes that are derived from wxWindow.
+\twocolwidtha{6cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{\helpref{wxPanel}{wxpanel}}{A window whose colour changes according to current user settings}
\twocolitem{\helpref{wxScrolledWindow}{wxscrolledwindow}}{Window with automatically managed scrollbars}
Common dialogs are ready-made dialog classes which are frequently used
in an application.
+\twocolwidtha{6cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{\helpref{wxDialog}{wxdialog}}{Base class for common dialogs}
\twocolitem{\helpref{wxColourDialog}{wxcolourdialog}}{Colour chooser dialog}
Typically, these are small windows which provide interaction with the user. Controls
that are not static can have \helpref{validators}{wxvalidator} associated with them.
+\twocolwidtha{6cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{\helpref{wxControl}{wxcontrol}}{The base class for controls}
\twocolitem{\helpref{wxButton}{wxbutton}}{Push button control, displaying text}
{\large {\bf Menus}}
+\twocolwidtha{6cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{\helpref{wxMenu}{wxmenu}}{Displays a series of menu items for selection}
\twocolitem{\helpref{wxMenuBar}{wxmenubar}}{Contains a series of menus for use with a frame}
{\large {\bf Window layout}}
-There are two different systems for layouting windows (and dialogs in particular).
+There are two different systems for laying out windows (and dialogs in particular).
One is based upon so-called sizers and it requires less typing, thinking and calculating
and will in almost all cases produce dialogs looking equally well on all platforms, the
-other is based on so-called constraints and allows for more detailed layouts.
+other is based on so-called constraints and is deprecated, though still available.
-These are the classes relevant to the sizer-based layout.
+\overview{Sizer overview}{sizeroverview} describes sizer-based layout.
+These are the classes relevant to sizer-based layout.
+
+\twocolwidtha{6cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{\helpref{wxSizer}{wxsizer}}{Abstract base class}
\twocolitem{\helpref{wxGridSizer}{wxgridsizer}}{A sizer for laying out windows in a grid with all fields having the same size}
\twocolitem{\helpref{wxFlexGridSizer}{wxflexgridsizer}}{A sizer for laying out windows in a flexible grid}
\twocolitem{\helpref{wxBoxSizer}{wxboxsizer}}{A sizer for laying out windows in a row or column}
-\twocolitem{\helpref{wxStaticBoxSizer}{wxstaticboxsizer}}{Same as wxBoxSizer, but with surrounding static box}
-\twocolitem{\helpref{wxNotebookSizer}{wxnotebooksizer}}{Sizer to use with the wxNotebook control.}
+\twocolitem{\helpref{wxStaticBoxSizer}{wxstaticboxsizer}}{Same as wxBoxSizer, but with a surrounding static box}
+\twocolitem{\helpref{wxNotebookSizer}{wxnotebooksizer}}{Sizer to use with the wxNotebook control}
\end{twocollist}
-\overview{Overview}{constraintsoverview} over the constraints-based layout.
+\overview{Constraints overview}{constraintsoverview} describes constraints-based layout.
These are the classes relevant to constraints-based window layout.
+\twocolwidtha{6cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{\helpref{wxIndividualLayoutConstraint}{wxindividuallayoutconstraint}}{Represents a single constraint dimension}
\twocolitem{\helpref{wxLayoutConstraints}{wxlayoutconstraints}}{Represents the constraints for a window class}
abstraction that allows parameterisation of your drawing code
by passing different device contexts.
+\twocolwidtha{6cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{\helpref{wxClientDC}{wxclientdc}}{A device context to access the client area outside {\bf OnPaint} events}
\twocolitem{\helpref{wxPaintDC}{wxpaintdc}}{A device context to access the client area inside {\bf OnPaint} events}
These classes are related to drawing on device contexts and windows.
+\twocolwidtha{6cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{\helpref{wxColour}{wxcolour}}{Represents the red, blue and green elements of a colour}
\twocolitem{\helpref{wxDCClipper}{wxdcclipper}}{Wraps the operations of setting and destroying the clipping region}
An event object contains information about a specific event. Event handlers
(usually member functions) have a single, event argument.
+\twocolwidtha{6cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{\helpref{wxActivateEvent}{wxactivateevent}}{A window or application activation event}
\twocolitem{\helpref{wxCalendarEvent}{wxcalendarevent}}{Used with \helpref{wxCalendarCtrl}{wxcalendarctrl}}
These are the window validators, used for filtering and validating
user input.
+\twocolwidtha{6cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{\helpref{wxValidator}{wxvalidator}}{Base validator class}
\twocolitem{\helpref{wxTextValidator}{wxtextvalidator}}{Text control validator class}
These are the data structure classes supported by wxWindows.
+\twocolwidtha{6cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{\helpref{wxCmdLineParser}{wxcmdlineparser}}{Command line parser class}
\twocolitem{\helpref{wxDate}{wxdate}}{A class for date manipulation (deprecated in favour of wxDateTime)}
wxWindows supports run-time manipulation of class information, and dynamic
creation of objects given class names.
+\twocolwidtha{6cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{\helpref{wxClassInfo}{wxclassinfo}}{Holds run-time class information}
\twocolitem{\helpref{wxObject}{wxobject}}{Root class for classes with run-time information}
wxWindows provides several classes and functions for the message logging.
Please see the \helpref{wxLog overview}{wxlogoverview} for more details.
+\twocolwidtha{6cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{\helpref{wxLog}{wxlog}}{The base log class}
\twocolitem{\helpref{wxLogStderr}{wxlogstderr}}{Log messages to a C STDIO stream}
wxWindows supports some aspects of debugging an application through
classes, functions and macros.
+\twocolwidtha{6cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{\helpref{wxDebugContext}{wxdebugcontext}}{Provides memory-checking facilities}
%\twocolitem{\helpref{wxDebugStreamBuf}{wxdebugstreambuf}}{A stream buffer writing to the debug stream}
wxWindows provides its own classes for socket based networking.
+\twocolwidtha{6cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{\helpref{wxDialUpManager}{wxdialupmanager}}{Provides functions to check the status of network connection and to establish one}
\twocolitem{\helpref{wxIPV4address}{wxipv4address}}{Represents an Internet address}
wxWindows provides a simple interprocess communications facilities
based on DDE.
+\twocolwidtha{6cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{\helpref{wxDDEClient}{wxddeclient}}{Represents a client}
\twocolitem{\helpref{wxDDEConnection}{wxddeconnection}}{Represents the connection between a client and a server}
wxWindows supports a document/view framework which provides
housekeeping for a document-centric application.
+\twocolwidtha{6cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{\helpref{wxDocument}{wxdocument}}{Represents a document}
\twocolitem{\helpref{wxView}{wxview}}{Represents a view}
make it relatively straightforward to provide document printing
facilities.
+\twocolwidtha{6cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{\helpref{wxPreviewFrame}{wxpreviewframe}}{Frame for displaying a print preview}
\twocolitem{\helpref{wxPreviewCanvas}{wxpreviewcanvas}}{Canvas for displaying a print preview}
\overview{Drag and drop and clipboard overview}{wxdndoverview}
+\twocolwidtha{6cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{\helpref{wxDataObject}{wxdataobject}}{Data object class}
\twocolitem{\helpref{wxDataFormat}{wxdataformat}}{Represents a data format}
wxWindows has several small classes to work with disk files, see \helpref{file classes
overview}{wxfileoverview} for more details.
+\twocolwidtha{6cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{\helpref{wxFileName}{wxfilename}}{Operations with the file name and attributes}
\twocolitem{\helpref{wxDir}{wxdir}}{Class for enumerating files/subdirectories.}
wxWindows has its own set of stream classes, as an alternative to often buggy standard stream
libraries, and to provide enhanced functionality.
+\twocolwidtha{6cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{\helpref{wxStreamBase}{wxstreambase}}{Stream base class}
\twocolitem{\helpref{wxStreamBuffer}{wxstreambuffer}}{Stream buffer class}
wxWindows provides a set of classes to make use of the native thread
capabilities of the various platforms.
+\twocolwidtha{6cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{\helpref{wxThread}{wxthread}}{Thread class}
\twocolitem{\helpref{wxMutex}{wxmutex}}{Mutex class}
wxWindows provides a set of classes to display text in HTML format. These
class include a help system based on the HTML widget.
+\twocolwidtha{6cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{\helpref{wxHtmlHelpController}{wxhtmlhelpcontroller}}{HTML help controller class}
\twocolitem{\helpref{wxHtmlWindow}{wxhtmlwindow}}{HTML window class}
wxWindows provides a set of classes that implement an extensible virtual file system,
used internally by the HTML classes.
+\twocolwidtha{6cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{\helpref{wxFSFile}{wxfsfile}}{Represents a file in the virtual file system}
\twocolitem{\helpref{wxFileSystem}{wxfilesystem}}{Main interface for the virtual file system}
Resources allow your application to create controls and other user interface elements
from specifications stored in an XML format.
+\twocolwidtha{6cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{\helpref{wxXmlResource}{wxxmlresource}}{The main class for working with resources.}
\twocolitem{\helpref{wxXmlResourceHandler}{wxxmlresourcehandler}}{The base class for XML resource handlers.}
{\large {\bf Online help}}
+\twocolwidtha{6cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{\helpref{wxHelpController}{wxhelpcontroller}}{Family of classes for controlling help windows}
\twocolitem{\helpref{wxHtmlHelpController}{wxhtmlhelpcontroller}}{HTML help controller class}
portable, flexible and better supported, so please use the classes below for
working with databases:
+\twocolwidtha{6cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{\helpref{wxDb}{wxdb}}{ODBC database connection}
\twocolitem{\helpref{wxDbTable}{wxdbtable}}{Provides access to a database table}
The documentation for the older classes is still included, but you should avoid
using any of them in the new programs:
+\twocolwidtha{6cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{\helpref{wxDatabase}{wxdatabase}}{Database class}
\twocolitem{\helpref{wxQueryCol}{wxquerycol}}{Class representing a column}
{\large {\bf Miscellaneous}}
+\twocolwidtha{6cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{\helpref{wxApp}{wxapp}}{Application class}
\twocolitem{\helpref{wxCaret}{wxcaret}}{A caret (cursor) object}
\helpref{wxSizer}{wxsizer}\\
\helpref{wxObject}{wxobject}
+\wxheading{See also}
+
+\helpref{wxSizer}{wxsizer}, \helpref{Sizer overview}{sizeroverview}
+
\membersection{wxFlexGridSizer::wxFlexGridSizer}\label{wxflexgridsizerwxflexgridsizer}
\func{}{wxFlexGridSizer}{\param{int }{rows}, \param{int }{cols}, \param{int }{vgap}, \param{int }{hgap}}
\helpref{wxSizer}{wxsizer}\\
\helpref{wxObject}{wxobject}
+\wxheading{See also}
+
+\helpref{wxSizer}{wxsizer}, \helpref{Sizer overview}{sizeroverview}
+
\membersection{wxGridSizer::wxGridSizer}\label{wxgridsizerwxgridsizer}
\func{}{wxGridSizer}{\param{int }{rows}, \param{int }{cols}, \param{int }{vgap}, \param{int }{hgap}}
sizer grow dynamically. {\it vgap} and {\it hgap} define extra space between
all children.
-
\membersection{wxGridSizer::GetCols}\label{wxgridsizergetcols}
\func{int}{GetCols}{}
page of the notebook and report an adjusted minimal size to a more toplevel
sizer.
-In order to query the size of notebook page, this page needs to have its
-own sizer, otherwise the wxNotebookSizer will ignore it. Notebook pages
-get there sizer by assiging one to them using \helpref{wxWindow::SetSizer}{wxwindowsetsizer}
-and setting the auto-layout option to TRUE using
-\helpref{wxWindow::SetAutoLayout}{wxwindowsetautolayout}. Here is one
-example showing how to add a notebook page that the notebook sizer is
-aware of:
-
-\begin{verbatim}
- wxNotebook *notebook = new wxNotebook( &dialog, -1 );
- wxNotebookSizer *nbs = new wxNotebookSizer( notebook );
-
- // Add panel as notebook page
- wxPanel *panel = new wxPanel( notebook, -1 );
- notebook->AddPage( panel, "My Notebook Page" );
-
- wxBoxSizer *panelsizer = new wxBoxSizer( wxVERTICAL );
-
- // Add controls to panel and panelsizer here...
-
- panel->SetAutoLayout( TRUE );
- panel->SetSizer( panelsizer );
-\end{verbatim}
-
-See also \helpref{wxSizer}{wxsizer}, \helpref{wxNotebook}{wxnotebook}.
+For more information, please see \helpref{Programming with wxNotebookSizer}{notebooksizerprogramming}.
\wxheading{Derived from}
\helpref{wxSizer}{wxsizer}\\
\helpref{wxObject}{wxobject}
+\wxheading{See also}
+
+\helpref{wxSizer}{wxsizer}, \helpref{wxNotebook}{wxnotebook}, \helpref{Sizer overview}{sizeroverview}
+
\latexignore{\rtfignore{\wxheading{Members}}}
\membersection{wxNotebookSizer::wxNotebookSizer}\label{wxnotebooksizerwxnotebooksizer}
box around the sizer. Note that this static box has to be created
separately.
-See also \helpref{wxSizer}{wxsizer}, \helpref{wxStaticBox}{wxstaticbox} and
- \helpref{wxBoxSizer}{wxboxsizer}.
-
\wxheading{Derived from}
\helpref{wxBoxSizer}{wxboxsizer}\\
\helpref{wxSizer}{wxsizer}\\
\helpref{wxObject}{wxobject}
+\wxheading{See also}
+
+\helpref{wxSizer}{wxsizer}, \helpref{wxStaticBox}{wxstaticbox}, \helpref{wxBoxSizer}{wxboxsizer}, \helpref{Sizer overview}{sizeroverview}
+
\latexignore{\rtfignore{\wxheading{Members}}}
\membersection{wxStaticBoxSizer::wxStaticBoxSizer}\label{wxstaticboxsizerwxstaticboxsizer}
\helpref{wxObject}{wxobject}
+\wxheading{See also}
+
+\helpref{Sizer overview}{sizeroverview}
+
\latexignore{\rtfignore{\wxheading{Members}}}
\membersection{wxSizer::wxSizer}\label{wxsizerwxsizer}
Classes: \helpref{wxLayoutConstraints}{wxlayoutconstraints}, \helpref{wxIndividualLayoutConstraint}{wxindividuallayoutconstraint}.
-{\bf Note:} constraints are now deprecated and you should use \helpref{wxSizers}{wxsizer} instead.
+{\bf Note:} constraints are now deprecated and you should use \helpref{sizers}{sizeroverview} instead.
Objects of class wxLayoutConstraint can be associated with a window to define
the way it is laid out, with respect to its siblings or the parent.
\input tdialog.tex
\input tvalidat.tex
\input tconstr.tex
+\input tsizer.tex
\input tresourc.tex
\input txrc.tex
\input tscroll.tex
--- /dev/null
+\section{Sizer overview}\label{sizeroverview}
+
+Classes: \helpref{wxSizer}{wxsizer}, \helpref{wxGridSizer}{wxgridsizer},
+\helpref{wxFlexGridSizer}{wxflexgridsizer}, \helpref{wxBoxSizer}{wxboxsizer},
+\helpref{wxStaticBoxSizer}{wxstaticboxsizer},
+\helpref{wxNotebookSizer}{wxnotebooksizer}
+
+Sizers, as represented by the wxSizer class and its descendants in
+the wxWindows class hierarchy, have become the method of choice to
+define the layout of controls in dialogs in wxWindows 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 wxWindows Dialog Editor,
+editors such as wxDesigner, wxrcedit, 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 wxWindows resource system, which can describe
+sizer-based dialogs, see the \helpref{XML-based resource system overview}{xrcoverview}.
+
+\subsection{The idea behind sizers}\label{ideabehindsizers}
+
+The layout algorithm used by sizers in wxWindows 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 wxWindows 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 wxWindows. Each represents
+either a certain way to lay out dialog items in a dialog or it fulfils 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 \helpref{Programming with Sizers}{sizersprogramming}.
+
+\subsubsection{Common features}\label{sizerscommonfeatures}
+
+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:
+
+{\bf 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 wxWindows, 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):
+
+\center{
+\image{}{sizer03.gif}
+
+\image{}{sizer04.gif}
+
+\image{}{sizer05.gif}
+}
+
+{\bf 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:
+
+\center{
+\image{}{sizer00.gif}
+
+\image{}{sizer01.gif}
+
+\image{}{sizer02.gif}
+}
+
+{\bf 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:
+
+\center{
+\image{}{sizer06.gif}
+}
+
+{\bf 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 {\it 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:
+
+\center{
+\image{}{sizer07.gif}
+}
+
+Within wxDesigner, this stretch factor gets set from the {\it Option} menu.
+
+\wxheading{wxBoxSizer}
+
+\helpref{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:
+
+\center{
+\image{}{sizer08.gif}
+}
+
+\wxheading{wxStaticBoxSizer}
+
+\helpref{wxStaticBoxSixer}{wxstaticboxsizer} is the same as a wxBoxSizer, but surrounded by a
+static box. Here is a sample:
+
+\center{
+\image{}{sizer09.gif}
+}
+
+\wxheading{wxGridSizer}
+
+\helpref{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:
+
+\center{
+\image{}{sizer10.gif}
+}
+
+For programming information, see \helpref{wxGridSizer}{wxgridsizer}.
+
+\wxheading{wxFlexGridSizer}
+
+Another two-dimensional sizer derived from
+wxGridSizer. The width of each column and the height of each row
+are calculated individually according 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 that which it requested. The following sample shows
+the same dialog as the one above, but using a flex grid sizer:
+
+\center{
+\image{}{sizer11.gif}
+}
+
+\wxheading{wxNotebookSizer}
+
+\helpref{wxNotebookSizer}{wxnotebooksizer} can be used in
+connection with notebooks. It calculates the size of each
+notebook page and sets the size of the notebook to the size
+of the biggest page plus some extra space required for the
+notebook tabs and decorations.
+
+\subsection{Programming with wxBoxSizer}\label{boxsizerprogramming}
+
+The basic idea behind a \helpref{wxBoxSizer}{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) {\it 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 {\it option} 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 {\it 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 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.
+
+\begin{verbatim}
+// 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
+
+ SetAutoLayout( TRUE ); // tell dialog to use sizer
+ SetSizer( topsizer ); // actually set the sizer
+
+ topsizer->Fit( this ); // set size to minimum size as calculated by the sizer
+ topsizer->SetSizeHints( this ); // set size hints to honour mininum size
+}
+\end{verbatim}
+
+\subsection{Programming with wxGridSizer}\label{gridsizerprogramming}
+
+\helpref{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.
+
+\subsection{Programming with wxFlexGridSizer}\label{flexgridsizerprogramming}
+
+\helpref{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 \helpref{wxGridSizer}{wxgridsizer}.
+
+\subsection{Programming with wxNotebookSizer}\label{notebooksizerprogramming}
+
+\helpref{wxNotebookSizer}{wxnotebooksizer} is a specialized sizer to make sizers work in connection
+with using notebooks. This sizer is different from any other sizer as
+you must not add any children to it - instead, it queries the notebook class itself.
+The only thing this sizer does is to determine the size of the biggest
+page of the notebook and report an adjusted minimal size to a more toplevel
+sizer.
+
+In order to query the size of notebook page, this page needs to have its
+own sizer, otherwise the wxNotebookSizer will ignore it. Notebook pages
+get there sizer by assiging one to them using \helpref{wxWindow::SetSizer}{wxwindowsetsizer}
+and setting the auto-layout option to TRUE using
+\helpref{wxWindow::SetAutoLayout}{wxwindowsetautolayout}. Here is one
+example showing how to add a notebook page that the notebook sizer is
+aware of:
+
+\begin{verbatim}
+ wxNotebook *notebook = new wxNotebook( &dialog, -1 );
+ wxNotebookSizer *nbs = new wxNotebookSizer( notebook );
+
+ // Add panel as notebook page
+ wxPanel *panel = new wxPanel( notebook, -1 );
+ notebook->AddPage( panel, "My Notebook Page" );
+
+ wxBoxSizer *panelsizer = new wxBoxSizer( wxVERTICAL );
+
+ // Add controls to panel and panelsizer here...
+
+ panel->SetAutoLayout( TRUE );
+ panel->SetSizer( panelsizer );
+\end{verbatim}
+
+\subsection{Programming with wxStaticBoxSizer}\label{staticboxsizerprogramming}
+
+\helpref{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.
+
\subsection{XRC file format}\label{xrcfileformat}
-\subsubsection{Introduction to the XRC file format}\label{xrcfileformatintro}
-
-This note describes the file format used for storing XRC resources that are
-used by wxXmlResource class. It is probably only useful for those implementing
-dialog editors with XRC support, or for those writing XRC files by hand.
-
-If you only want to use the resources, you can choose from a number of editors,
-as listed in \helpref{XRC concepts}{xrcconcepts}.
-
-The XRC format is based on XML 1.0 (please consult W3C's specification). There
-is no DTD available since it is not possible to fully describe the format with
-the limited expressive power of DTDs.
-
-\subsubsection{XRC terminology}\label{xrcterminology}
-
-The usual XML terminology applies. In particular, we shall use the terms
-{\it node}, {\it property} and {\it value} in the XML sense:
-
-\begin{verbatim}
- <node property1="value1" property2="value2">...</node>
-\end{verbatim}
-
-The term "attribute" is specific to XRC and refers to a property-less subnode
-of an <object> or <object_ref> node. In the example bellow, <pos>, <label> and
-<style> are attributes, while neither <resource> nor either of <object>s is:
-
-\begin{verbatim}
- <?xml version="1.0" encoding="utf-8">
- <resource version="2.3.0.1">
- <object class="wxPanel">
- <style>wxSUNKEN_BORDER</style>
- <object class="wxStaticText">
- <label>A label</label>
- <pos>10,10</pos>
- </object>
- </object>
- </resource>
-\end{verbatim}
-
-\subsubsection{XRC format high-level description}
-
-An XRC resource file is a well-formed XML 1.0 document.
-
-The root node of XRC document must be <resource>. The <resource> node has
-optional {\it version} property. Default version (in absence of the version
-property) is "0.0.0.0". The version consists of four integers separated by
-periods. Version of XRC format changes only if there was an incompatible
-change introduced (i.e. either the library cannot understand old resource
-files or older versions of the library wouldn't understand the new format).
-The first three integers are major, minor and release number of the wxWindows
-release when the change was introduced, the last one is revision number and
-is 0 for the first incompatible change in given wxWindows release, 1 for
-the second, and so on.
-
-Differences between versions are described within this document in paragraphs
-entitled {\it Version Note}.
-
-The <resource> node is only allowed to have <object> and <object_ref>
-subnodes, all of which must have the "name" property.
-
-<object> - TODO (name, class, subclass)
-
-<object_ref> - TODO (name, ref, subclass)
-
-\subsubsection{Common XRC attributes}
-
-Coming soon.
-
-\subsubsection{Supported classes}
-
-Coming soon.
+Please see Technical Note 14 (docs/tech/tn0014.txt) in your wxWindows
+distribution.
\subsection{Adding new resource handlers}\label{newresourcehandlers}
projects / wxWidgets.git / commitdiff
