DSizerMethods

From Dabo Wiki
Jump to: navigation, search

The primary methods used with dSizer are append() and insert(). Their method signatures are the same, with the exception that insert() requires you to pass the position in the sizer where you want the object inserted.

def append(self, item, layout="normal", proportion=0, alignment=None,
        halign="left", valign="top", border=None, borderSides=None,
        borderFlags=None)

def insert(self, index, item, layout="normal", proportion=0, alignment=None,
        halign="left", valign="top", border=None, borderSides=None, 
        borderFlags=None)

Each of the parameters, and how they affect the appearance of the added object in the sizer, is listed below:

Parameter Default Description
index - Only used with insert(). This is the zero-based index of the position in the sizer where the object will be inserted.
item - The object to be added to the sizer. It can be a UI control, another sizer, or an integer. If it is an integer, a spacer of that size will be added to the sizer.
layout "normal" Determines how the object is sized in the "other" (non-Orientation) dimension to fill the space (e.g., in a Vertical sizer, how is the horizontal sizing determined?). "Normal" means that the sizer will inspect the control to determine its required size every time layout() is called. "Fixed" means that the sizer checks the size of the control when it is added to the sizer, and maintains that size even if the control changes. "Expand" means to resize the control to fill the available space. Since "Expand" is a very common choice, it can be abbreviated as "ex", "exp", or simply "x". "Grow" is another synonym that will be interpreted as "Expand".
proportion 0 Determines the relative weighting given to this control when the sizer divides up the space it has to manage along its Orientation dimension. A proportion of zero means to give the control just the space it would naturally take up if it weren't in a sizer. All non-zero proportions are then pooled and the space remaining after the required sizes of all controls is accounted for is then divided up according to each object's proportion.
alignment None Deprecated; for backwards compatibility only. Use halign and valign instead.
halign "left" Controls the horizontal alignment within the space allocated by the sizer. Possible values are "Left", "Right", or "Center"/"Centre". Case-insensitive.
valign "top" Controls the vertical alignment within the space allocated by the sizer. Possible values are "Top", "Middle", or "Bottom". Case-insensitive.
border None Integer value that determines how much extra space is created around the control. Overrides the sizer's Border property.
borderSides "All" A list of the sides on which the border will be created. Overrides the sizers's various Border* properties. If only a single value needs to be passed, you may pass it as a plain string. Allowed values are "Left", "Right", "Top", "Bottom", or "All". Case-insensitive.
borderFlags "All" Deprecated; use borderSides instead.

append1x()

def append1x(self, item, **kwargs)

This is a convenience method that is shorthand for append(item, 1, "expand", **kwargs). Since one of the most common things needed is appending an item to a sizer with a proportion of 1 and a layout of "expand", this method comes in very handy.


prepend()

def prepend(self, *args, **kwargs)

Another convenience method; this one inserts the item at the beginning of the objects already in the sizer. It is equivalent to insert(0, *args, **kwargs).


layout()

def layout(self)

Tells the sizer to re-evaluate its rules, and re-position/ re-size the items it controls. This method is called recursively, so typically you only need to call it for the topmost container that needs updating, and it will call layout() method of all contained items. It is also called automatically when a form is resized.


addSpacer()

appendSpacer()

insertSpacer()

prependSpacer()

def addSpacer(self, val, pos=None, proportion=0)

def appendSpacer(self, val, proportion=0)

def insertSpacer(self, pos, val, proportion=0)

def prependSpacer(self, val, proportion=0)

These are all methods for adding spacers to your sizers. They follow the same naming as the append/insert/prepend methods for adding objects.

Spacers guarantee a minimum of space will be maintained at the position in the sizer where it is inserted. If a non-zero proportion is specified, the space will grow along with the other items in the sizer according to each one's relative proportions, but the spacer will never shrink below the orginal specified size.

Tip: You can use spacers to "float" a control inside its container. See How to Visually Float a Control for an example.


remove()

showItem()

hideItem()

def remove(self, item, destroy=None)

def showItem(self, itm)

def hideItem(self, itm)

remove() removes the item from the control of the sizer. Does not destroy the item, unless the destroy parameter is passed as True. The object that was removed remains where it is, and will no longer have its size and position updated as the form is resized.

showItem() and hideItem() do what you would expect: they affect the visibility of the item in question. But they do more than that: they also affect how the rest of the items in the sizer are layed out, since when an item is hidden, it's treated as if it had been removed from the sizer altogether, and its space is re-apportioned among the visible members.


release()

def release(self, releaseContents=False)

Destroys the sizer. If releaseContents is passed as True, all items controlled by the sizer are also destroyed. Otherwise the items remain where they are, and will no longer have their sizes and positions updated as the form is resized.


getItem()

def getItem(self, szItem)

Since sizers aren't physically present in the UI, but instead are hierarchical sets of rules, asking a sizer for its Children will return SizerItem objects, not the objects being controlled. Passing one of these SizerItem objects to getItem() returns the object controlled by that SizerItem. It can be a UI control, another sizer, or a spacer (which will be returned as a 2-tuple of width,height).