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