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 :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.
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.
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.
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.
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.
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.
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)
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.
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.
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.
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)
See 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.
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.
SizerItem add_spacer(Integer size)Adds non-stretchable space to the sizer. More readable way of calling Add, size, 0).
SizerItem add_stretch_spacer(Integer prop = 1)Adds stretchable space to the sizer. More readable way of calling Add, 0, prop).
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.
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.
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.
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.
ScrolledWindow#set_scrollbars, Sizer#set_virtual_size_hints
Array get_children()Returns an array of SizerItem objects with one corresponding to each Window, Sizer or spacer contained in this sizer.
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.
Size get_size()Returns the current size of the sizer.
Point get_position()Returns the current position of the sizer.
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.
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.
SizerItem insert_spacer(Integer index, Integer size)Inserts non-stretchable space to the sizer. More readable way of calling Insert, size, 0).
SizerItem insert_stretch_spacer(Integer index,
Integer prop = 1)Inserts stretchable space to the sizer. More readable way of calling Insert, 0, prop).
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.
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.
SizerItem prepend_spacer(Integer size)Prepends non-stretchable space to the sizer. More readable way of calling Prepend, size, 0).
SizerItem prepend_stretch_spacer(Integer prop = 1)Prepends stretchable space to the sizer. More readable way of calling Prepend, 0, prop).
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.
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.
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.
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.
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.
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).
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.
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]