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.
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
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.
Adds non-stretchable space to the sizer. More readable way of calling
Add, size, 0).
Adds stretchable space to the sizer. More readable way of calling
Add, 0, prop).
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.
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.
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.
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
Returns an array of SizerItem objects with one
corresponding to each Window, Sizer or spacer contained in this sizer.
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.
Returns the current size of the sizer.
Returns the current position of the sizer.
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.
Insert a child into the sizer before any existing item at index.
See Sizer#add for the meaning of the other parameters.
Inserts non-stretchable space to the sizer. More readable way of calling
Insert, size, 0).
Inserts stretchable space to the sizer. More readable way of calling
Insert, 0, prop).
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.
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.
Prepends non-stretchable space to the sizer. More readable way of calling
Prepend, size, 0).
Prepends stretchable space to the sizer. More readable way of calling
Prepend, 0, prop).
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.
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.
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.
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 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.
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).
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.
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-03 08:07:31 +0000]