| 1 | \section{\class{wxSizer}}\label{wxsizer} |
| 2 | |
| 3 | wxSizer is the abstract base class used for laying out subwindows in a window. You |
| 4 | cannot use wxSizer directly; instead, you will have to use one of the sizer |
| 5 | classes derived from it. Currently there are \helpref{wxBoxSizer}{wxboxsizer}, |
| 6 | \helpref{wxStaticBoxSizer}{wxstaticboxsizer}, |
| 7 | \helpref{wxNotebookSizer}{wxnotebooksizer}, \helpref{wxGridSizer}{wxgridsizer} |
| 8 | and \helpref{wxFlexGridSizer}{wxflexgridsizer}. |
| 9 | |
| 10 | The layout algorithm used by sizers in wxWindows is closely related to layout |
| 11 | in other GUI toolkits, such as Java's AWT, the GTK toolkit or the Qt toolkit. It is |
| 12 | based upon the idea of the individual subwindows reporting their minimal required |
| 13 | size and their ability to get stretched if the size of the parent window has changed. |
| 14 | This will most often mean, that the programmer does not set the original size of |
| 15 | a dialog in the beginning, rather the dialog will assigned a sizer and this sizer |
| 16 | will be queried about the recommended size. The sizer in turn will query its |
| 17 | children, which can be normal windows, empty space or other sizers, so that |
| 18 | a hierarchy of sizers can be constructed. Note that wxSizer does not derive from wxWindow |
| 19 | and thus do not interfere with tab ordering and requires very little resources compared |
| 20 | to a real window on screen. |
| 21 | |
| 22 | What makes sizers so well fitted for use in wxWindows is the fact that every control |
| 23 | reports its own minimal size and the algorithm can handle differences in font sizes |
| 24 | or different window (dialog item) sizes on different platforms without problems. If e.g. |
| 25 | the standard font as well as the overall design of Motif widgets requires more space than |
| 26 | on Windows, the initial dialog size will automatically be bigger on Motif than on Windows. |
| 27 | |
| 28 | \pythonnote{If you wish to create a sizer class in wxPython you should |
| 29 | derive the class from {\tt wxPySizer} in order to get Python-aware |
| 30 | capabilities for the various virtual methods.} |
| 31 | |
| 32 | \wxheading{Derived from} |
| 33 | |
| 34 | \helpref{wxObject}{wxobject} |
| 35 | |
| 36 | \wxheading{See also} |
| 37 | |
| 38 | \helpref{Sizer overview}{sizeroverview} |
| 39 | |
| 40 | \latexignore{\rtfignore{\wxheading{Members}}} |
| 41 | |
| 42 | \membersection{wxSizer::wxSizer}\label{wxsizerwxsizer} |
| 43 | |
| 44 | \func{}{wxSizer}{\void} |
| 45 | |
| 46 | The constructor. Note that wxSizer is an abstract base class and may not |
| 47 | be instantiated. |
| 48 | |
| 49 | \membersection{wxSizer::\destruct{wxSizer}}\label{wxsizerdtor} |
| 50 | |
| 51 | \func{}{\destruct{wxSizer}}{\void} |
| 52 | |
| 53 | The destructor. |
| 54 | |
| 55 | \membersection{wxSizer::Add}\label{wxsizeradd} |
| 56 | |
| 57 | \func{void}{Add}{\param{wxWindow* }{window}, \param{int }{option = 0},\param{int }{flag = 0}, \param{int }{border = 0}, \param{wxObject* }{userData = NULL}} |
| 58 | |
| 59 | \func{void}{Add}{\param{wxSizer* }{sizer}, \param{int }{option = 0}, \param{int }{flag = 0}, \param{int }{border = 0}, \param{wxObject* }{userData = NULL}} |
| 60 | |
| 61 | \func{void}{Add}{\param{int }{width}, \param{int }{height}, \param{int }{option = 0}, \param{int }{flag = 0}, \param{int }{border = 0}, \param{wxObject* }{userData = NULL}} |
| 62 | |
| 63 | Adds the {\it window} to the sizer. As wxSizer itself is an abstract class, the parameters |
| 64 | have no meaning in the wxSizer class itself, but as there currently is only one class |
| 65 | deriving directly from wxSizer and this class does not override these methods, the meaning |
| 66 | of the parameters is described here: |
| 67 | |
| 68 | \docparam{window}{The window to be added to the sizer. Its initial size (either set explicitly by the |
| 69 | user or calculated internally when using wxDefaultSize) is interpreted as the minimal and in many |
| 70 | cases also the initial size. This is particularly useful in connection with \helpref{SetSizeHints}{wxsizersetsizehints}.} |
| 71 | |
| 72 | \docparam{sizer}{The (child-)sizer to be added to the sizer. This allows placing a child sizer in a |
| 73 | sizer and thus to create hierarchies of sizers (typically a vertical box as the top sizer and several |
| 74 | horizontal boxes on the level beneath).} |
| 75 | |
| 76 | \docparam{width and height}{The dimension of a spacer to be added to the sizer. Adding spacers to sizers |
| 77 | gives more flexibility in the design of dialogs; imagine for example a horizontal box with two buttons at the |
| 78 | bottom of a dialog: you might want to insert a space between the two buttons and make that space stretchable |
| 79 | using the {\it option} flag and the result will be that the left button will be aligned with the left |
| 80 | side of the dialog and the right button with the right side - the space in between will shrink and grow with |
| 81 | the dialog.} |
| 82 | |
| 83 | \docparam{option}{Although the meaning of this parameter is undefined in wxSizer, it is used in wxBoxSizer |
| 84 | to indicate if a child of a sizer can change its size in the main orientation of the wxBoxSizer - where |
| 85 | 0 stands for not changeable and a value of more than zero is interpreted relative to the value of other |
| 86 | children of the same wxBoxSizer. For example, you might have a horizontal wxBoxSizer with three children, two |
| 87 | of which are supposed to change their size with the sizer. Then the two stretchable windows would get a |
| 88 | value of 1 each to make them grow and shrink equally with the sizer's horizontal dimension.} |
| 89 | |
| 90 | \docparam{flag}{This parameter can be used to set a number of flags which can |
| 91 | be combined using the binary OR operator |. Two main behaviours are defined |
| 92 | using these flags. One is the border around a window: the {\it border} |
| 93 | parameter determines the border width whereas the flags given here determine |
| 94 | where the border may be (wxTOP, wxBOTTOM, wxLEFT, wxRIGHT or wxALL). The other |
| 95 | flags determine the child window's behaviour if the size of the sizer changes. |
| 96 | However this is not - in contrast to the {\it option} flag - in the main |
| 97 | orientation, but in the respectively other orientation. So if you created a |
| 98 | wxBoxSizer with the wxVERTICAL option, these flags will be relevant if the |
| 99 | sizer changes its horizontal size. A child may get resized to completely fill |
| 100 | out the new size (using either wxGROW or wxEXPAND), it may get proportionally |
| 101 | resized (wxSHAPED), it may get centered (wxALIGN\_CENTER or wxALIGN\_CENTRE) |
| 102 | or it may get aligned to either side (wxALIGN\_LEFT and wxALIGN\_TOP are set |
| 103 | to 0 and thus represent the default, wxALIGN\_RIGHT and wxALIGN\_BOTTOM have |
| 104 | their obvious meaning). With proportional resize, a child may also be centered |
| 105 | in the main orientation using wxALIGN\_CENTER\_VERTICAL (same as |
| 106 | wxALIGN\_CENTRE\_VERTICAL) and wxALIGN\_CENTER\_HORIZONTAL (same as |
| 107 | wxALIGN\_CENTRE\_HORIZONTAL) flags. Finally, you can also specify |
| 108 | wxADJUST\_MINSIZE flag to make the minimal size of the control dynamically adjust |
| 109 | to the value returned by its \helpref{GetBestSize()}{wxwindowgetbestsize} |
| 110 | method - this allows, for example, for correct relayouting of a static text |
| 111 | control even if its text is changed during run-time.} |
| 112 | |
| 113 | \docparam{border}{Determines the border width, if the {\it flag} parameter is set to any border.} |
| 114 | |
| 115 | \docparam{userData}{Allows an extra object to be attached to the sizer |
| 116 | item, for use in derived classes when sizing information is more |
| 117 | complex than the {\it option} and {\it flag} will allow for.} |
| 118 | |
| 119 | \membersection{wxSizer::CalcMin}\label{wxsizercalcmin} |
| 120 | |
| 121 | \func{wxSize}{CalcMin}{\void} |
| 122 | |
| 123 | This method is abstract and has to be overwritten by any derived class. |
| 124 | Here, the sizer will do the actual calculation of its children minimal sizes. |
| 125 | |
| 126 | \membersection{wxSizer::Fit}\label{wxsizerfit} |
| 127 | |
| 128 | \func{wxSize}{Fit}{\param{wxWindow* }{window}} |
| 129 | |
| 130 | Tell the sizer to resize the {\it window} to match the sizer's minimal size. This |
| 131 | is commonly done in the constructor of the window itself, see sample in the description |
| 132 | of \helpref{wxBoxSizer}{wxboxsizer}. Returns the new size. |
| 133 | |
| 134 | \membersection{wxSizer::FitInside}\label{wxsizerfitinside} |
| 135 | |
| 136 | \func{void}{FitInside}{\param{wxWindow* }{window}} |
| 137 | |
| 138 | Tell the sizer to resize the virtual size of the {\it window} to match the sizer's |
| 139 | minimal size. This will not alter the on screen size of the window, but may cause |
| 140 | the addition/removal/alteration of scrollbars required to view the virtual area in |
| 141 | windows which manage it. |
| 142 | |
| 143 | \wxheading{See also} |
| 144 | |
| 145 | \helpref{wxScrolledWindow::SetScrollbars}{wxscrolledwindowsetscrollbars},\rtfsp |
| 146 | \helpref{wxSizer::SetVirtualSizeHints}{wxsizersetvirtualsizehints} |
| 147 | |
| 148 | \membersection{wxSizer::GetSize}\label{wxsizergetsize} |
| 149 | |
| 150 | \func{wxSize}{GetSize}{\void} |
| 151 | |
| 152 | Returns the current size of the sizer. |
| 153 | |
| 154 | \membersection{wxSizer::GetPosition}\label{wxsizergetposition} |
| 155 | |
| 156 | \func{wxPoint}{GetPosition}{\void} |
| 157 | |
| 158 | Returns the current position of the sizer. |
| 159 | |
| 160 | \membersection{wxSizer::GetMinSize}\label{wxsizergetminsize} |
| 161 | |
| 162 | \func{wxSize}{GetMinSize}{\void} |
| 163 | |
| 164 | Returns the minimal size of the sizer. This is either the combined minimal |
| 165 | size of all the children and their borders or the minimal size set by |
| 166 | \helpref{SetMinSize}{wxsizersetminsize}, depending on which is bigger. |
| 167 | |
| 168 | \membersection{wxSizer::Layout}\label{wxsizerlayout} |
| 169 | |
| 170 | \func{void}{Layout}{\void} |
| 171 | |
| 172 | Call this to force layout of the children anew, e.g. after having added a child |
| 173 | to or removed a child (window, other sizer or space) from the sizer while keeping |
| 174 | the current dimension. |
| 175 | |
| 176 | \membersection{wxSizer::Prepend}\label{wxsizerprepend} |
| 177 | |
| 178 | \func{void}{Prepend}{\param{wxWindow* }{window}, \param{int }{option = 0}, \param{int }{flag = 0}, \param{int }{border = 0}, \param{wxObject* }{userData = NULL}} |
| 179 | |
| 180 | \func{void}{Prepend}{\param{wxSizer* }{sizer}, \param{int }{option = 0}, \param{int }{flag = 0}, \param{int }{border = 0}, \param{wxObject* }{userData = NULL}} |
| 181 | |
| 182 | \func{void}{Prepend}{\param{int }{width}, \param{int }{height}, \param{int }{option = 0}, \param{int }{flag = 0}, \param{int }{border= 0}, \param{wxObject* }{userData = NULL}} |
| 183 | |
| 184 | Same as \helpref{wxSizer::Add}{wxsizeradd}, but prepends the items to the beginning of the |
| 185 | list of items (windows, subsizers or spaces) owned by this sizer. |
| 186 | |
| 187 | \membersection{wxSizer::RecalcSizes}\label{wxsizerrecalcsizes} |
| 188 | |
| 189 | \func{void}{RecalcSizes}{\void} |
| 190 | |
| 191 | This method is abstract and has to be overwritten by any derived class. |
| 192 | Here, the sizer will do the actual calculation of its children's positions |
| 193 | and sizes. |
| 194 | |
| 195 | \membersection{wxSizer::Remove}\label{wxsizerremove} |
| 196 | |
| 197 | \func{bool}{Remove}{\param{wxWindow* }{window}} |
| 198 | |
| 199 | \func{bool}{Remove}{\param{wxSizer* }{sizer}} |
| 200 | |
| 201 | \func{bool}{Remove}{\param{int }{nth}} |
| 202 | |
| 203 | Removes a child from the sizer. {\it window} is the window to be removed, {\it sizer} is the |
| 204 | equivalent sizer and {\it nth} is the position of the child in the sizer, typically 0 for |
| 205 | the first item. This method does not cause any layout or resizing to take place and does |
| 206 | not delete the window itself. Call \helpref{wxSizer::Layout}{wxsizerlayout} to update |
| 207 | the layout "on screen" after removing a child from the sizer. |
| 208 | |
| 209 | Returns TRUE if the child item was found and removed, FALSE otherwise. |
| 210 | |
| 211 | \membersection{wxSizer::SetDimension}\label{wxsizersetdimension} |
| 212 | |
| 213 | \func{void}{SetDimension}{\param{int }{x}, \param{int }{y}, \param{int }{width}, \param{int }{height}} |
| 214 | |
| 215 | Call this to force the sizer to take the given dimension and thus force the items owned |
| 216 | by the sizer to resize themselves according to the rules defined by the parameter in the |
| 217 | \helpref{Add}{wxsizeradd} and \helpref{Prepend}{wxsizerprepend} methods. |
| 218 | |
| 219 | \membersection{wxSizer::SetMinSize}\label{wxsizersetminsize} |
| 220 | |
| 221 | \func{void}{SetMinSize}{\param{int }{width}, \param{int }{height}} |
| 222 | |
| 223 | \func{void}{SetMinSize}{\param{wxSize }{size}} |
| 224 | |
| 225 | Call this to give the sizer a minimal size. Normally, the sizer will calculate its |
| 226 | minimal size based purely on how much space its children need. After calling this |
| 227 | method \helpref{GetMinSize}{wxsizergetminsize} will return either the minimal size |
| 228 | as requested by its children or the minimal size set here, depending on which is |
| 229 | bigger. |
| 230 | |
| 231 | \membersection{wxSizer::SetItemMinSize}\label{wxsizersetitemminsize} |
| 232 | |
| 233 | \func{void}{SetItemMinSize}{\param{wxWindow* }{window}, \param{int}{ width}, \param{int}{ height}} |
| 234 | |
| 235 | \func{void}{SetItemMinSize}{\param{wxSizer* }{sizer}, \param{int}{ width}, \param{int}{ height}} |
| 236 | |
| 237 | \func{void}{SetItemMinSize}{\param{int}{ pos}, \param{int}{ width}, \param{int}{ height}} |
| 238 | |
| 239 | Set an item's minimum size by window, sizer, or position. The item will be found recursively |
| 240 | in the sizer's descendants. This function enables an application to set the size of an item |
| 241 | after initial creation. |
| 242 | |
| 243 | \membersection{wxSizer::SetSizeHints}\label{wxsizersetsizehints} |
| 244 | |
| 245 | \func{void}{SetSizeHints}{\param{wxWindow* }{window}} |
| 246 | |
| 247 | Tell the sizer to set (and \helpref{Fit}{wxsizerfit}) the minimal size of the {\it window} to |
| 248 | match the sizer's minimal size. This is commonly done in the constructor of the window itself, |
| 249 | see sample in the description of \helpref{wxBoxSizer}{wxboxsizer} if the window is resizable |
| 250 | (as are many dialogs under Unix and frames on probably all platforms). |
| 251 | |
| 252 | \membersection{wxSizer::SetVirtualSizeHints}\label{wxsizersetvirtualsizehints} |
| 253 | |
| 254 | \func{void}{SetVirtualSizeHints}{\param{wxWindow* }{window}} |
| 255 | |
| 256 | Tell the sizer to set the minimal size of the {\it window} virtual area to match the sizer's |
| 257 | minimal size. For windows with managed scrollbars this will set them appropriately. |
| 258 | |
| 259 | \wxheading{See also} |
| 260 | |
| 261 | \helpref{wxScrolledWindow::SetScrollbars}{wxscrolledwindowsetscrollbars} |
| 262 | |