h1(#wxsizer). Wx::Sizer Sizer is the abstract base class used for laying out subwindows in a window. You cannot use Sizer directly; instead, you use one of the sizer classes derived from it. Currently there are "BoxSizer":boxsizer.html, "StaticBoxSizer":staticboxsizer.html, "GridSizer":gridsizer.html "FlexGridSizer":flexgridsizer.html and "GridBagSizer":gridbagsizer.html. The layout algorithm used by sizers in Widgets is closely related to layout in other GUI toolkits, such as Java's AWT, the GTK toolkit or the Qt toolkit. It is based upon the idea of the individual subwindows reporting their minimal required size and their ability to get stretched if the size of the parent window has changed. This will most often mean that the programmer does not set the original size of a dialog in the beginning. Instead, the dialog will be assigned a sizer and this sizer will be queried about the recommended size. The sizer in turn will query its children, which can be normal windows, empty space or other sizers, so that a hierarchy of sizers can be constructed. Note that Sizer does not derive from "Window":window.html and thus does not interfere with tab ordering and requires very few resources compared to a real window on screen. What makes sizers so well fitted for use in wxRuby is the fact that every control reports its own minimal size and the algorithm can handle differences in font sizes or different window (dialog item) sizes on different platforms without problems. If, for example the standard font as well as the overall design of GTK widgets requires more space than on Windows, the initial dialog size will automatically be bigger on GTK than on Windows. Sizers may also be used to control the layout of custom drawn items on the window. The "add":#Sizer_add, "insert":#Sizer_insert, "prepend":#Sizer_prepend, and "add_item":#Sizer_additem methods return the newly added "SizerItem":sizeritem.html. Just add empty space of the desired size and attributes, and then use the "SizerItem#get_rect":sizeritem.html#SizerItem_getrect method to determine where the drawing operations should take place. It is worth noting that "add_item":#Sizer_additem is more generic than "add":#Sizer_add, "insert":#Sizer_insert, and "prepend":#Sizer_prepend as it supports : * both the addition and the insertion of an item, * both positional and keyword arguments (an argument may be specified by its position or by its keyword). h2. Sizer options Sizers can control numerous aspects of window layout by varying the arguments to "add":#Sizer_add, "insert":#Sizer_insert, or "prepend":#Sizer_prepend. All these arguments can accept a "Window":window.html to be laid out, a spacer, or another "Sizer":sizer.html. This section discusses the key aspects of layout that can be controlled using sizers. It discusses it with reference to "BoxSizer":boxsizer.html, which is the commonest kind of Sizer. A BoxSizer simply arranges its contents in a horizontal row or vertical stack. The wxSizer.rb sample inside the wxRuby distribution demonstrates the use of a wide variety of these options in combination. h3. Adding elements to a Sizer h4. Adding Windows to Sizers A sizer can directly control the size of a Window, such as a control, or another container, like a panel. A windows initial size (either set explicitly by the user or calculated internally) is interpreted as the minimum and in many cases also the initial size. This is particularly useful in connection with "set_size_hints":#Sizer_setsizehints. h4. Using Sizers within Sizers Sizers can be nested within one another to create a hierarchy of sizers. They can be nested within one another, for example, to create a horizontal row of buttons with a vertical overall dialog layout. h4. Using Spacers within Sizers Adding spacers to sizers gives more flexibility in the design of dialogs; imagine for example a horizontal box with two buttons at the bottom of a dialog: you might want to insert a space between the two buttons and make that space stretchable using the _proportion_ flag and the result will be that the left button will be aligned with the left side of the dialog and the right button with the right side - the space in between will shrink and grow with the dialog. h3. Controlling the space given to Sizer elements One main feature of Sizers is that they can control how space is distributed to child windows as a containing "Frame":frame.html or "Dialog":dialog.html is resized by the user. h4. Size on the main axis The _proportion_ argument to "add":#Sizer_add control how the size in the main axis of the sizer is distributed to its children. For a vertical "BoxSizer":boxsizer.html, therefore, it controls how tall each widget is relative to the total space available. The size of each widget is determined by taking the total of all the proportion arguments of the widgets in the sizer, and then giving each widget a share of that based on its proportion argument. With three widgets, one with proportion 1, one with proportion 2, and one with proportion 3, the first would get 1/(1+2+3+) of the space, the second 2/(1+2+3), and the third 3/(1+2+3). So, if the three widgets were within a frame with a vertical sizer, and the total size of the frame was 150 pixels, the first widget would be 25px tall, the second 50px tall and the third 75px tall. If the frame were resized to 300 pixels tall, the first widget would now be 50px, the second 100px and the third 150px. A proportion argument of 0 is used to mean that the widget should maintain its natural minimum size, but should not grow or shrink as the container grows or shrinks. h4. Size on the minor axis Within a vertical BoxSizer, the stack is only one column of widgets wide, but the container may be resized to have a greater or smaller width. By default, each widgets will have their minimum width, but will not expand to fill the total width available if the container becomes wider. Including the @Wx::GROW@ (or, equivalent @Wx::EXPAND@) flag in the flags passed to "add":#Sizer_add will make the widget grow and shrink to fill the space in the minor axis (width in a vertical stack, height in a horizontal row) h3. Controlling element alignment For widgets that maintain a fixed size in one or other dimension as the sizer grows and shrinks, the alignment of the widget within the overall space available can be specified. Alignment is specified by passing flags to "add":#Sizer_add. Examples include @Wx::ALIGN_TOP@, which will keep the widget attached to the top of its assigned space in the sizer, @Wx::ALIGN_CENTRE@ and so forth. These flags can be combined to attach the widget to corners. h3. Controlling element borders Widgets within sizers can have blank space around them; this is needed to give an attractive appearance to dialogs and frames. Two aspects of border can be controlled. Firstly, the sides of the widget to which the border should be applied is set by a flag to "add":#Sizer_add, for example @Wx::TOP@ or @Wx::LEFT@. @Wx::ALL@ should be used to set a border on all sides. Secondly, an integer _border_ argument specifies the size of the border, in pixels. h2. Derived from "Object":object.html "ClientDataContainer":clientdatacontainer.html
h2. Methods * "Sizer.new":#Sizer_new * "Sizer#add_item":#Sizer_additem * "Sizer#add":#Sizer_add * "Sizer#add_spacer":#Sizer_addspacer * "Sizer#add_stretch_spacer":#Sizer_addstretchspacer * "Sizer#calc_min":#Sizer_calcmin * "Sizer#detach":#Sizer_detach * "Sizer#fit":#Sizer_fit * "Sizer#fit_inside":#Sizer_fitinside * "Sizer#get_children":#Sizer_getchildren * "Sizer#get_item":#Sizer_getitem * "Sizer#get_size":#Sizer_getsize * "Sizer#get_position":#Sizer_getposition * "Sizer#get_min_size":#Sizer_getminsize * "Sizer#insert":#Sizer_insert * "Sizer#insert_spacer":#Sizer_insertspacer * "Sizer#insert_stretch_spacer":#Sizer_insertstretchspacer * "Sizer#layout":#Sizer_layout * "Sizer#prepend":#Sizer_prepend * "Sizer#prepend_spacer":#Sizer_prependspacer * "Sizer#prepend_stretch_spacer":#Sizer_prependstretchspacer * "Sizer#recalc_sizes":#Sizer_recalcsizes * "Sizer#remove":#Sizer_remove * "Sizer#set_dimension":#Sizer_setdimension * "Sizer#set_min_size":#Sizer_setminsize * "Sizer#set_item_min_size":#Sizer_setitemminsize * "Sizer#set_size_hints":#Sizer_setsizehints * "Sizer#set_virtual_size_hints":#Sizer_setvirtualsizehints * "Sizer#show":#Sizer_show
h3(#Sizer_wxsizer). Sizer.new This method is abstract in this class - Wx::Sizer is never instantiated directly. See the specific subclass you are using (eg "BoxSizer":boxsizer.html ) for the parameters require by the constructor. h3(#Sizer_additem). Sizer#add_item "SizerItem":sizeritem.html *add_item*(%(arg-type)Object% item, %(arg-type)Integer% index = -1, %(arg-type)Integer% proportion = 0, %(arg-type)Integer% flag = 0, %(arg-type)Integer% border = 0, %(arg-type)Object% user_data = nil) Appends or inserts an item (a window, a child sizer, or a spacer) to the sizer. Optional parameters may also be specified by keywords in any order as following : sizer.add_item(an_item, :index => 1, :proportion => 1, :flag => Wx::EXPAND) h4. Parameters * _item_ A window,a child sizer, or a spacer to be added to the sizer. A spacer is defined by an array containing its width and its height. * _index_ If equals to -1, the item is added at the end of the sizer. Otherwise, it is inserted at the specified position. * _proportion_ The proportion of the sizer's space to be allocated to this item * _flag_ Sets a number of options including border location, resizing and alignment * _border_ The size of the border, in pixels * _user_data_ Not currently supported in wxRuby, not needed in normal use h4. Flags See "Sizer#add":sizer.html#Sizer_add h3(#Sizer_add). Sizer#add "SizerItem":sizeritem.html *add*(%(arg-type)"Window":window.html% window, %(arg-type)Integer% proportion = 0, %(arg-type)Integer% flag = 0, %(arg-type)Integer% border = 0, %(arg-type)Object% userData = nil) "SizerItem":sizeritem.html *add*(%(arg-type)"Sizer":sizer.html% sizer, %(arg-type)Integer% proportion = 0, %(arg-type)Integer% flag = 0, %(arg-type)Integer% border = 0, %(arg-type)Object% userData = nil) "SizerItem":sizeritem.html *add*(%(arg-type)Integer% width, %(arg-type)Integer% height, %(arg-type)Integer% proportion = 0, %(arg-type)Integer% flag = 0, %(arg-type)Integer% border = 0, %(arg-type)Object% userData = nil) Appends a child to the sizer. Sizer itself is an abstract class, but the parameters are equivalent in the derived classes that you will instantiate to use it so they are described here. The section above on using sizers describes in more detail how to use these arguments to control window size, proportion, border and alignment. The three different versions of this call allow a "Window":window.html, another "Sizer":sizer.html, or empty space to be added. * _window_ A window to be added to the sizer. * _sizer_ A child sizer to be added to the sizer * _width and height_ The dimension of a spacer to be added to the sizer. * _proportion_ The proportion of the sizer's space to be allocated to this item * _flag_ Sets a number of options including border location, resizing and alignment * _border_ The size of the border, in pixels * _userData_ Not currently supported in wxRuby, not needed in normal use h4. Flags The following flags are valid, and can be combined using | (the OR operator) @Wx::TOP@, @Wx::BOTTOM@, @Wx::LEFT@, @Wx::RIGHT@, @Wx::ALL@ : These flags are used to specify which side(s) of the sizer item the _border_ width will apply to. @Wx::EXPAND@ : The item will be expanded to fill the space assigned to the item. @Wx::SHAPED@ : The item will be expanded as much as possible while also maintaining its aspect ratio @Wx::FIXED_MINSIZE@ : Normally Sizers will use "get_adjusted_best_size":#Sizer_getadjustedbestsize to determine what the minimal size of window items should be, and will use that size to calculate the layout. This allows layouts to adjust when an item changes and its _best size_ becomes different. If you would rather have a window item stay the size itstarted with then use @Wx::FIXED_MINSIZE@. @Wx::ALIGN_CENTER@, @Wx::ALIGN_LEFT@, @Wx::ALIGN_RIGHT@, @Wx::ALIGN_TOP@, @Wx::ALIGN_BOTTOM@, @Wx::ALIGN_CENTER_VERTICAL@, @Wx::ALIGN_CENTER_HORIZONTAL@ The ALIGN flags allow you to specify the alignment of the item within the space allotted to it bythe sizer, adjusted for the border if any. h3(#Sizer_addspacer). Sizer#add_spacer "SizerItem":sizeritem.html *add_spacer*(%(arg-type)Integer% size) Adds non-stretchable space to the sizer. More readable way of calling "Add":sizeradd.html(size, size, 0). h3(#Sizer_addstretchspacer). Sizer#add_stretch_spacer "SizerItem":sizeritem.html *add_stretch_spacer*(%(arg-type)Integer% prop = 1) Adds stretchable space to the sizer. More readable way of calling "Add":sizeradd.html(0, 0, prop). h3(#Sizer_calcmin). Sizer#calc_min "Size":size.html *calc_min*() This method is abstract and has to be overwritten by any derived class. Here, the sizer will do the actual calculation of its children minimal sizes. h3(#Sizer_detach). Sizer#detach Boolean *detach*(%(arg-type)"Window":window.html% window) Boolean *detach*(%(arg-type)"Sizer":sizer.html% sizer) Boolean *detach*(%(arg-type)Integer% index) Detach a child from the sizer without destroying it. _window_ is the window to be detached, _sizer_ is the equivalent sizer and _index_ is the position of the child in the sizer, typically 0 for the first item. This method does not cause any layout or resizing to take place, call "Sizer#layout":sizer.html#Sizer_layout to update the layout "on screen" after detaching a child from the sizer. Returns true if the child item was found and detached, false otherwise. h4. See also "Sizer#remove":sizer.html#Sizer_remove h3(#Sizer_fit). Sizer#fit "Size":size.html *fit*(%(arg-type)"Window":window.html% window) Tell the sizer to resize the _window_ to match the sizer's minimal size. This is commonly done in the constructor of the window itself, see sample in the description of "BoxSizer":boxsizer.html. Returns the new size. For a top level window this is the total window size, not client size. h3(#Sizer_fitinside). Sizer#fit_inside *fit_inside*(%(arg-type)"Window":window.html% window) Tell the sizer to resize the virtual size of the _window_ to match the sizer's minimal size. This will not alter the on screen size of the window, but may cause the addition/removal/alteration of scrollbars required to view the virtual area in windows which manage it. h4. See also "ScrolledWindow#set_scrollbars":scrolledwindow.html#ScrolledWindow_setscrollbars, "Sizer#set_virtual_size_hints":sizer.html#Sizer_setvirtualsizehints h3(#Sizer_getchildren). Sizer#get_children Array *get_children*() Returns an array of "SizerItem":sizeritem.html objects with one corresponding to each Window, Sizer or spacer contained in this sizer. h3(#Sizer_getitem). Sizer#get_item "SizerItem":sizeritem.html *get_item*(%(arg-type)"Window":window.html% window, %(arg-type)Boolean% recursive = false) "SizerItem":sizeritem.html *get_item*(%(arg-type)"Sizer":sizer.html% sizer, %(arg-type)Boolean% recursive = false) "SizerItem":sizeritem.html *get_item*(%(arg-type)Integer% index) Finds item of the sizer which holds given _window_, _sizer_ or is located in sizer at position _index_. Use parameter _recursive_ to search in subsizers too. Returns nil if there is no such item. h3(#Sizer_getsize). Sizer#get_size "Size":size.html *get_size*() Returns the current size of the sizer. h3(#Sizer_getposition). Sizer#get_position "Point":point.html *get_position*() Returns the current position of the sizer. h3(#Sizer_getminsize). Sizer#get_min_size "Size":size.html *get_min_size*() Returns the minimal size of the sizer. This is either the combined minimal size of all the children and their borders or the minimal size set by "set_min_size":#Sizer_setminsize, depending on which is bigger. h3(#Sizer_insert). Sizer#insert "SizerItem":sizeritem.html *insert*(%(arg-type)Integer% index, %(arg-type)"Window":window.html% window, %(arg-type)Integer% proportion = 0, %(arg-type)Integer% flag = 0, %(arg-type)Integer% border = 0, %(arg-type)Object% userData = nil) "SizerItem":sizeritem.html *insert*(%(arg-type)Integer% index, %(arg-type)"Sizer":sizer.html% sizer, %(arg-type)Integer% proportion = 0, %(arg-type)Integer% flag = 0, %(arg-type)Integer% border = 0, %(arg-type)Object% userData = nil) "SizerItem":sizeritem.html *insert*(%(arg-type)Integer% index, %(arg-type)Integer% width, %(arg-type)Integer% height, %(arg-type)Integer% proportion = 0, %(arg-type)Integer% flag = 0, %(arg-type)Integer% border = 0, %(arg-type)Object% userData = nil) Insert a child into the sizer before any existing item at _index_. * _index_ The position this child should assume in the sizer. See "Sizer#add":sizer.html#Sizer_add for the meaning of the other parameters. h3(#Sizer_insertspacer). Sizer#insert_spacer "SizerItem":sizeritem.html *insert_spacer*(%(arg-type)Integer% index, %(arg-type)Integer% size) Inserts non-stretchable space to the sizer. More readable way of calling "Insert":sizerinsert.html(size, size, 0). h3(#Sizer_insertstretchspacer). Sizer#insert_stretch_spacer "SizerItem":sizeritem.html *insert_stretch_spacer*(%(arg-type)Integer% index, %(arg-type)Integer% prop = 1) Inserts stretchable space to the sizer. More readable way of calling "Insert":sizerinsert.html(0, 0, prop). h3(#Sizer_layout). Sizer#layout *layout*() Call this to force layout of the children anew, e.g. after having added a child to or removed a child (window, other sizer or space) from the sizer while keeping the current dimension. h3(#Sizer_prepend). Sizer#prepend "SizerItem":sizeritem.html *prepend*(%(arg-type)"Window":window.html% window, %(arg-type)Integer% proportion = 0, %(arg-type)Integer% flag = 0, %(arg-type)Integer% border = 0, %(arg-type)Object% userData = nil) "SizerItem":sizeritem.html *prepend*(%(arg-type)"Sizer":sizer.html% sizer, %(arg-type)Integer% proportion = 0, %(arg-type)Integer% flag = 0, %(arg-type)Integer% border = 0, %(arg-type)Object% userData = nil) "SizerItem":sizeritem.html *prepend*(%(arg-type)Integer% width, %(arg-type)Integer% height, %(arg-type)Integer% proportion = 0, %(arg-type)Integer% flag = 0, %(arg-type)Integer% border= 0, %(arg-type)Object% userData = nil) Same as "Sizer#add":sizer.html#Sizer_add, but prepends the items to the beginning of the list of items (windows, subsizers or spaces) owned by this sizer. See "Sizer#add":#Sizer_add and the introduction for a description of the use of the arguments. h3(#Sizer_prependspacer). Sizer#prepend_spacer "SizerItem":sizeritem.html *prepend_spacer*(%(arg-type)Integer% size) Prepends non-stretchable space to the sizer. More readable way of calling "Prepend":sizerprepend.html(size, size, 0). h3(#Sizer_prependstretchspacer). Sizer#prepend_stretch_spacer "SizerItem":sizeritem.html *prepend_stretch_spacer*(%(arg-type)Integer% prop = 1) Prepends stretchable space to the sizer. More readable way of calling "Prepend":sizerprepend.html(0, 0, prop). h3(#Sizer_recalcsizes). Sizer#recalc_sizes *recalc_sizes*() This method is abstract and has to be overwritten by any derived class. Here, the sizer will do the actual calculation of its children's positions and sizes. h3(#Sizer_remove). Sizer#remove Boolean *remove*(%(arg-type)"Sizer":sizer.html% sizer) Boolean *remove*(%(arg-type)Integer% index) Removes a child from the sizer and destroys it. _sizer_ is the Sizer to be removed, _index_ is the position of the child in the sizer, typically 0 for the first item. This method does not cause any layout or resizing to take place, call "Sizer#layout":sizer.html#Sizer_layout to update the layout "on screen" after removing a child from the sizer. If you have a variable holding a "Window":window.html you want to remove from a sizer, use "Sizer#detach":sizer.html#Sizer_detach instead. Returns true if the child item was found and removed, false otherwise. h3(#Sizer_setdimension). Sizer#set_dimension *set_dimension*(%(arg-type)Integer% x, %(arg-type)Integer% y, %(arg-type)Integer% width, %(arg-type)Integer% height) Call this to force the sizer to take the given dimension and thus force the items owned by the sizer to resize themselves according to the rules defined by the parameter in the "Add":sizeradd.html and "Prepend":sizerprepend.html methods. h3(#Sizer_setminsize). Sizer#set_min_size *set_min_size*(%(arg-type)Integer% width, %(arg-type)Integer% height) *set_min_size*(%(arg-type)"Size":size.html% size) Call this to give the sizer a minimal size. Normally, the sizer will calculate its minimal size based purely on how much space its children need. After calling this method "get_min_size":#Sizer_getminsize will return either the minimal size as requested by its children or the minimal size set here, depending on which is bigger. h3(#Sizer_setitemminsize). Sizer#set_item_min_size *set_item_min_size*(%(arg-type)"Window":window.html% window, %(arg-type)Integer% width, %(arg-type)Integer% height) *set_item_min_size*(%(arg-type)"Sizer":sizer.html% sizer, %(arg-type)Integer% width, %(arg-type)Integer% height) *set_item_min_size*(%(arg-type)Integer% index, %(arg-type)Integer% width, %(arg-type)Integer% height) Set an item's minimum size by window, sizer, or position. The item will be found recursively in the sizer's descendants. This function enables an application to set the size of an item after initial creation. h3(#Sizer_setsizehints). Sizer#set_size_hints *set_size_hints*(%(arg-type)"Window":window.html% window) Tell the sizer to set (and "Fit":sizerfit.html) the minimal size of the _window_ to match the sizer's minimal size. This is commonly done in the constructor of the window itself, see sample in the description of "BoxSizer":boxsizer.html if the window is resizable (as are many dialogs under Unix and frames on probably all platforms). h3(#Sizer_setvirtualsizehints). Sizer#set_virtual_size_hints *set_virtual_size_hints*(%(arg-type)"Window":window.html% window) Tell the sizer to set the minimal size of the _window_ virtual area to match the sizer's minimal size. For windows with managed scrollbars this will set them appropriately. h4. See also "ScrolledWindow#set_scrollbars":scrolledwindow.html#ScrolledWindow_setscrollbars h3(#Sizer_show). Sizer#show Boolean *show*(%(arg-type)"Window":window.html% window, %(arg-type)Boolean% show = true, %(arg-type)Boolean% recursive = false) Boolean *show*(%(arg-type)"Sizer":sizer.html% sizer, %(arg-type)Boolean% show = true, %(arg-type)Boolean% recursive = false) Boolean *show*(%(arg-type)Integer% index, %(arg-type)Boolean% show = true) Shows or hides the _window_, _sizer_, or item at _index_. To make a sizer item disappear or reappear, use show followed by "layout":#Sizer_layout. Use parameter _recursive_ to show or hide elements found in subsizers. Returns true if the child item was found, false otherwise. Note that this only works with "BoxSizer":boxsizer.html and "FlexGridSizer":flexgridsizer.html, since they are the only two sizer classes that can size rows/columns independently.