All sizers are containers—that is, they are used to lay out one or more elements, which they contain. No matter how the individual sizers lay out their children, all children have certain features in common.

A minimal size: The minimal size of a control is calculated from the control’s notion of its “best size” (supplied by implementing DoGetBestSize for each control). This is the control’s natural size. For example, the best size of a check box comprises the space taken up by the check box graphic and the label. However, if you want the initial window size (as passed to the window’s constructor) to be used as the minimal size instead, you can use the wxFIXED_MINSIZE style when adding the control to a sizer. Note that only some windows can calculate their size (such as a check box), whereas others (such as a list box) don’t have any natural width or height and thus require an explicit size. Some windows can calculate their height, but not their width—for example, a single-line text control. Figure 7-3 shows three controls on their own in a dialog, showing how they expand the dialog to fit their own minimal size.

Figure 7-3 Windows reporting their minimal size

A border: The border is just empty space that is used to separate elements. This border can be all around, or it can be at any combination of sides, such as only above and below the control. The thickness of this border must be set explicitly, typically 5 pixels. Figure 7-4 shows dialogs with only one control (a button) and a border of 0, 5, and 10 pixels around the button, respectively.

Figure 7-4 Different border sizes

An alignment: An element can be moved to the center of the available space, or to either side of the space. Figure 7-5 shows a horizontal box sizer containing a list box and three buttons. One button is centered, one is aligned at the top, and one is aligned at the bottom. Alignment can be specified in horizontal or vertical orientations, but for most sizers, only one of these will have an effect. For example, in Figure 7-5, we have specified alignment in the vertical orientation, but horizontal alignment isn’t possible because of the way space is distributed among children of the sizer. (To achieve the effect of horizontal alignment, we would need to insert a stretching spacer, which we will look at shortly.)

Figure 7-5 Sizer alignment

A stretch factor: If a sizer contains more than one child and is offered more space than its children and their borders need, the surplus space needs to be distributed among the children. For this purpose, a stretch factor may be assigned to each child, where the default value of zero indicates that the child will not get more space than its requested minimal 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, so if two children get a stretch factor of 1, they will each get half the extra space, independent of their minimal size. Figure 7-6 shows a dialog with three buttons, at the initial size and after resizing. The first button 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.

Figure 7-6 Stretch factor

Note that the term “proportion” is sometimes used instead of stretch factor in the wxWidgets reference manual.

wxBoxSizer can lay out its children either vertically or horizontally, depending on the style passed to 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 previously is used for the main orientation, so when using a horizontal box sizer, the stretch factor determines how much the child can be stretched horizontally. Figure 7-7 shows the same dialog as in Figure 7-6, except that the sizer is a vertical box sizer.

Figure 7-7 A verical wxBoxSizer

You add child elements to a box sizer with Add:

The first parameter is a window or sizer.

The second is the proportion or stretch factor.

The third parameter is a bit-list specifying alignment behavior and borders. The alignment flags specify what happens when a vertical sizer changes its width, or when a horizontal sizer changes its height. The allowed values for specifying alignment and borders are shown in Table 7-1. The default alignment is wxALIGN_LEFT ¦ wxALIGN_TOP.

The fourth parameter specifies the size of the border (on the edges that have been specified in the flags parameter).

You can also add a spacer. There are three ways to do this:

The second method is the equivalent of calling Add(size, size, 0), and the third method is equivalent to calling Add(0, 0, stretch).

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 at the top level as a column with the text at the top and buttons at the bottom, and at the second level as a row with an OK button to the left and a Cancel button to the right. In many cases, the main window will be resizable by the user, and this change of size will have to be propagated to its children. Here, we want the text area to grow with the dialog, whereas the buttons should have a fixed size. In addition, the buttons will be centered as the width of the dialog changes. Figure 7-8 shows how it will look.

Figure 7-8 A simple dialog using sizers

Here’s the code that produces this dialog:

wxStaticBoxSizer is a sizer derived from wxBoxSizer that manages a static box around the sizer. Note that this static box has to be created separately. Create wxStaticBoxSizer by passing a pointer to the static box and the orientation (wxHORIZONTAL or wxVERTICAL). The Add function is the same as for wxBoxSizer.

Figure 7-9 shows an example of a dialog with a static box containing a check box control.

Figure 7-9 A wxStaticBoxSizer

Here’s the corresponding code:

wxGridSizer is a sizer that lays out its children in a two-dimensional table with all table fields having the same size; that is, the width of each field is the width of the widest child, and the height of each field is the height of the tallest child. Create a wxGridSizer by passing the number of rows, number of columns, extra vertical gap between children, and extra horizontal gap between children. Add is the same as for wxBoxSizer.

Figure 7-10 shows a grid sizer with three columns and two rows. The extra size of the second button has caused the space occupied by all the buttons to increase because all the cells of a wxGridSizer are the same size.

Figure 7-10 A wxGridSizer

Here’s the code:

wxFlexGridSizer is a sizer that 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. However, unlike wxGridSizer, all rows or all columns are not necessarily the same height or width: this will depend on the size of elements in a row or column. Additionally, columns and rows can be declared to be stretchable, which means that as the sizer is expanded, these columns or rows will be allocated extra space.

Create a wxFlexGridSizer by passing the number of rows, number of columns, extra vertical gap between children, and extra horizontal gap between children. Add is the same as for wxBoxSizer.

Figure 7-11 shows a flex grid sizer at its initial size, where the first column has been made stretchable. It’s essentially the same as the wxGridSizer example, but as you can see, the layout is more compact because the size of the middle column is not reflected in the other columns.

Figure 7-11 A wxFlexGridSizer at its initial size

Initially, we don’t see the effect of making the first column stretchable, but if we stretch it horizontally, as in Figure 7-12, we can see this column (containing buttons One and Four) taking up the extra space, with the buttons centered in the column.

Figure 7-12 A resized wxFlexGridSizer

Here’s the code that creates the dialogs we’ve shown:

This sizer attempts to reconcile the worlds of absolute positioning and sizer-based layout. It can lay out elements in a virtual grid, like a flex grid sizer, but in this case item row and column positions are specified using wxGBPosition, and items can optionally span more than one row and/or column using wxGBSpan.

When creating a wxGridBagSizer, optionally pass sizers for vertical and horizontal gaps between rows and columns (defaulting to zero). Use the Add function to add windows or sizers, passing the position and optional span, plus optional flags and border size as for wxBoxSizer.

Figure 7-13 shows a simple grid bag sizer example with four buttons, one of them spanning two columns (button Two). We also specify that the second row and third column are growable so that when we resize the dialog, we get the effect shown in Figure 7-14.

Figure 7-13 A wxGridBagSizer at its original size

Figure 7-14 A wxGridBagSizer after resizing

Here’s the code that produces this layout:

Although sizers protect you from changes in basic control size on different platforms and in different languages, you may still have some hard-coded sizes in your dialogs (for example, for list boxes). If you would like these sizes to adjust to the current system font (or font supplied by the application), you can use dialog units instead of pixels. Dialog units are based on average character width and height for a window’s font, and so the actual pixel dimension for a given dialog unit value will vary according to the current font. wxWindow has functions ConvertDialogToPixels and ConvertPixelsToDialog, and a convenience macro wxDLG_UNIT(window, ptOrSz) that can be used with both wxPoint and wxSize objects. So instead of passing a pixel size to your control, use the wxDLG_UNIT macro, for example:

Dialog units can be specified in an XRC file by appending “d” to dimension values.

Although dialogs on different platforms are largely similar, sometimes the style guides are incompatible. For example, on Windows and Linux, it’s acceptable to have right-justified or centered OK, Cancel, and Help buttons, in that order. On Mac OS X, the Help should be on the left, and Cancel and OK buttons are right aligned, in that order.

To help with this issue, wxStdDialogButtonSizer is provided. It’s derived from wxBoxSizer, so it can be used in a similar way, but its orientation will depend on platform.

This sizer’s constructor has no arguments. There are two ways of adding buttons: pass the button pointer to AddButton, or (if you’re not using standard identifiers) call SetAffirmativeButton, SetNegativeButton, and SetCancelButton. If using AddButton, you should use identifiers from this list: wxID_OK, wxID_YES, wxID_CANCEL, wxID_NO, wxID_SAVE, wxID_APPLY, wxID_HELP, and wxID_CONTEXT_HELP.

Then, after the buttons have been added, call Realize so that the sizer can add the buttons in the appropriate order with the appropriate spacing (which it can only do when it knows about all the buttons in the sizer). The following code creates a standard button sizer with OK, Cancel, and Help buttons:

As a convenience, wxDialog::CreateButtonSizer can be used, indirectly creating a wxStdDialogButtonSizer with buttons based on a flag list. If you look at the dialog implementations in src/generic, you will see that CreateButtonSizer is used for many of them. The flags in Table 7-2 can be passed to this function.

Using CreateButtonSizer simplifies the example code shown previously to the following:

There is another way to specify variations in UI on different platforms. XRC allows a platform parameter to be associated with each object; this parameter’s value can be a combination of unix, win, mac, and os2 separated by the pipe character (“¦”). XRC will only create the element if the platform value matches the actual platform the program is running on. DialogBlocks supports this property and can generate conditional C++ code if XRC is not being used.

Alternatively, you can load a different XRC file for each platform, but this is harder to maintain than having the differences contained within a single dialog design.

Sometimes you’d like the layout to change dynamically; for example, clicking on a Details button might expand the dialog and show further controls. You can hide controls contained in sizers the same way you would hide any control, using the wxWindow::Show method. However, wxSizer also offers a separate method, which can tell the sizer not to consider a window in its size calculations. To hide a window using the sizer, pass false to wxSizer::Show. You must then call wxSizer::Layout to force an update.