wx.Sizer

Package wx :: Class Sizer

Type Sizer

object --+    
         |    
    Object --+
             |
            Sizer

Known Subclasses:: BoxSizer, GridSizer, PySizer

wx.Sizer is the abstract base class used for laying out subwindows in a window. You cannot use wx.Sizer directly; instead, you will have to use one of the sizer classes derived from it such as wx.BoxSizer, wx.StaticBoxSizer, wx.GridSizer, wx.FlexGridSizer and wx.GridBagSizer.

The concept implemented by sizers in wxWidgets is closely related to layout tools 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, rather the dialog will 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 or contorls, empty space or other sizers, so that a hierarchy of sizers can be constructed. Note that wxSizer does not derive from wxWindow and thus do not interfere with tab ordering and requires very little resources compared to a real window on screen.

What makes sizers so well fitted for use in wxWidgets 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 Mac widgets requires more space than on Windows, then the initial size of a dialog using a sizer will automatically be bigger on Mac than on Windows.

Sizers may also be used to control the layout of custom drawn items on the window. The Add, Insert, and Prepend functions return a pointer to the newly added wx.SizerItem. Just add empty space of the desired size and attributes, and then use the wx.SizerItem.GetRect method to determine where the drawing operations should take place.

Note:

If you wish to create a custom sizer class in wxPython you should derive the class from wx.PySizer in order to get Python-aware capabilities for the various virtual methods.

See Also:

wx.SizerItem

To Do:

More dscriptive text here along with some pictures...

Method Summary
	`__init__(self)`
	`__del__(self)`
wx.SizerItem	`Add(self, item, proportion, flag, border, userData)` Appends a child item to the sizer.
	`AddF(args, *kwargs)` AddF(self, item, wx.SizerFlags flags) -> wx.SizerItem
	`AddItem(self, item)` Adds a `wx.SizerItem` to the sizer.
	`AddMany(self, items)` AddMany is a convenience method for adding several items to a sizer at one time.
	`AddSizer(self, args, *kw)` Compatibility alias for `Add`.
	`AddSpacer(self, args, *kw)` AddSpacer(int size) --> SizerItem
	`AddStretchSpacer(self, prop)` AddStretchSpacer(int prop=1) --> SizerItem
	`AddWindow(self, args, *kw)` Compatibility alias for `Add`.
Size	`CalcMin(self)` This method is where the sizer will do the actual calculation of its children's minimal sizes.
	`Clear(self, deleteWindows)` Clear all items from the sizer, optionally destroying the window items as well.
	`DeleteWindows(self)` Destroy all windows managed by the sizer.
bool	`Detach(self, item)` Detaches an item from the sizer without destroying it.
Size	`Fit(self, window)` Tell the sizer to resize the window to match the sizer's minimal size.
	`FitInside(self, window)` Tell the sizer to resize the virtual size of the window to match the sizer's minimal size.
list	`GetChildren(self)` Returns a list of all the `wx.SizerItem` objects managed by the sizer.
Window	`GetContainingWindow(self)` Get the window this sizer is used in.
wx.SizerItem	`GetItem(self, item, recursive)` Returns the `wx.SizerItem` which holds the item given.
Size	`GetMinSize(self)` Returns the minimal size of the sizer.
	`GetMinSizeTuple(self)`
Point	`GetPosition(self)` Returns the current position of the sizer's managed space.
	`GetPositionTuple(self)`
Size	`GetSize(self)` Returns the current size of the space managed by the sizer.
	`GetSizeTuple(self)`
	`Hide(self, item, recursive)` A convenience method for `Show` (item, False, recursive).
wx.SizerItem	`Insert(self, before, item, proportion, flag, border, userData)` Inserts a new item into the list of items managed by this sizer before the item at index before.
	`InsertF(args, *kwargs)` InsertF(self, int before, item, wx.SizerFlags flags) -> wx.SizerItem
	`InsertItem(self, index, item)` Inserts a `wx.SizerItem` to the sizer at the position given by index.
	`InsertSizer(self, args, *kw)` Compatibility alias for `Insert`.
	`InsertSpacer(self, index, args, *kw)` InsertSpacer(int index, int size) --> SizerItem
	`InsertStretchSpacer(self, index, prop)` InsertStretchSpacer(int index, int prop=1) --> SizerItem
	`InsertWindow(self, args, *kw)` Compatibility alias for `Insert`.
	`IsShown(self, item)` Determines if the item is currently shown.
	`Layout(self)` This method will force the recalculation and layout of the items controlled by the sizer using the current space allocated to the sizer.
wx.SizerItem	`Prepend(self, item, proportion, flag, border, userData)` Adds a new item to the begining of the list of sizer items managed by this sizer.
	`PrependF(args, *kwargs)` PrependF(self, item, wx.SizerFlags flags) -> wx.SizerItem
	`PrependItem(self, item)` Prepends a `wx.SizerItem` to the sizer.
	`PrependSizer(self, args, *kw)` Compatibility alias for `Prepend`.
	`PrependSpacer(self, args, *kw)` PrependSpacer(int size) --> SizerItem
	`PrependStretchSpacer(self, prop)` PrependStretchSpacer(int prop=1) --> SizerItem
	`PrependWindow(self, args, *kw)` Compatibility alias for `Prepend`.
	`RecalcSizes(self)` Using the sizes calculated by `CalcMin` reposition and resize all the items managed by this sizer.
bool	`Remove(self, item)` Removes an item from the sizer and destroys it.
	`RemovePos(self, args, *kw)` Compatibility alias for `Remove`.
	`RemoveSizer(self, args, *kw)` Compatibility alias for `Remove`.
	`RemoveWindow(self, args, *kw)` Compatibility alias for `Remove`.
	`Replace(self, olditem, item, recursive)` Detaches the given `olditem` from the sizer and replaces it with `item` which can be a window, sizer, or `wx.SizerItem`.
	`SetContainingWindow(self, window)` Set (or unset) the window this sizer is used in.
	`SetDimension(self, x, y, width, 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`, `Insert` or `Prepend` methods.
	`SetItemMinSize(self, item, size)` Sets the minimum size that will be allocated for an item in the sizer.
	`SetMinSize(self, size)` Call this to give the sizer a minimal size.
	`SetSizeHints(self, window)` Tell the sizer to set (and `Fit`) the minimal size of the window to match the sizer's minimal size.
	`SetVirtualSizeHints(self, window)` Tell the sizer to set the minimal size of the window virtual area to match the sizer's minimal size.
bool	`Show(self, item, show, recursive)` Shows or hides an item managed by the sizer.
	`ShowItems(self, show)` Recursively call `wx.SizerItem.Show` on all sizer items.

Property Summary
	`Children`: See `GetChildren`
	`ContainingWindow`: See `GetContainingWindow` and `SetContainingWindow`
	`MinSize`: See `GetMinSize` and `SetMinSize`
	`Position`: See `GetPosition`
	`Size`: See `GetSize`
	`thisown`: The membership flag

Method Details

Add(self, item, proportion=0, flag=0, border=0, userData=None)

Appends a child item to the sizer.

Parameters:

item - The item can be one of three kinds of objects:

window: A wx.Window to be managed by the sizer. Its minimal size (either set explicitly by the user or calculated internally when constructed with wx.DefaultSize) is interpreted as the minimal size to use when laying out item in the sizer. This is particularly useful in connection with wx.Window.SetSizeHints.
sizer: The (child-)sizer to be added to the sizer. This allows placing a child sizer in a sizer and thus to create hierarchies of sizers (for example a vertical box as the top sizer and several horizontal boxes on the level beneath).
size: A wx.Size or a 2-element sequence of integers that represents the width and height of a spacer to be added to the sizer. 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 value 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.

proportion - Although the meaning of this parameter is undefined in wx.Sizer, it is used in wx.BoxSizer to indicate if a child of a sizer can change its size in the main orientation of the wx.BoxSizer - where 0 stands for not changeable and a value of more than zero is interpreted relative (a proportion of the total) to the value of other children of the same wx.BoxSizer. For example, you might have a horizontal wx.BoxSizer with three children, two of which are supposed to change their size with the sizer. Then the two stretchable windows should each be given proportion value of 1 to make them grow and shrink equally with the sizer's horizontal dimension. But if one of them had a proportion value of 2 then it would get a double share of the space available after the fixed size items are positioned.
(type=int)

flag - This parameter can be used to set a number of flags which can be combined using the binary OR operator |. Two main behaviours are defined using these flags. One is the border around a window: the border parameter determines the border width whereas the flags given here determine which side(s) of the item that the border will be added. The other flags determine how the sizer item behaves when the space allotted to the sizer changes, and is somewhat dependent on the specific kind of sizer used.

wx.TOP wx.BOTTOM wx.LEFT wx.RIGHT wx.ALL	These flags are used to specify which side(s) of the sizer item that the border width will apply to.
wx.EXPAND	The item will be expanded to fill the space allotted to the item.
wx.SHAPED	The item will be expanded as much as possible while also maintaining its aspect ratio
wx.FIXED_MINSIZE	Normally wx.Sizers will use `wx.Window.GetMinSize` or `wx.Window.GetBestSize` 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 it's best size becomes different. If you would rather have a window item stay the size it started 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 wx.ALIGN flags allow you to specify the alignment of the item within the space allotted to it by the sizer, ajusted for the border if any.

(type=int)

border - Determines the border width, if the flag parameter is set to include any border flag.
(type=int)

userData - Allows an extra object to be attached to the sizer item, for use in derived classes when sizing information is more complex than the proportion and flag will allow for.
(type=PyObject)

Returns:: wx.SizerItem

AddF(*args, **kwargs)

AddF(self, item, wx.SizerFlags flags) -> wx.SizerItem

Similar to Add but uses the wx.SizerFlags convenience class for setting the various flags, options and borders.

AddItem(self, item)

Adds a wx.SizerItem to the sizer.

Parameters:: item
(type=SizerItem)

AddMany(self, items)

AddMany is a convenience method for adding several items to a sizer at one time. Simply pass it a list of tuples, where each tuple consists of the parameters that you would normally pass to the Add method.

AddSizer(self, *args, **kw)

Compatibility alias for Add.

AddSpacer(self, *args, **kw)

AddSpacer(int size) --> SizerItem

Add a spacer that is (size,size) pixels.

AddStretchSpacer(self, prop=1)

AddStretchSpacer(int prop=1) --> SizerItem

Add a stretchable spacer.

AddWindow(self, *args, **kw)

Compatibility alias for Add.

CalcMin(self)

This method is where the sizer will do the actual calculation of its children's minimal sizes. You should not need to call this directly as it is called by Layout.

Returns:: Size

Clear(self, deleteWindows=False)

Clear all items from the sizer, optionally destroying the window items as well.

Parameters:: deleteWindows
(type=bool)

DeleteWindows(self)

Destroy all windows managed by the sizer.

Detach(self, item)

Detaches an item from the sizer without destroying it. This method does not cause any layout or resizing to take place, call Layout to do so. The item parameter can be either a window, a sizer, or the zero-based index of the item to be detached. Returns True if the child item was found and detached.

Returns:: bool

Fit(self, 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 in order to set its initial size to match the needs of the children as determined by the sizer. Returns the new size.

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

Parameters:: window
(type=Window)

Returns:: Size

FitInside(self, 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.

Parameters:: window
(type=Window)

GetChildren(self)

Returns a list of all the wx.SizerItem objects managed by the sizer.

Returns:: list

GetContainingWindow(self)

Get the window this sizer is used in.

Returns:: Window

GetItem(self, item, recursive=False)

Returns the wx.SizerItem which holds the item given. The item parameter can be either a window, a sizer, or the zero-based index of the item to be found.

Returns:: wx.SizerItem

GetMinSize(self)

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

Returns:: Size

GetPosition(self)

Returns the current position of the sizer's managed space.

Returns:: Point

GetSize(self)

Returns the current size of the space managed by the sizer.

Returns:: Size

Hide(self, item, recursive=False)

A convenience method for Show (item, False, recursive).

Insert(self, before, item, proportion=0, flag=0, border=0, userData=None)

Inserts a new item into the list of items managed by this sizer before the item at index before. See Add for a description of the parameters.

Parameters:: before
(type=int); proportion
(type=int); flag
(type=int); border
(type=int); userData
(type=PyObject)

Returns:: wx.SizerItem

InsertF(*args, **kwargs)

InsertF(self, int before, item, wx.SizerFlags flags) -> wx.SizerItem

Similar to Insert, but uses the wx.SizerFlags convenience class for setting the various flags, options and borders.

InsertItem(self, index, item)

Inserts a wx.SizerItem to the sizer at the position given by index.

Parameters:: index
(type=int); item
(type=SizerItem)

InsertSizer(self, *args, **kw)

Compatibility alias for Insert.

InsertSpacer(self, index, *args, **kw)

InsertSpacer(int index, int size) --> SizerItem

Insert a spacer at position index that is (size, size) pixels.

InsertStretchSpacer(self, index, prop=1)

InsertStretchSpacer(int index, int prop=1) --> SizerItem

Insert a stretchable spacer.

InsertWindow(self, *args, **kw)

Compatibility alias for Insert.

IsShown(self, item)

Determines if the item is currently shown. To make a sizer item disappear or reappear, use Show followed by Layout. The item parameter can be either a window, a sizer, or the zero-based index of the item.

Layout(self)

This method will force the recalculation and layout of the items controlled by the sizer using the current space allocated to the sizer. Normally this is called automatically from the owning window's EVT_SIZE handler, but it is also useful to call it from user code when one of the items in a sizer change size, or items are added or removed.

Prepend(self, item, proportion=0, flag=0, border=0, userData=None)

Adds a new item to the begining of the list of sizer items managed by this sizer. See Add for a description of the parameters.

Parameters:: proportion
(type=int); flag
(type=int); border
(type=int); userData
(type=PyObject)

Returns:: wx.SizerItem

PrependF(*args, **kwargs)

PrependF(self, item, wx.SizerFlags flags) -> wx.SizerItem

Similar to Prepend but uses the wx.SizerFlags convenience class for setting the various flags, options and borders.

PrependItem(self, item)

Prepends a wx.SizerItem to the sizer.

Parameters:: item
(type=SizerItem)

PrependSizer(self, *args, **kw)

Compatibility alias for Prepend.

PrependSpacer(self, *args, **kw)

PrependSpacer(int size) --> SizerItem

Prepend a spacer that is (size, size) pixels.

PrependStretchSpacer(self, prop=1)

PrependStretchSpacer(int prop=1) --> SizerItem

Prepend a stretchable spacer.

PrependWindow(self, *args, **kw)

Compatibility alias for Prepend.

RecalcSizes(self)

Using the sizes calculated by CalcMin reposition and resize all the items managed by this sizer. You should not need to call this directly as it is called by Layout.

Remove(self, item)

Removes an item from the sizer and destroys it. This method does not cause any layout or resizing to take place, call Layout to update the layout on screen after removing a child from the sizer. The item parameter can be either a window, a sizer, or the zero-based index of an item to remove. Returns True if the child item was found and removed.

Returns:: bool

Note:

For historical reasons calling this method with a wx.Window parameter is depreacted, as it will not be able to destroy the window since it is owned by its parent. You should use Detach instead.

RemovePos(self, *args, **kw)

Compatibility alias for Remove.

RemoveSizer(self, *args, **kw)

Compatibility alias for Remove.

RemoveWindow(self, *args, **kw)

Compatibility alias for Remove.

Replace(self, olditem, item, recursive=False)

Detaches the given olditem from the sizer and replaces it with item which can be a window, sizer, or wx.SizerItem. The detached child is destroyed only if it is not a window, (because windows are owned by their parent, not the sizer.) The recursive parameter can be used to search for the given element recursivly in subsizers.

This method does not cause any layout or resizing to take place, call Layout to do so.

Returns True if the child item was found and removed.

SetContainingWindow(self, window)

Set (or unset) the window this sizer is used in.

Parameters:: window
(type=Window)

SetDimension(self, x, y, width, 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, Insert or Prepend methods.

Parameters:: x
(type=int); y
(type=int); width
(type=int); height
(type=int)

SetItemMinSize(self, item, size)

Sets the minimum size that will be allocated for an item in the sizer. The item parameter can be either a window, a sizer, or the zero-based index of the item. If a window or sizer is given then it will be searched for recursivly in subsizers if neccessary.

Parameters:: size
(type=Size)

SetMinSize(self, 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 GetMinSize will return either the minimal size as requested by its children or the minimal size set here, depending on which is bigger.

Parameters:: size
(type=Size)

SetSizeHints(self, 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 if the window is resizable (as are many dialogs under Unix and frames on probably all platforms) in order to prevent the window from being sized smaller than the minimal size required by the sizer.

Parameters:: window
(type=Window)

SetVirtualSizeHints(self, 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.

Parameters:: window
(type=Window)

See Also:

wx.ScrolledWindow.SetScrollbars

Show(self, item, show=True, recursive=false)

Shows or hides an item managed by the sizer. To make a sizer item disappear or reappear, use Show followed by Layout. The item parameter can be either a window, a sizer, or the zero-based index of the item. Use the recursive parameter to show or hide an item in a subsizer. Returns True if the item was found.