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 :

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

## 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
- Sizer#add_item
- Sizer#add
- Sizer#add_spacer
- Sizer#add_stretch_spacer
- Sizer#calc_min
- Sizer#detach
- Sizer#fit
- Sizer#fit_inside
- Sizer#get_children
- Sizer#get_item
- Sizer#get_size
- Sizer#get_position
- Sizer#get_min_size
- Sizer#insert
- Sizer#insert_spacer
- Sizer#insert_stretch_spacer
- Sizer#layout
- Sizer#prepend
- Sizer#prepend_spacer
- Sizer#prepend_stretch_spacer
- Sizer#recalc_sizes
- Sizer#remove
- Sizer#set_dimension
- Sizer#set_min_size
- Sizer#set_item_min_size
- Sizer#set_size_hints
- Sizer#set_virtual_size_hints
- Sizer#show

### 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(%(arg-type)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

- 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

#### Flags

See Sizer#add

### Sizer#add

SizerItem add(%(arg-type)Window% window, Integer proportion = 0, Integer flag = 0, Integer border = 0, Object userData = nil) SizerItem add(%(arg-type)Sizer% sizer, Integer proportion = 0, Integer flag = 0, Integer border = 0, Object userData = nil) SizerItem add(%(arg-type)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.

- 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

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

### 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(%(arg-type)Integer% index, Window window, Integer proportion = 0, Integer flag = 0, Integer border = 0, Object userData = nil) SizerItem insert(%(arg-type)Integer% index, Sizer sizer, Integer proportion = 0, Integer flag = 0, Integer border = 0, Object userData = nil) SizerItem insert(%(arg-type)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.

- index The position this child should assume in the sizer.

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

### Sizer#insert_spacer

SizerItem insert_spacer(%(arg-type)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(%(arg-type)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(%(arg-type)Window% window, Integer proportion = 0, Integer flag = 0, Integer border = 0, Object userData = nil) SizerItem prepend(%(arg-type)Sizer% sizer, Integer proportion = 0, Integer flag = 0, Integer border = 0, Object userData = nil) SizerItem prepend(%(arg-type)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(%(arg-type)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(%(arg-type)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(%(arg-type)Sizer% 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 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(%(arg-type)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(%(arg-type)Integer% width, Integer height) set_min_size(%(arg-type)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(%(arg-type)Window% window, Integer width, Integer height) set_item_min_size(%(arg-type)Sizer% sizer, Integer width, Integer height) set_item_min_size(%(arg-type)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(%(arg-type)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(%(arg-type)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(%(arg-type)Window% window, Boolean show = true, Boolean recursive = false) Boolean show(%(arg-type)Sizer% sizer, Boolean show = true, Boolean recursive = false) Boolean show(%(arg-type)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
layoutlayout. 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 2023-06-09 00:45:27 +0000]