DGridSizerMethods

From Dabo Wiki
Jump to: navigation, search

The primary method used with dGridSizer is append(). You can specify the row/column position where the object is to be inserted; note that if an object already exists in that position, an error will be thrown.

A SizerItem reference to the appended item is returned.

But the more common usage is to set the MaxRows or MaxCols property, and then call append() without specifying row/column position. The sizer will then find the next available cell and place the object there. When the MaxRows / MaxCols property value has been reached, the sizer will start a new column or row.

An example might help. A typical usage of a grid sizer is to lay out a series of textboxes along with an identifying label to its left. This is a two-column layout, with as many rows as there are textboxes. In this case, you'd set MaxCols to 2, and then append the first label. It will be placed in row 0, col 0. Next append the first textbox; it will go into row 0, col 1. Next you would append the second label. Since we've reached the maximum number of columns, a new row will be started, and the label will be placed in row 1, col 0. Next comes its textbox, and that will go into row 1, col 1. When the next label is appended, another row will be started, and so on until the end, where the result will be a nice 2-column grid with labels in the left column, and textboxes in the right.

def append(self, item, layout="normal", row=-1, col=-1, 
        rowSpan=1, colSpan=1, alignment=None, halign="left", 
        valign="middle", border=0, borderSides=("all",), 
        borderFlags=("all",), flag=None):

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

Parameter Default Description
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 when the cell it is in is bigger than the object requires. "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 Has no effect on an item in a grid sizer.
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.



appendItems()

def appendItems(self, items, *args, **kwargs)

This is a convenience method when you want to append a number of items to the grid sizer with the same parameters. Instead of calling append() multiple times, just pass the list of items to be appended (either a list or a tuple is fine), along with whatever parameters are desired, and each one will be appended in the order they exist in the list.

A list of SizerItem objects to the appended items is returned. The SizerItem objects are in the same order as the original object list.


appendSpacer()

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

Appends a spacer into the next available cell. Spacers serve two purposes in dGridSizer: first, they are used to ensure that a cell has a certain minimum size; second, they let you skip a cell when appending a series of items.

Since the space defined by the sizer is two-dimensional, the item passed to this method should be a 2-tuple containing the (width, height) of the desired spacing. If a single integer, such as 10, is passed instead, it is converted to (10, 10) and then appended normally.


findFirstEmptyCell()

def findFirstEmptyCell(self)

This method scans through the grid sizer and will return the coordinates of the first cell in the grid that does not have any object assigned to it. The order in which cells are checked is determined by the MaxDimension property, which is either c (for columns) or r (for rows).

Let's say that MaxDimension is 'c': the method will start at (0, 0) and then proceed along row 0 until either an empty cell is found, or until it has checked MaxCols columns. At that point, it starts checking out the next row, starting with column 0 and again checking sucessive columns until either an empty cell or it reaches MaxCols.


getHighRow()

def getHighRow(self)

Returns the integer representing the highest row number that contains an object.


getHighCol()

def getHighCol(self)

Returns the integer representing the highest column number that contains an object.


getItemByRowCol()

def getItemByRowCol(self, row, col, returnObject=True)

Returns the contents of the cell at the specified location. Normally this returns the object that is managed by the grid sizer at that location, but if you pass returnObject=False, the SizerItemfor that object is returned instead. And, of course, if the cell at that location is empty, it returns None.


getNeighbor()

def getNeighbor(self, obj, dir)

Sometimes it's handy to be able to get a reference to the object in a cell adjacent to another object. This method takes an object reference and a direction, locates the object in the grid sizer, and then returns the content of the cell in whichever direction you requested. If the cell is empty, None is returned. Allowable directions are: Left, Right, Up, or Down. Only the first letter is significant, and case doesn't matter, so you can pass Down, D, d, doofus, etc., and all will be interpreted as meaning Down.


getItemAtOffset()

def getItemAtOffset(self, obj, off)

This is a more general version of getNeighbor(). You pass an object reference and an offset, and it returns the content of the cell at the corresponding offset. If the cell is empty, None is returned.

Offsets are expressed as 2-tuples in the form (horizontal, vertical). A positive value for the horizontal parameter will look to columns to the right of the object, while negative values look to the left. Similarly, negative vertical values will look upwards, and positive values will look lower in the grid sizer.


getGridPos()

def getGridPos(self, obj)

Given an object reference, returns its (row, col) position in the grid sizer. If the object is not managed by this sizer, returns (None, None).


moveCell()

def moveCell(self, fromRow, fromCol, toRow, toCol, delay=False)

Moves the object in cell (fromRow, fromCol) to cell (toRow, toCol). If the destination cell already contains an object, an error will be thrown.

Normally layout() is automatically called, but in the case where you are moving many objects, it's faster to pass delay=True, in which case layout() is not called by the class; you have to call it manually when you are done moving items around.


moveObject()

def moveObject(self, obj, targetRow, targetCol, delay=False)

Just like moveCell(), except that you pass an object instead of a "from" location. The class will figure out the location of the object, and then move it as in moveCell().


getRowExpand()

def getRowExpand(self, row)

Given a row number, returns a boolean indicating whether the row is set to expand or not.


getColExpand()

def getColExpand(self, col)

Given a column number, returns a boolean indicating whether the column is set to expand or not.


setRowExpand()

def setRowExpand(self, expand, rowNum, proportion=0)

Turns expansion on/off for the specified row, depending on whether True or False is passed for the expand parameter.

rowNum is either an integer representing the row number to be changed, or the string "all", which will then apply the setting to all rows containing objects.

The proportion parameter works similar to the way proportion does in dSizer, except that if all rows are set to 0 proportion, they are all sized equally instead of not sized at all.


setColExpand()

def setColExpand(self, expand, colNum, proportion=0)

Turns expansion on/off for the specified column, depending on whether True or False is passed for the expand parameter.

colNum is either an integer representing the column number to be changed, or the string "all", which will then apply the setting to all columns containing objects.

The proportion parameter works similar to the way proportion does in dSizer, except that if all columns are set to 0 proportion, they are all sized equally instead of not sized at all.


setFullExpand()

def setFullExpand(self)

Convenience method for setting all columns and rows of the sizer to be growable. Must be called after all items are added, as any rows or columns added after the call will have their expand setting at its default of False.


setFullCollapse()

def setFullCollapse(self)

Convenience method for setting all columns and rows of the sizer to not be growable.


getGridSpan()

def getGridSpan(self, obj)

Given an object, returns that object's cell span in a (row, col) 2-tuple. If the object is not managed by this sizer, returns (None, None).


setGridSpan()

def setGridSpan(self, obj, row=None, col=None)

Given an object that is managed by this grid sizer, sets its span to the given values. Returns True if successful, or False if it fails, due to another item in the way.


setRowSpan()

def setRowSpan(self, obj, rowspan)

Sets the row span of the specified object, keeping the column span the same. Returns True if successful, or False if it fails, due to another item in the way.


setColSpan()

def setColSpan(self, obj, colspan)

Sets the column span of the specified object, keeping the row span the same. Returns True if successful, or False if it fails, due to another item in the way.


removeRow()

def removeRow(self, rowNum)

Deletes any items contained in the specified row, and then moves all items below it up to fill the space.


removeCol()

def removeCol(self, colNum)

Deletes any items contained in the specified column, and then moves all items to the right of it up to fill the space.


copyGrid()

def copyGrid(self, oldGrid)

This method takes an existing grid sizer, and moves the contents to the current grid. The properties of each cell's item are preserved, but row/column Expand settings must be handled separately.


isRowGrowable()

def isRowGrowable(self, row)

Deprecated. Use getRowExpand() instead.


isColGrowable()

def isColGrowable(self, col)

Deprecated. Use getColExpand() instead.