]> git.saurik.com Git - wxWidgets.git/blame - docs/latex/wx/tsizer.tex
patch 1306473
[wxWidgets.git] / docs / latex / wx / tsizer.tex
CommitLineData
1c0c339c
JS
1\section{Sizer overview}\label{sizeroverview}
2
3Classes: \helpref{wxSizer}{wxsizer}, \helpref{wxGridSizer}{wxgridsizer},
4\helpref{wxFlexGridSizer}{wxflexgridsizer}, \helpref{wxBoxSizer}{wxboxsizer},
5\helpref{wxStaticBoxSizer}{wxstaticboxsizer},
2b5f62a0 6\helpref{CreateButtonSizer}{createbuttonsizer}
1c0c339c
JS
7
8Sizers, as represented by the wxSizer class and its descendants in
fc2171bd
JS
9the wxWidgets class hierarchy, have become the method of choice to
10define the layout of controls in dialogs in wxWidgets because of
1c0c339c
JS
11their ability to create visually appealing dialogs independent of the
12platform, taking into account the differences in size and style of
fc2171bd 13the individual controls. Unlike the original wxWidgets Dialog Editor,
5a7b6f80 14editors such as wxDesigner, DialogBlocks, XRCed and wxWorkshop create dialogs based exclusively on sizers,
1c0c339c
JS
15practically forcing the user to create platform independent layouts without compromises.
16
17The next section describes and shows what can be done with sizers.
18The following sections briefly describe how to program with individual sizer classes.
19
fc2171bd 20For information about the new wxWidgets resource system, which can describe
1c0c339c
JS
21sizer-based dialogs, see the \helpref{XML-based resource system overview}{xrcoverview}.
22
23\subsection{The idea behind sizers}\label{ideabehindsizers}
24
fc2171bd 25The layout algorithm used by sizers in wxWidgets is closely related to layout
1c0c339c
JS
26systems in other GUI toolkits, such as Java's AWT, the GTK toolkit or the Qt toolkit. It is
27based upon the idea of individual subwindows reporting their minimal required
28size and their ability to get stretched if the size of the parent window has changed.
29This will most often mean that the programmer does not set the start-up size of
30a dialog, the dialog will rather be assigned a sizer and this sizer
31will be queried about the recommended size. This sizer in turn will query its
32children (which can be normal windows, empty space or other sizers) so that
33a hierarchy of sizers can be constructed. Note that wxSizer does not derive from wxWindow
34and thus does not interfere with tab ordering and requires very few resources compared
35to a real window on screen.
36
fc2171bd 37What makes sizers so well fitted for use in wxWidgets is the fact that every control
1c0c339c
JS
38reports its own minimal size and the algorithm can handle differences in font sizes
39or different window (dialog item) sizes on different platforms without problems. For example, if
40the standard font as well as the overall design of Linux/GTK widgets requires more space than
41on Windows, the initial dialog size will automatically be bigger on Linux/GTK than on Windows.
42
fc2171bd 43There are currently five different kinds of sizers available in wxWidgets. Each represents
3980000c 44either a certain way to lay out dialog items in a dialog or it fulfills a special task
1c0c339c
JS
45such as wrapping a static box around a dialog item (or another sizer). These sizers will
46be discussed one by one in the text below. For more detailed information on how to use sizers
e676441f 47programmatically, please refer to the section \helpref{Programming with Sizers}{boxsizerprogramming}.
1c0c339c
JS
48
49\subsubsection{Common features}\label{sizerscommonfeatures}
50
51All sizers are containers, that is, they are used to lay out one dialog item (or several
52dialog items), which they contain. Such items are sometimes referred to as the children
53of the sizer. Independent of how the individual sizers lay out their children, all children
54have certain features in common:
55
56{\bf A minimal size:} This minimal size is usually identical to
57the initial size of the controls and may either be set explicitly in the wxSize field
fc2171bd 58of the control constructor or may be calculated by wxWidgets, typically by setting
1c0c339c
JS
59the height and/or the width of the item to -1. Note that only some controls can
60calculate their size (such as a checkbox) whereas others (such as a listbox)
61don't have any natural width or height and thus require an explicit size. Some controls
62can calculate their height, but not their width (e.g. a single line text control):
63
7af3ca16 64\newcommand{\myimage}[1]{\mbox{\image{0cm;0cm}{#1}}}
1c0c339c 65
7af3ca16
VZ
66\begin{center}
67\myimage{sizer03.eps}\gifsep
68\myimage{sizer04.eps}\gifsep
69\myimage{sizer05.eps}
70\end{center}
1c0c339c
JS
71
72{\bf A border:} The border is just empty space and is used to separate dialog items
73in a dialog. This border can either be all around, or at any combination of sides
74such as only above and below the control. The thickness of this border must be set
75explicitly, typically 5 points. The following samples show dialogs with only one
76dialog item (a button) and a border of 0, 5, and 10 pixels around the button:
77
7af3ca16
VZ
78\begin{center}
79\myimage{sizer00.eps}\gifsep
80\myimage{sizer01.eps}\gifsep
81\myimage{sizer02.eps}
82\end{center}
1c0c339c
JS
83
84{\bf An alignment:} Often, a dialog item is given more space than its minimal size
85plus its border. Depending on what flags are used for the respective dialog
86item, the dialog item can be made to fill out the available space entirely, i.e.
87it will grow to a size larger than the minimal size, or it will be moved to either
88the centre of the available space or to either side of the space. The following
89sample shows a listbox and three buttons in a horizontal box sizer; one button
90is centred, one is aligned at the top, one is aligned at the bottom:
91
7af3ca16
VZ
92\begin{center}
93\myimage{sizer06.eps}
94\end{center}
1c0c339c
JS
95
96{\bf A stretch factor:} If a sizer contains more than one child and it is offered
97more space than its children and their borders need, the question arises how to
98distribute the surplus space among the children. For this purpose, a stretch
99factor may be assigned to each child, where the default value of 0 indicates that the child
100will not get more space than its requested minimum size. A value of more than zero
101is interpreted in relation to the sum of all stretch factors in the children
102of the respective sizer, i.e. if two children get a stretch factor of 1, they will
103get half the extra space each {\it independent of whether one control has a minimal
104sizer inferior to the other or not}. The following sample shows a dialog with
105three buttons, the first one has a stretch factor of 1 and thus gets stretched,
106whereas the other two buttons have a stretch factor of zero and keep their
107initial width:
108
7af3ca16
VZ
109\begin{center}
110\myimage{sizer07.eps}
111\end{center}
1c0c339c
JS
112
113Within wxDesigner, this stretch factor gets set from the {\it Option} menu.
114
55f9f0cb
VZ
115\subsubsection{Hiding controls using sizers}\label{sizershiding}
116
117You can hide controls contained in sizers the same way you would hide any control,
118using the \helpref{wxWindow::Show}{wxwindowshow} method.
119
120However, wxSizer also offers a separate method which can tell the sizer not to
121consider that control in its size calculations. To hide a window using the sizer,
122call \helpref{wxSizer::Show}{wxsizershow}. You must then call Layout on the sizer
123to force an update.
124
125This is useful when hiding parts of the interface, since you can avoid removing
126the controls from the sizer and having to add them back later.
127
128Note: This is supported only by wxBoxSizer and wxFlexGridSizer.
129
1c0c339c
JS
130\wxheading{wxBoxSizer}
131
132\helpref{wxBoxSizer}{wxboxsizer} can lay out its children either vertically
133or horizontally, depending on what flag is being used in its constructor.
134When using a vertical sizer, each child can be centered, aligned to the
135right or aligned to the left. Correspondingly, when using a horizontal
136sizer, each child can be centered, aligned at the bottom or aligned at
137the top. The stretch factor described in the last paragraph is used
138for the main orientation, i.e. when using a horizontal box sizer, the
139stretch factor determines how much the child can be stretched horizontally.
140The following sample shows the same dialog as in the last sample,
141only the box sizer is a vertical box sizer now:
142
7af3ca16
VZ
143\begin{center}
144\myimage{sizer08.eps}
145\end{center}
1c0c339c
JS
146
147\wxheading{wxStaticBoxSizer}
148
149\helpref{wxStaticBoxSixer}{wxstaticboxsizer} is the same as a wxBoxSizer, but surrounded by a
150static box. Here is a sample:
151
7af3ca16
VZ
152\begin{center}
153\myimage{sizer09.eps}
154\end{center}
1c0c339c
JS
155
156\wxheading{wxGridSizer}
157
158\helpref{wxGridSizer}{wxgridsizer} is a two-dimensional sizer. All children are given the
159same size, which is the minimal size required by the biggest child, in
160this case the text control in the left bottom border. Either the number
161of columns or the number or rows is fixed and the grid sizer will grow
162in the respectively other orientation if new children are added:
163
7af3ca16
VZ
164\begin{center}
165\myimage{sizer10.eps}
166\end{center}
1c0c339c
JS
167
168For programming information, see \helpref{wxGridSizer}{wxgridsizer}.
169
170\wxheading{wxFlexGridSizer}
171
172Another two-dimensional sizer derived from
173wxGridSizer. The width of each column and the height of each row
3980000c 174are calculated individually according to the minimal requirements
1c0c339c
JS
175from the respectively biggest child. Additionally, columns and
176rows can be declared to be stretchable if the sizer is assigned
3980000c 177a size different from the one it requested. The following sample shows
1c0c339c
JS
178the same dialog as the one above, but using a flex grid sizer:
179
7af3ca16
VZ
180\begin{center}
181\myimage{sizer11.eps}
182\end{center}
1c0c339c 183
1c0c339c
JS
184\subsection{Programming with wxBoxSizer}\label{boxsizerprogramming}
185
186The basic idea behind a \helpref{wxBoxSizer}{wxboxsizer} is that windows will most often be laid out in rather
187simple basic geometry, typically in a row or a column or several hierarchies of either.
188
189As an example, we will construct a dialog that will contain a text field at the top and
190two buttons at the bottom. This can be seen as a top-hierarchy column with the text at
191the top and buttons at the bottom and a low-hierarchy row with an OK button to the left
192and a Cancel button to the right. In many cases (particularly dialogs under Unix and
193normal frames) the main window will be resizable by the user and this change of size
194will have to get propagated to its children. In our case, we want the text area to grow
195with the dialog, whereas the button shall have a fixed size. In addition, there will be
196a thin border around all controls to make the dialog look nice and - to make matter worse -
197the buttons shall be centred as the width of the dialog changes.
198
199It is the unique feature of a box sizer, that it can grow in both directions (height and
200width) but can distribute its growth in the main direction (horizontal for a row) {\it unevenly}
201among its children. In our example case, the vertical sizer is supposed to propagate all its
2b5f62a0 202height changes to only the text area, not to the button area. This is determined by the {\it proportion} parameter
1c0c339c
JS
203when adding a window (or another sizer) to a sizer. It is interpreted
204as a weight factor, i.e. it can be zero, indicating that the window may not be resized
205at all, or above zero. If several windows have a value above zero, the value is interpreted
206relative to the sum of all weight factors of the sizer, so when adding two windows with
207a value of 1, they will both get resized equally much and each half as much as the sizer
208owning them. Then what do we do when a column sizer changes its width? This behaviour is
209controlled by {\it flags} (the second parameter of the Add() function): Zero or no flag
210indicates that the window will preserve it is original size, wxGROW flag (same as wxEXPAND)
211forces the window to grow with the sizer, and wxSHAPED flag tells the window to change it is
212size proportionally, preserving original aspect ratio. When wxGROW flag is not used,
213the item can be aligned within available space. wxALIGN\_LEFT, wxALIGN\_TOP, wxALIGN\_RIGHT,
214wxALIGN\_BOTTOM, wxALIGN\_CENTER\_HORIZONTAL and wxALIGN\_CENTER\_VERTICAL do what they say.
215wxALIGN\_CENTRE (same as wxALIGN\_CENTER) is defined as (wxALIGN\_CENTER\_HORIZONTAL |
216wxALIGN\_CENTER\_VERTICAL). Default alignment is wxALIGN\_LEFT | wxALIGN\_TOP.
217
218As mentioned above, any window belonging to a sizer may have border, and it can be specified
219which of the four sides may have this border, using the wxTOP, wxLEFT, wxRIGHT and wxBOTTOM
220constants or wxALL for all directions (and you may also use wxNORTH, wxWEST etc instead). These
221flags can be used in combination with the alignment flags above as the second parameter of the
222Add() method using the binary or operator |. The sizer of the border also must be made known,
223and it is the third parameter in the Add() method. This means, that the entire behaviour of
224a sizer and its children can be controlled by the three parameters of the Add() method.
225
226\begin{verbatim}
227// we want to get a dialog that is stretchable because it
228// has a text ctrl at the top and two buttons at the bottom
229
230MyDialog::MyDialog(wxFrame *parent, wxWindowID id, const wxString &title )
231 : wxDialog(parent, id, title, wxDefaultPosition, wxDefaultSize,
232 wxDEFAULT_DIALOG_STYLE | wxRESIZE_BORDER)
233{
234 wxBoxSizer *topsizer = new wxBoxSizer( wxVERTICAL );
235
236 // create text ctrl with minimal size 100x60
237 topsizer->Add(
238 new wxTextCtrl( this, -1, "My text.", wxDefaultPosition, wxSize(100,60), wxTE_MULTILINE),
239 1, // make vertically stretchable
240 wxEXPAND | // make horizontally stretchable
241 wxALL, // and make border all around
242 10 ); // set border width to 10
243
244
245 wxBoxSizer *button_sizer = new wxBoxSizer( wxHORIZONTAL );
246 button_sizer->Add(
247 new wxButton( this, wxID_OK, "OK" ),
248 0, // make horizontally unstretchable
249 wxALL, // make border all around (implicit top alignment)
250 10 ); // set border width to 10
251 button_sizer->Add(
252 new wxButton( this, wxID_CANCEL, "Cancel" ),
253 0, // make horizontally unstretchable
254 wxALL, // make border all around (implicit top alignment)
255 10 ); // set border width to 10
256
257 topsizer->Add(
258 button_sizer,
259 0, // make vertically unstretchable
260 wxALIGN_CENTER ); // no border and centre horizontally
261
e5251d4f 262 SetSizer( topsizer ); // use the sizer for layout
1c0c339c 263
2edb0bde 264 topsizer->SetSizeHints( this ); // set size hints to honour minimum size
1c0c339c
JS
265}
266\end{verbatim}
267
40210d8a
RN
268Note that the new way of specifying flags to wxSizer is via \helpref{wxSizerFlags}{wxsizerflags}. This class greatly eases the burden of passing flags to a wxSizer.
269
270Here's how you'd do the previous example with wxSizerFlags:
271
272\begin{verbatim}
273// we want to get a dialog that is stretchable because it
274// has a text ctrl at the top and two buttons at the bottom
275
276MyDialog::MyDialog(wxFrame *parent, wxWindowID id, const wxString &title )
277 : wxDialog(parent, id, title, wxDefaultPosition, wxDefaultSize,
278 wxDEFAULT_DIALOG_STYLE | wxRESIZE_BORDER)
279{
280 wxBoxSizer *topsizer = new wxBoxSizer( wxVERTICAL );
281
282 // create text ctrl with minimal size 100x60 that is horizontally and
283 // vertically stretchable with a border width of 10
284 topsizer->Add(
285 new wxTextCtrl( this, -1, "My text.", wxDefaultPosition, wxSize(100,60), wxTE_MULTILINE),
286 wxSizerFlags(1).Align().Expand().Border(wxALL, 10));
287
288 wxBoxSizer *button_sizer = new wxBoxSizer( wxHORIZONTAL );
289
290 //create two buttons that are horizontally unstretchable,
291 // with an all-around border with a width of 10 and implicit top alignment
292 button_sizer->Add(
293 new wxButton( this, wxID_OK, "OK" ),
294 wxSizerFlags(0).Align().Border(wxALL, 10));
295
296 button_sizer->Add(
297 new wxButton( this, wxID_CANCEL, "Cancel" ),
298 wxSizerFlags(0).Align().Border(wxALL, 10));
299
300 //create a sizer with no border and centered horizontally
301 topsizer->Add(
302 button_sizer,
303 wxSizerFlags(0).Center() );
304
305 SetSizer( topsizer ); // use the sizer for layout
306
307 topsizer->SetSizeHints( this ); // set size hints to honour minimum size
308}
309\end{verbatim}
310
311
1c0c339c
JS
312\subsection{Programming with wxGridSizer}\label{gridsizerprogramming}
313
314\helpref{wxGridSizer}{wxgridsizer} is a sizer which lays out its children in a two-dimensional
315table with all table fields having the same size,
316i.e. the width of each field is the width of the widest child,
317the height of each field is the height of the tallest child.
318
319\subsection{Programming with wxFlexGridSizer}\label{flexgridsizerprogramming}
320
321\helpref{wxFlexGridSizer}{wxflexgridsizer} is a sizer which lays out its children in a two-dimensional
322table with all table fields in one row having the same
323height and all fields in one column having the same width, but all
324rows or all columns are not necessarily the same height or width as in
325the \helpref{wxGridSizer}{wxgridsizer}.
326
1c0c339c
JS
327\subsection{Programming with wxStaticBoxSizer}\label{staticboxsizerprogramming}
328
329\helpref{wxStaticBoxSizer}{wxstaticboxsizer} is a sizer derived from wxBoxSizer but adds a static
330box around the sizer. Note that this static box has to be created
331separately.
332
2b5f62a0
VZ
333\subsection{CreateButtonSizer}\label{createbuttonsizer}
334
335As a convenience, CreateButtonSizer ( long flags ) can be used to create a standard button sizer
336in which standard buttons are displayed. The following flags can be passed to this function:
337
338
339\begin{verbatim}
340 wxYES_NO // Add Yes/No subpanel
341 wxYES // return wxID_YES
342 wxNO // return wxID_NO
343 wxNO_DEFAULT // make the wxNO button the default, otherwise wxYES or wxOK button will be default
344
345 wxOK // return wxID_OK
346 wxCANCEL // return wxID_CANCEL
347 wxHELP // return wxID_HELP
348
349 wxFORWARD // return wxID_FORWARD
350 wxBACKWARD // return wxID_BACKWARD
351 wxSETUP // return wxID_SETUP
352 wxMORE // return wxID_MORE
353
354\end{verbatim}