| 1 | \section{\class{wxBoxSizer}}\label{wxboxsizer} |
| 2 | |
| 3 | The basic idea behind a box sizer is that windows will most often be laid out in rather |
| 4 | simple basic geometry, typically in a row or a column or several hierarchies of either. |
| 5 | |
| 6 | As an example, we will construct a dialog that will contain a text field at the top and |
| 7 | two buttons at the bottom. This can be seen as a top-hierarchy column with the text at |
| 8 | the top and buttons at the bottom and a low-hierarchy row with an OK button to the left |
| 9 | and a Cancel button to the right. In many cases (particularly dialogs under Unix and |
| 10 | normal frames) the main window will be resizable by the user and this change of size |
| 11 | will have to get propagated to its children. In our case, we want the text area to grow |
| 12 | with the dialog, whereas the button shall have a fixed size. In addition, there will be |
| 13 | a thin border around all controls to make the dialog look nice and - to make matter worse - |
| 14 | the buttons shall be centred as the width of the dialog changes. |
| 15 | |
| 16 | It is the unique feature of a box sizer, that it can grow in both directions (height and |
| 17 | width) but can distribute its growth in the main direction (horizontal for a row) {\it unevenly} |
| 18 | among its children. In our example case, the vertical sizer is supposed to propagate all its |
| 19 | height changes to only the text area, not to the button area. This is determined by the {\it option} parameter |
| 20 | when adding a window (or another sizer) to a sizer. It is interpreted |
| 21 | as a weight factor, i.e. it can be zero, indicating that the window may not be resized |
| 22 | at all, or above zero. If several windows have a value above zero, the value is interpreted |
| 23 | relative to the sum of all weight factors of the sizer, so when adding two windows with |
| 24 | a value of 1, they will both get resized equally much and each half as much as the sizer |
| 25 | owning them. Then what do we do when a column sizer changes its width? This behaviour is |
| 26 | controlled by {\it flags} (the second parameter of the Add() function): Zero or no flag |
| 27 | indicates that the window will preserve it is original size, wxGROW flag (same as wxEXPAND) |
| 28 | forces the window to grow with the sizer, and wxSHAPED flag tells the window to change it is |
| 29 | size proportionally, preserving original aspect ratio. When wxGROW flag is not used, |
| 30 | the item can be aligned within available space. wxALIGN\_LEFT, wxALIGN\_TOP, wxALIGN\_RIGHT, |
| 31 | wxALIGN\_BOTTOM, wxALIGN\_CENTER\_HORIZONTAL and wxALIGN\_CENTER\_VERTICAL do what they say. |
| 32 | wxALIGN\_CENTRE (same as wxALIGN\_CENTER) is defined as (wxALIGN\_CENTER\_HORIZONTAL | |
| 33 | wxALIGN\_CENTER\_VERTICAL). Default alignment is wxALIGN\_LEFT | wxALIGN\_TOP. |
| 34 | |
| 35 | As mentioned above, any window belonging to a sizer may have border, and it can be specified |
| 36 | which of the four sides may have this border, using the wxTOP, wxLEFT, wxRIGHT and wxBOTTOM |
| 37 | constants or wxALL for all directions (and you may also use wxNORTH, wxWEST etc instead). These |
| 38 | flags can be used in combination with the alignment flags above as the second parameter of the |
| 39 | Add() method using the binary or operator |. The sizer of the border also must be made known, |
| 40 | and it is the third parameter in the Add() method. This means, that the entire behaviour of |
| 41 | a sizer and its children can be controlled by the three parameters of the Add() method. |
| 42 | |
| 43 | \begin{verbatim} |
| 44 | // we want to get a dialog that is stretchable because it |
| 45 | // has a text ctrl at the top and two buttons at the bottom |
| 46 | |
| 47 | MyDialog::MyDialog(wxFrame *parent, wxWindowID id, const wxString &title ) |
| 48 | : wxDialog(parent, id, title, wxDefaultPosition, wxDefaultSize, |
| 49 | wxDEFAULT_DIALOG_STYLE | wxRESIZE_BORDER) |
| 50 | { |
| 51 | wxBoxSizer *topsizer = new wxBoxSizer( wxVERTICAL ); |
| 52 | |
| 53 | // create text ctrl with minimal size 100x60 |
| 54 | topsizer->Add( |
| 55 | new wxTextCtrl( this, -1, "My text.", wxDefaultPosition, wxSize(100,60), wxTE_MULTILINE), |
| 56 | 1, // make vertically stretchable |
| 57 | wxEXPAND | // make horizontally stretchable |
| 58 | wxALL, // and make border all around |
| 59 | 10 ); // set border width to 10 |
| 60 | |
| 61 | |
| 62 | wxBoxSizer *button_sizer = new wxBoxSizer( wxHORIZONTAL ); |
| 63 | button_sizer->Add( |
| 64 | new wxButton( this, wxID_OK, "OK" ), |
| 65 | 0, // make horizontally unstretchable |
| 66 | wxALL, // make border all around (implicit top alignment) |
| 67 | 10 ); // set border width to 10 |
| 68 | button_sizer->Add( |
| 69 | new wxButton( this, wxID_CANCEL, "Cancel" ), |
| 70 | 0, // make horizontally unstretchable |
| 71 | wxALL, // make border all around (implicit top alignment) |
| 72 | 10 ); // set border width to 10 |
| 73 | |
| 74 | topsizer->Add( |
| 75 | button_sizer, |
| 76 | 0, // make vertically unstretchable |
| 77 | wxALIGN_CENTER ); // no border and centre horizontally |
| 78 | |
| 79 | SetAutoLayout( TRUE ); // tell dialog to use sizer |
| 80 | SetSizer( topsizer ); // actually set the sizer |
| 81 | |
| 82 | topsizer->Fit( this ); // set size to minimum size as calculated by the sizer |
| 83 | topsizer->SetSizeHints( this ); // set size hints to honour mininum size |
| 84 | } |
| 85 | \end{verbatim} |
| 86 | |
| 87 | \wxheading{Derived from} |
| 88 | |
| 89 | \helpref{wxSizer}{wxsizer}\\ |
| 90 | \helpref{wxObject}{wxobject} |
| 91 | |
| 92 | \membersection{wxBoxSizer::wxBoxSizer}\label{wxboxsizerwxboxsizer} |
| 93 | |
| 94 | \func{}{wxBoxSizer}{\param{int }{orient}} |
| 95 | |
| 96 | Constructor for a wxBoxSizer. {\it orient} may be either of wxVERTICAL |
| 97 | or wxHORIZONTAL for creating either a column sizer or a row sizer. |
| 98 | |
| 99 | \membersection{wxBoxSizer::RecalcSizes}\label{wxboxsizerrecalcsizes} |
| 100 | |
| 101 | \func{void}{RecalcSizes}{\void} |
| 102 | |
| 103 | Implements the calculation of a box sizer's dimensions and then sets |
| 104 | the size of its its children (calling \helpref{wxWindow::SetSize}{wxwindowsetsize} |
| 105 | if the child is a window). It is used internally only and must not be called |
| 106 | by the user. Documented for information. |
| 107 | |
| 108 | \membersection{wxBoxSizer::CalcMin}\label{wxboxsizercalcmin} |
| 109 | |
| 110 | \func{wxSize}{CalcMin}{\void} |
| 111 | |
| 112 | Implements the calculation of a box sizer's minimal. It is used internally |
| 113 | only and must not be called by the user. Documented for information. |
| 114 | |
| 115 | \membersection{wxBoxSizer::GetOrientation}\label{wxboxsizergetorientation} |
| 116 | |
| 117 | \func{int}{GetOrientation}{\void} |
| 118 | |
| 119 | Returns the orientation of the box sizer, either wxVERTICAL |
| 120 | or wxHORIZONTAL. |
| 121 | |