| 1 | \section{Sizer overview}\label{sizeroverview} |
| 2 | |
| 3 | Classes: \helpref{wxSizer}{wxsizer}, \helpref{wxGridSizer}{wxgridsizer}, |
| 4 | \helpref{wxFlexGridSizer}{wxflexgridsizer}, \helpref{wxBoxSizer}{wxboxsizer}, |
| 5 | \helpref{wxStaticBoxSizer}{wxstaticboxsizer}, |
| 6 | \helpref{wxNotebookSizer}{wxnotebooksizer} |
| 7 | |
| 8 | Sizers, as represented by the wxSizer class and its descendants in |
| 9 | the wxWindows class hierarchy, have become the method of choice to |
| 10 | define the layout of controls in dialogs in wxWindows 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 wxWindows Dialog Editor, |
| 14 | editors such as wxDesigner, wxrcedit, XRCed and wxWorkshop create dialogs based exclusively on sizers, |
| 15 | practically forcing the user to create platform independent layouts without compromises. |
| 16 | |
| 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. |
| 19 | |
| 20 | For information about the new wxWindows resource system, which can describe |
| 21 | sizer-based dialogs, see the \helpref{XML-based resource system overview}{xrcoverview}. |
| 22 | |
| 23 | \subsection{The idea behind sizers}\label{ideabehindsizers} |
| 24 | |
| 25 | The layout algorithm used by sizers in wxWindows 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. |
| 36 | |
| 37 | What makes sizers so well fitted for use in wxWindows 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. |
| 42 | |
| 43 | There are currently five different kinds of sizers available in wxWindows. Each represents |
| 44 | either a certain way to lay out dialog items in a dialog or it fulfils 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}. |
| 48 | |
| 49 | \subsubsection{Common features}\label{sizerscommonfeatures} |
| 50 | |
| 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: |
| 55 | |
| 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 wxWindows, 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): |
| 63 | |
| 64 | \center{ |
| 65 | \image{}{sizer03.gif} |
| 66 | |
| 67 | \image{}{sizer04.gif} |
| 68 | |
| 69 | \image{}{sizer05.gif} |
| 70 | } |
| 71 | |
| 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: |
| 77 | |
| 78 | \center{ |
| 79 | \image{}{sizer00.gif} |
| 80 | |
| 81 | \image{}{sizer01.gif} |
| 82 | |
| 83 | \image{}{sizer02.gif} |
| 84 | } |
| 85 | |
| 86 | {\bf An alignment:} Often, a dialog item is given more space than its minimal size |
| 87 | plus its border. Depending on what flags are used for the respective dialog |
| 88 | item, the dialog item can be made to fill out the available space entirely, i.e. |
| 89 | it will grow to a size larger than the minimal size, or it will be moved to either |
| 90 | the centre of the available space or to either side of the space. The following |
| 91 | sample shows a listbox and three buttons in a horizontal box sizer; one button |
| 92 | is centred, one is aligned at the top, one is aligned at the bottom: |
| 93 | |
| 94 | \center{ |
| 95 | \image{}{sizer06.gif} |
| 96 | } |
| 97 | |
| 98 | {\bf A stretch factor:} If a sizer contains more than one child and it is offered |
| 99 | more space than its children and their borders need, the question arises how to |
| 100 | distribute the surplus space among the children. For this purpose, a stretch |
| 101 | factor may be assigned to each child, where the default value of 0 indicates that the child |
| 102 | will not get more space than its requested minimum size. A value of more than zero |
| 103 | is interpreted in relation to the sum of all stretch factors in the children |
| 104 | of the respective sizer, i.e. if two children get a stretch factor of 1, they will |
| 105 | get half the extra space each {\it independent of whether one control has a minimal |
| 106 | sizer inferior to the other or not}. The following sample shows a dialog with |
| 107 | three buttons, the first one has a stretch factor of 1 and thus gets stretched, |
| 108 | whereas the other two buttons have a stretch factor of zero and keep their |
| 109 | initial width: |
| 110 | |
| 111 | \center{ |
| 112 | \image{}{sizer07.gif} |
| 113 | } |
| 114 | |
| 115 | Within wxDesigner, this stretch factor gets set from the {\it Option} menu. |
| 116 | |
| 117 | \wxheading{wxBoxSizer} |
| 118 | |
| 119 | \helpref{wxBoxSizer}{wxboxsizer} can lay out its children either vertically |
| 120 | or horizontally, depending on what flag is being used in its constructor. |
| 121 | When using a vertical sizer, each child can be centered, aligned to the |
| 122 | right or aligned to the left. Correspondingly, when using a horizontal |
| 123 | sizer, each child can be centered, aligned at the bottom or aligned at |
| 124 | the top. The stretch factor described in the last paragraph is used |
| 125 | for the main orientation, i.e. when using a horizontal box sizer, the |
| 126 | stretch factor determines how much the child can be stretched horizontally. |
| 127 | The following sample shows the same dialog as in the last sample, |
| 128 | only the box sizer is a vertical box sizer now: |
| 129 | |
| 130 | \center{ |
| 131 | \image{}{sizer08.gif} |
| 132 | } |
| 133 | |
| 134 | \wxheading{wxStaticBoxSizer} |
| 135 | |
| 136 | \helpref{wxStaticBoxSixer}{wxstaticboxsizer} is the same as a wxBoxSizer, but surrounded by a |
| 137 | static box. Here is a sample: |
| 138 | |
| 139 | \center{ |
| 140 | \image{}{sizer09.gif} |
| 141 | } |
| 142 | |
| 143 | \wxheading{wxGridSizer} |
| 144 | |
| 145 | \helpref{wxGridSizer}{wxgridsizer} is a two-dimensional sizer. All children are given the |
| 146 | same size, which is the minimal size required by the biggest child, in |
| 147 | this case the text control in the left bottom border. Either the number |
| 148 | of columns or the number or rows is fixed and the grid sizer will grow |
| 149 | in the respectively other orientation if new children are added: |
| 150 | |
| 151 | \center{ |
| 152 | \image{}{sizer10.gif} |
| 153 | } |
| 154 | |
| 155 | For programming information, see \helpref{wxGridSizer}{wxgridsizer}. |
| 156 | |
| 157 | \wxheading{wxFlexGridSizer} |
| 158 | |
| 159 | Another two-dimensional sizer derived from |
| 160 | wxGridSizer. The width of each column and the height of each row |
| 161 | are calculated individually according the minimal requirements |
| 162 | from the respectively biggest child. Additionally, columns and |
| 163 | rows can be declared to be stretchable if the sizer is assigned |
| 164 | a size different from that which it requested. The following sample shows |
| 165 | the same dialog as the one above, but using a flex grid sizer: |
| 166 | |
| 167 | \center{ |
| 168 | \image{}{sizer11.gif} |
| 169 | } |
| 170 | |
| 171 | \wxheading{wxNotebookSizer} |
| 172 | |
| 173 | \helpref{wxNotebookSizer}{wxnotebooksizer} can be used in |
| 174 | connection with notebooks. It calculates the size of each |
| 175 | notebook page and sets the size of the notebook to the size |
| 176 | of the biggest page plus some extra space required for the |
| 177 | notebook tabs and decorations. |
| 178 | |
| 179 | \subsection{Programming with wxBoxSizer}\label{boxsizerprogramming} |
| 180 | |
| 181 | The basic idea behind a \helpref{wxBoxSizer}{wxboxsizer} is that windows will most often be laid out in rather |
| 182 | simple basic geometry, typically in a row or a column or several hierarchies of either. |
| 183 | |
| 184 | As an example, we will construct a dialog that will contain a text field at the top and |
| 185 | two buttons at the bottom. This can be seen as a top-hierarchy column with the text at |
| 186 | the top and buttons at the bottom and a low-hierarchy row with an OK button to the left |
| 187 | and a Cancel button to the right. In many cases (particularly dialogs under Unix and |
| 188 | normal frames) the main window will be resizable by the user and this change of size |
| 189 | will have to get propagated to its children. In our case, we want the text area to grow |
| 190 | with the dialog, whereas the button shall have a fixed size. In addition, there will be |
| 191 | a thin border around all controls to make the dialog look nice and - to make matter worse - |
| 192 | the buttons shall be centred as the width of the dialog changes. |
| 193 | |
| 194 | It is the unique feature of a box sizer, that it can grow in both directions (height and |
| 195 | width) but can distribute its growth in the main direction (horizontal for a row) {\it unevenly} |
| 196 | among its children. In our example case, the vertical sizer is supposed to propagate all its |
| 197 | height changes to only the text area, not to the button area. This is determined by the {\it option} parameter |
| 198 | when adding a window (or another sizer) to a sizer. It is interpreted |
| 199 | as a weight factor, i.e. it can be zero, indicating that the window may not be resized |
| 200 | at all, or above zero. If several windows have a value above zero, the value is interpreted |
| 201 | relative to the sum of all weight factors of the sizer, so when adding two windows with |
| 202 | a value of 1, they will both get resized equally much and each half as much as the sizer |
| 203 | owning them. Then what do we do when a column sizer changes its width? This behaviour is |
| 204 | controlled by {\it flags} (the second parameter of the Add() function): Zero or no flag |
| 205 | indicates that the window will preserve it is original size, wxGROW flag (same as wxEXPAND) |
| 206 | forces the window to grow with the sizer, and wxSHAPED flag tells the window to change it is |
| 207 | size proportionally, preserving original aspect ratio. When wxGROW flag is not used, |
| 208 | the item can be aligned within available space. wxALIGN\_LEFT, wxALIGN\_TOP, wxALIGN\_RIGHT, |
| 209 | wxALIGN\_BOTTOM, wxALIGN\_CENTER\_HORIZONTAL and wxALIGN\_CENTER\_VERTICAL do what they say. |
| 210 | wxALIGN\_CENTRE (same as wxALIGN\_CENTER) is defined as (wxALIGN\_CENTER\_HORIZONTAL | |
| 211 | wxALIGN\_CENTER\_VERTICAL). Default alignment is wxALIGN\_LEFT | wxALIGN\_TOP. |
| 212 | |
| 213 | As mentioned above, any window belonging to a sizer may have border, and it can be specified |
| 214 | which of the four sides may have this border, using the wxTOP, wxLEFT, wxRIGHT and wxBOTTOM |
| 215 | constants or wxALL for all directions (and you may also use wxNORTH, wxWEST etc instead). These |
| 216 | flags can be used in combination with the alignment flags above as the second parameter of the |
| 217 | Add() method using the binary or operator |. The sizer of the border also must be made known, |
| 218 | and it is the third parameter in the Add() method. This means, that the entire behaviour of |
| 219 | a sizer and its children can be controlled by the three parameters of the Add() method. |
| 220 | |
| 221 | \begin{verbatim} |
| 222 | // we want to get a dialog that is stretchable because it |
| 223 | // has a text ctrl at the top and two buttons at the bottom |
| 224 | |
| 225 | MyDialog::MyDialog(wxFrame *parent, wxWindowID id, const wxString &title ) |
| 226 | : wxDialog(parent, id, title, wxDefaultPosition, wxDefaultSize, |
| 227 | wxDEFAULT_DIALOG_STYLE | wxRESIZE_BORDER) |
| 228 | { |
| 229 | wxBoxSizer *topsizer = new wxBoxSizer( wxVERTICAL ); |
| 230 | |
| 231 | // create text ctrl with minimal size 100x60 |
| 232 | topsizer->Add( |
| 233 | new wxTextCtrl( this, -1, "My text.", wxDefaultPosition, wxSize(100,60), wxTE_MULTILINE), |
| 234 | 1, // make vertically stretchable |
| 235 | wxEXPAND | // make horizontally stretchable |
| 236 | wxALL, // and make border all around |
| 237 | 10 ); // set border width to 10 |
| 238 | |
| 239 | |
| 240 | wxBoxSizer *button_sizer = new wxBoxSizer( wxHORIZONTAL ); |
| 241 | button_sizer->Add( |
| 242 | new wxButton( this, wxID_OK, "OK" ), |
| 243 | 0, // make horizontally unstretchable |
| 244 | wxALL, // make border all around (implicit top alignment) |
| 245 | 10 ); // set border width to 10 |
| 246 | button_sizer->Add( |
| 247 | new wxButton( this, wxID_CANCEL, "Cancel" ), |
| 248 | 0, // make horizontally unstretchable |
| 249 | wxALL, // make border all around (implicit top alignment) |
| 250 | 10 ); // set border width to 10 |
| 251 | |
| 252 | topsizer->Add( |
| 253 | button_sizer, |
| 254 | 0, // make vertically unstretchable |
| 255 | wxALIGN_CENTER ); // no border and centre horizontally |
| 256 | |
| 257 | SetAutoLayout( TRUE ); // tell dialog to use sizer |
| 258 | SetSizer( topsizer ); // actually set the sizer |
| 259 | |
| 260 | topsizer->Fit( this ); // set size to minimum size as calculated by the sizer |
| 261 | topsizer->SetSizeHints( this ); // set size hints to honour mininum size |
| 262 | } |
| 263 | \end{verbatim} |
| 264 | |
| 265 | \subsection{Programming with wxGridSizer}\label{gridsizerprogramming} |
| 266 | |
| 267 | \helpref{wxGridSizer}{wxgridsizer} is a sizer which lays out its children in a two-dimensional |
| 268 | table with all table fields having the same size, |
| 269 | i.e. the width of each field is the width of the widest child, |
| 270 | the height of each field is the height of the tallest child. |
| 271 | |
| 272 | \subsection{Programming with wxFlexGridSizer}\label{flexgridsizerprogramming} |
| 273 | |
| 274 | \helpref{wxFlexGridSizer}{wxflexgridsizer} is a sizer which lays out its children in a two-dimensional |
| 275 | table with all table fields in one row having the same |
| 276 | height and all fields in one column having the same width, but all |
| 277 | rows or all columns are not necessarily the same height or width as in |
| 278 | the \helpref{wxGridSizer}{wxgridsizer}. |
| 279 | |
| 280 | \subsection{Programming with wxNotebookSizer}\label{notebooksizerprogramming} |
| 281 | |
| 282 | \helpref{wxNotebookSizer}{wxnotebooksizer} is a specialized sizer to make sizers work in connection |
| 283 | with using notebooks. This sizer is different from any other sizer as |
| 284 | you must not add any children to it - instead, it queries the notebook class itself. |
| 285 | The only thing this sizer does is to determine the size of the biggest |
| 286 | page of the notebook and report an adjusted minimal size to a more toplevel |
| 287 | sizer. |
| 288 | |
| 289 | In order to query the size of notebook page, this page needs to have its |
| 290 | own sizer, otherwise the wxNotebookSizer will ignore it. Notebook pages |
| 291 | get there sizer by assiging one to them using \helpref{wxWindow::SetSizer}{wxwindowsetsizer} |
| 292 | and setting the auto-layout option to TRUE using |
| 293 | \helpref{wxWindow::SetAutoLayout}{wxwindowsetautolayout}. Here is one |
| 294 | example showing how to add a notebook page that the notebook sizer is |
| 295 | aware of: |
| 296 | |
| 297 | \begin{verbatim} |
| 298 | wxNotebook *notebook = new wxNotebook( &dialog, -1 ); |
| 299 | wxNotebookSizer *nbs = new wxNotebookSizer( notebook ); |
| 300 | |
| 301 | // Add panel as notebook page |
| 302 | wxPanel *panel = new wxPanel( notebook, -1 ); |
| 303 | notebook->AddPage( panel, "My Notebook Page" ); |
| 304 | |
| 305 | wxBoxSizer *panelsizer = new wxBoxSizer( wxVERTICAL ); |
| 306 | |
| 307 | // Add controls to panel and panelsizer here... |
| 308 | |
| 309 | panel->SetAutoLayout( TRUE ); |
| 310 | panel->SetSizer( panelsizer ); |
| 311 | \end{verbatim} |
| 312 | |
| 313 | \subsection{Programming with wxStaticBoxSizer}\label{staticboxsizerprogramming} |
| 314 | |
| 315 | \helpref{wxStaticBoxSizer}{wxstaticboxsizer} is a sizer derived from wxBoxSizer but adds a static |
| 316 | box around the sizer. Note that this static box has to be created |
| 317 | separately. |
| 318 | |