wxRuby Documentation Home

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, StaticBoxSizer, GridSizer FlexGridSizer and GridBagSizer.

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 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, insert, prepend, and add_item methods return the newly added SizerItem. Just add empty space of the desired size and attributes, and then use the SizerItem#get_rect method to determine where the drawing operations should take place. It is worth noting that add_item is more generic than add, insert, and prepend as it supports :

Sizer options

Sizers can control numerous aspects of window layout by varying the arguments to add, insert, or prepend. All these arguments can accept a Window to be laid out, a spacer, or another Sizer.

This section discusses the key aspects of layout that can be controlled using sizers. It discusses it with reference to BoxSizer, 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.

Adding elements to a Sizer

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.

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.

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.

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 or Dialog is resized by the user.

Size on the main axis

The proportion argument to add control how the size in the main axis of the sizer is distributed to its children. For a vertical BoxSizer, 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.

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 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)

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. 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.

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, 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.

Derived from

Object

ClientDataContainer

Methods

Sizer.new

This method is abstract in this class – Wx::Sizer is never instantiated directly. See the specific subclass you are using (eg BoxSizer ) for the parameters require by the constructor.

Sizer#add_item

SizerItem add_item(Object item,
                 Integer index = -1, 
                 Integer proportion = 0, 
                 Integer flag = 0, 
                 Integer border = 0, 
                 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)

Parameters

Flags

See Sizer#add

Sizer#add

SizerItem add(Window window,  
                 Integer proportion = 0, 
                 Integer flag = 0, 
                 Integer border = 0, 
                 Object userData = nil)
SizerItem add(Sizer sizer,  
                Integer proportion = 0, 
                Integer flag = 0, 
                Integer border = 0, 
                Object userData = nil)
SizerItem add(Integer width,  
                Integer height, 
                Integer proportion = 0, 
                Integer flag = 0, 
                Integer border = 0, 
                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, another Sizer, or empty space to be added.

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 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.

Sizer#add_spacer

SizerItem add_spacer(Integer size)

Adds non-stretchable space to the sizer. More readable way of calling Add, size, 0).

Sizer#add_stretch_spacer

SizerItem add_stretch_spacer(Integer prop = 1)

Adds stretchable space to the sizer. More readable way of calling Add, 0, prop).

Sizer#calc_min

Size 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.

Sizer#detach

Boolean detach(Window window)
Boolean detach(Sizer sizer)
Boolean detach(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 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.

See also

Sizer#remove

Sizer#fit

Size fit(Window 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. Returns the new size.

For a top level window this is the total window size, not client size.

Sizer#fit_inside

fit_inside(Window 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.

See also

ScrolledWindow#set_scrollbars, Sizer#set_virtual_size_hints

Sizer#get_children

Array get_children()

Returns an array of SizerItem objects with one corresponding to each Window, Sizer or spacer contained in this sizer.

Sizer#get_item

SizerItem get_item(Window window, 
                     Boolean recursive = false)
SizerItem get_item(Sizer sizer, 
                     Boolean recursive = false)
SizerItem get_item(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.

Sizer#get_size

Size get_size()

Returns the current size of the sizer.

Sizer#get_position

Point get_position()

Returns the current position of the sizer.

Sizer#get_min_size

Size 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, depending on which is bigger.

Sizer#insert

SizerItem insert(Integer index, 
                   Window window, 
                   Integer proportion = 0, 
                   Integer flag = 0, 
                   Integer border = 0, 
                   Object userData = nil)
SizerItem insert(Integer index,  
                   Sizer sizer, 
                   Integer proportion = 0, 
                   Integer flag = 0, 
                   Integer border = 0, 
                   Object userData = nil)
SizerItem insert(Integer index,  
                   Integer width, 
                   Integer height, 
                   Integer proportion = 0, 
                   Integer flag = 0, 
                   Integer border = 0, 
                   Object userData = nil)

Insert a child into the sizer before any existing item at index.

See Sizer#add for the meaning of the other parameters.

Sizer#insert_spacer

SizerItem insert_spacer(Integer index,  Integer size)

Inserts non-stretchable space to the sizer. More readable way of calling Insert, size, 0).

Sizer#insert_stretch_spacer

SizerItem insert_stretch_spacer(Integer index, 
                                  Integer prop = 1)

Inserts stretchable space to the sizer. More readable way of calling Insert, 0, prop).

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.

Sizer#prepend

SizerItem prepend(Window window,  
                    Integer proportion = 0, 
                    Integer flag = 0, 
                    Integer border = 0, 
                    Object userData = nil)
SizerItem prepend(Sizer sizer,
                    Integer proportion = 0, 
                    Integer flag = 0, 
                    Integer border = 0, 
                    Object userData = nil)
SizerItem prepend(Integer width,  
                    Integer height, 
                    Integer proportion = 0, 
                    Integer flag = 0, 
                    Integer border= 0, 
                    Object userData = nil)

Same as 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 and the introduction for a description of the use of the arguments.

Sizer#prepend_spacer

SizerItem prepend_spacer(Integer size)

Prepends non-stretchable space to the sizer. More readable way of calling Prepend, size, 0).

Sizer#prepend_stretch_spacer

SizerItem prepend_stretch_spacer(Integer prop = 1)

Prepends stretchable space to the sizer. More readable way of calling Prepend, 0, prop).

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.

Sizer#remove

Boolean remove(Sizer sizer)
Boolean remove(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 to update the layout “on screen” after removing a child from the sizer.

If you have a variable holding a Window you want to remove from a sizer, use Sizer#detach instead.

Returns true if the child item was found and removed, false otherwise.

Sizer#set_dimension

set_dimension(Integer x,  
              Integer y, 
              Integer width, 
              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 and Prepend methods.

Sizer#set_min_size

set_min_size(Integer width,  Integer height)
set_min_size(Size 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 will return either the minimal size as requested by its children or the minimal size set here, depending on which is bigger.

Sizer#set_item_min_size

set_item_min_size(Window window,  
                  Integer width, 
                  Integer height)
set_item_min_size(Sizer sizer,  
                  Integer width, 
                  Integer height)
set_item_min_size(Integer index, 
                  Integer width, 
                  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.

Sizer#set_size_hints

set_size_hints(Window window)

Tell the sizer to set (and Fit) 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 if the window is resizable (as are many dialogs under Unix and frames on probably all platforms).

Sizer#set_virtual_size_hints

set_virtual_size_hints(Window 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.

See also

ScrolledWindow#set_scrollbars

Sizer#show

Boolean show(Window window,  
             Boolean show = true, 
             Boolean recursive = false)
Boolean show(Sizer sizer,  
             Boolean show = true, 
             Boolean recursive = false)
Boolean show(Integer index,  
             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. 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 and FlexGridSizer, since they are the only two sizer classes that can size rows/columns independently.

[This page automatically generated from the Textile source at Wed Sep 09 02:21:23 +0100 2009]