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