 |
Major Classes ReferenceInterface documentation of the major classes |
Home
What’s New?
Features
Getting Started
Cookbook
FAQ
Class Docs
Discussion
Download
Version 1.2 (2008/09/06)
Quick search
|
Major Classes ReferenceInterface documentation of the major classes |
Version 1.2 (2008/09/06)
An object list displays various aspects of a list of objects in a multi-column list control.
To use an ObjectListView, the programmer defines what columns are in the control and which bits of information each column should display. The programmer then calls SetObjects with the list of objects that the ObjectListView should display. The ObjectListView then builds the control.
Columns hold much of the intelligence of this control. Columns define both the format (width, alignment), the aspect to be shown in the column, and the columns behaviour. See ColumnDefn for full details.
These are public instance variables. (All other variables should be considered private.)
This control whether and how the cells of the control are editable. It can be set to one of the following values:
Cell editing is not allowed on the control This is the default.
Single clicking on any subitem cell begins an edit operation on that cell. Single clicking on the primaru cell does not start an edit operation. It simply selects the row. Pressing F2 edits the primary cell.
Double clicking any cell starts an edit operation on that cell, including the primary cell. Pressing F2 edits the primary cell.
Pressing F2 edits the primary cell. Tab/Shift-Tab can be used to edit other cells. Clicking does not start any editing.
When useAlternateBackColors is true, even numbered rows will have this background color.
When this is True (the default), several standard keys will be handled as commands by the ObjectListView. If this is False, they will be ignored.
Select all model objects
Put a text version of the selected rows onto the clipboard (on Windows, this is will also put a HTML version into the clipboard)
[GroupListView only] This will collapse/expand all selected groups.
When useAlternateBackColors is true, odd numbered rows will have this background color.
To further control the formatting of individual rows, this property can be set to a callable that expects two parameters: the listitem whose characteristics are to be set, and the model object being displayed on that row.
The row formatter is called after the alternate back colours (if any) have been set.
Remember: the background and text colours are overridden by system defaults while a row is selected.
If this boolean is True (the default), when the user types into the list, the control will try to find a prefix match on the values in the sort column. If this is False, or the list is unsorted or if the sorted column is marked as not searchable (via isSearchable attribute), the primary column will be matched.
If this property is true, even and odd rows will be given different background. The background colors are controlled by the properties evenRowsBackColor and oddRowsBackColor. This is true by default.
Create an ObjectListView.
Apart from the normal ListCtrl parameters, this constructor looks for any of the following optional parameters:
- cellEditMode
- rowFormatter
- sortable
- useAlternateBackColors
The behaviour of these properties are described in the class documentation, except for sortable.
sortable controls whether the rows of the control will be sorted when the user clicks on the header. This is true by default. If it is False, clicking the header will be nothing, and no images will be registered in the image lists. This parameter only has effect at creation time – it has no impact after creation.
Append the given ColumnDefn object to our list of active columns.
If this method is called directly, you must also call RepopulateList() to populate the new column with data.
Add the given images to the list of available images. Return the index of the image.
If a name is given, that name can later be used to refer to the images rather than having to use the returned index.
Add the given object to our collection of objects.
The object will appear at its sorted location, or at the end of the list if the list is unsorted
Add the given collections of objects to our collection of objects.
The objects will appear at their sorted locations, or at the end of the list if the list is unsorted
Put a textual representation of the given objects onto the clipboard.
This will be one line per object and tab-separated values per line. Under windows there will be a HTML table version put on the clipboard as well.
Create a fixed width column at the given index to show the checkedness of objects in this list.
If this is installed at column 0 (which is the default), the listview should only be used in Report view.
This should be called after SetColumns() has been called, since SetColumns() removed any previous check state column.
RepopulateList() or SetObjects() must be called after this.
Make sure the user can see all of the given cell, scrolling if necessary. Return the bounds to the cell calculated after the cell has been made visible. Return None if the cell cannot be made visible (non-Windows platforms can’t scroll the listview horizontally)
If the cell is bigger than the ListView, the top left of the cell will be visible.
Return the check state of the given model object.
Returns a boolean or None (which means undetermined)
Return the model objects that are actually displayed in the control.
If no filter is in effect, this is the same as GetObjects().
Return the index of the given modelObject in the list.
This method works on the visible item in the control. If a filter is in place, not all model object given to SetObjects() are visible.
Return the model objects that are available to the control.
If no filter is in effect, this is the same as GetFilteredObjects().
Return the primary column or None there is no primary column.
The primary column is the first column given by the user. This column is edited when F2 is pressed.
Return the index of the primary column. Returns -1 when there is no primary column.
The primary column is the first column given by the user. This column is edited when F2 is pressed.
Poor mans replacement for missing wxWindows method.
The rect returned takes scroll position into account, so negative x and y are possible.
Return a tuple indicating which (item, subItem) the given pt (client coordinates) is over.
This uses the buildin version on Windows, and poor mans replacement on other platforms.
Configure the given column so that it shows the check state of each row in this control.
This column’s checkbox will be toggled when the user pressed space when a row is selected.
RepopulateList() or SetObjects() must be called after a new check state column is installed for the check state column to be visible.
Set to None to remove the check state column.
Register the bitmaps that should be used to indicated which column is being sorted These bitmaps must be the same dimensions as the small image list (not sure why that should be so, but it is)
If no parameters are given, 16x16 default images will be registered
Set the check state of the given model object.
‘state’ can be True, False or None (which means undetermined)
Set the list of columns that will be displayed.
The elements of the list can be either ColumnDefn objects or a tuple holding the values to be given to the ColumnDefn constructor.
The first column is the primary column – this will be shown in the the non-report views.
This clears any preexisting CheckStateColumn. The first column that is a check state column will be installed as the CheckStateColumn for this listview.
Remember the filter that is currently operating on this control. Set this to None to clear the current filter.
A filter is a callable that accepts one parameter: the original list of model objects. The filter chooses which of these model objects should be visible to the user, and returns a collection of only those objects.
The Filter module has some useful standard filters.
You must call RepopulateList() for changes to the filter to be visible.
Remember the image lists to be used for this control.
Call this without parameters to create reasonable default image lists.
Use this to change the size of images shown by the list control.
Set the column by which the rows should be sorted.
‘column’ can be None (which makes the list be unsorted), a ColumnDefn, or the index of the column desired
Sort the existing list items using the given comparison function.
The comparison function must accept two model objects as parameters.
The primary users of this method are handlers of the SORT event that want to sort the items by their own special function.
Toggle the “checkedness” of the given model.
Checked becomes unchecked; unchecked or undetermined becomes checked.
A ColumnDefn controls how one column of information is sourced and formatted.
Much of the intelligence and ease of use of an ObjectListView comes from the column definitions. It is worthwhile gaining an understanding of the capabilities of this class.
Public Attributes (alphabetically):
How will the title and the cells of the this column be aligned. Possible values: ‘left’, ‘centre’, ‘right’
This is a callable that will be invoked to create an editor for value in this column. The callable should accept three parameters: the objectListView starting the edit, the rowIndex and the subItemIndex. It should create and return a Control that is capable of editing the value.
If this is None, a cell editor will be chosen based on the type of objects in this column (See CellEditor.EditorRegistry).
If the column is space filling, this attribute controls what proportion of the space should be given to this column. By default, all spacing filling column share the free space equally. By changing this attribute, a column can be given a larger proportion of the space.
The groupKeyConverter converts a group key into the string that can be presented to the user. This string will be used as part of the title for the group.
Its behaviour is the same as “stringConverter.”
When this column is used to group the model objects, what groupKeyGetter extracts the value from each model that will be used to partition the model objects into groups.
Its behaviour is the same as “valueGetter.”
If this is None, the value returned by valueGetter will be used.
When a group is created that contains a single item, and the GroupListView has “showItemCounts” turned on, this string will be used to create the title of the group. The string should contain two placeholder: %(title)s and %(count)d. Example: “%(title)s [only %(count)d song]”
When a group is created that contains 0 items or >1 items, and the GroupListView has “showItemCounts” turned on, this string will be used to create the title of the group. The string should contain two placeholder: %(title)s and %(count)d. Example: “%(title)s [%(count)d songs]”
The index or name of the image that will be shown against the column header. Remember, a column header can only show one image at a time, so if the column is the sort column, it will show the sort indicator – not this headerImage.
A string, callable or integer that is used to get a index of the image to be shown in a cell.
Strings and callable are used as for the valueGetter attribute.
Integers are treated as constants (that is, all rows will have the same image).
Can the user edit cell values in this column? Default is True
If this column is the sort column, when the user types into the ObjectListView, will a match be looked for using values from this column? If this is False, values from column 0 will be used. Default is True.
Is this column a space filler? Space filling columns resize to occupy free space within the listview. As the listview is expanded, space filling columns expand as well. Conversely, as the control shrinks these columns shrink too.
Space filling columns can disappear (i.e. have a width of 0) if the control becomes too small. You can set minimumWidth to prevent them from disappearing.
An integer indicate the number of pixels above which this column will not resize. Default is -1, which means there is no limit.
An integer indicate the number of pixels below which this column will not resize. Default is -1, which means there is no limit.
If isSearchable and useBinarySearch are both True, the ObjectListView will use a binary search algorithm to locate a match. If useBinarySearch is False, a simple linear search will be done.
The binary search can quickly search large numbers of rows (10,000,000 in about 25 comparisons), which makes them ideal for virtual lists. However, there are two constraints:
- the ObjectListView must be sorted by this column
- sorting by string representation must give the same ordering as sorting by the aspect itself.
The second constraint is necessary because the user types characters expecting them to match the string representation of the data. The binary search will make its decisions using the string representation, but the rows ordered by aspect value. This will only work if sorting by string representation would give the same ordering as sorting by the aspect value.
In general, binary searches work with strings, YYYY-MM-DD dates, and booleans. They do not work with numerics or other date formats.
If either of these constrains are not true, you must set useBinarySearch to False and be content with linear searches. Otherwise, the searching will not work correctly.
A string or a callable that will used to convert a cells value into a presentation string.
If it is a callble, it will be called with the value for the cell and must return a string.
If it is a string, it will be used as a format string with the % operator, e.g. “self.stringConverter % value.” For dates and times, the stringConverter will be passed as the first parameter to the strftime() method on the date/time.
A string that will be used as the title of the column in the listview
A string, callable or integer that is used to get the value to be displayed in a cell. See _Munge() for details on how this attribute is used.
A callable is simply called and the result is the value for the cell.
The string can be the name of a method to be invoked, the name of an attribute to be fetched, or (for dictionary like objects) an index into the dictionary.
An integer can only be used for list-like objects and is used as an index into the list.
A string, callable or integer that is used to write an edited value back into the model object.
A callable is called with the model object and the new value. Example:
myCol.valueSetter(modelObject, newValue)
An integer can only be used if the model object is a mutable sequence. The integer is used as an index into the list. Example:
modelObject[myCol.valueSetter] = newValue
The string can be:
the name of a method to be invoked, in which case the method should accept the new value as its parameter. Example:
method = getattr(modelObject, myCol.valueSetter)
method(newValue)
the name of an attribute to be updated. This attribute will not be created: it must already exist. Example:
setattr(modelObject, myCol.valueSetter, newValue)
for dictionary like model objects, an index into the dictionary. Example:
modelObject[myCol.valueSetter] = newValue
When this is true and the group key for a row is a string, only the first letter of the string will be considered as the group key. This is often useful for grouping row when the column contains a name.
How many pixels wide will the column be? -1 means auto size to contents. For a list with thousands of items, autosize can be noticably slower than specifically setting the size.
The title, align and width attributes are only references when the column definition is given to the ObjectListView via the SetColumns() or AddColumnDefn() methods. The other attributes are referenced intermittently – changing them will change the behaviour of the ObjectListView.
Without a string converter, None will be converted to an empty string. Install a string converter (‘%s’ will suffice) if you want to see the ‘None’ instead.
BUG: Double-clicking on a divider (under Windows) can resize a column beyond its minimum and maximum widths.
Create a new ColumnDefn using the given attributes.
The attributes behave as described in the class documentation, except for:
An integer which indicates that this column has the given width and is not resizable. Useful for column that always display fixed with data (e.g. a single icon). Setting this parameter overrides the width, minimumWidth and maximumWidth parameters.
If this is True, the column will use an autocomplete TextCtrl when values of this column are edited. This overrules the cellEditorCreator parameter.
If this is True, the column will use an autocomplete ComboBox when values of this column are edited. This overrules the cellEditorCreator parameter.
An ObjectListView that allows model objects to be organised into collapsable groups.
GroupListView only work in report view.
The appearance of the group headers are controlled by the ‘groupFont’, ‘groupTextColour’, and ‘groupBackgroundColour’ public variables.
The images used for expanded and collapsed groups can be controlled by changing the images name ‘ObjectListView.NAME_EXPANDED_IMAGE’ and ‘ObjectListView.NAME_COLLAPSED_IMAGE’ respectfully. Like this:
self.AddNamedImages(ObjectListView.NAME_EXPANDED_IMAGE, myOtherImage1)
self.AddNamedImages(ObjectListView.NAME_COLLAPSED_IMAGE, myOtherImage2)
Public variables:
When this is True (the default), the list will be built so there is a blank line between groups.
Create a GroupListView.
Parameters:
showItemCounts
If this is True (the default) Group title will include the count of the items that are within that group.
useExpansionColumn
If this is True (the default), the expansion/contraction icon will have its own column at position 0. If this is false, the expand/contract icon will be in the first user specified column. This must be set before SetColumns() is called. If it is changed, SetColumns() must be called again.
Return the model object at the given row of the list.
With GroupListView, this method can return None, since the given index may be a blank row or a group header. These do not have corresponding model objects.
Completely rebuild our groups from our current list of model objects.
Only use this if SetObjects() has been called. If you have specifically created your groups and called SetGroups(), do not use this method.
Selected all model objects in the control.
In a GroupListView, this does not select blank lines or groups
Set the column by which the rows should be always be grouped.
‘column’ can be None (which clears the setting), a ColumnDefn, or the index of the column desired
Present the collection of ListGroups in this control.
Calling this automatically put the control into ShowGroup mode
Sort the given collection of groups in the given direction (defaults to ascending).
The model objects within each group will be sorted as well
Progressively yield the selected modelObjects.
Only return model objects, not blank lines or ListGroups
This class is an Adapter around an ObjectListView which ensure that the list is updated, at most, once every N seconds.
Usage:
self.olv2 = BatchedUpdate(self.olv, 3)
# Now use olv2 in place of olv, and the list will only be updated at most once
# every 3 second, no many how many calls are made to it.
This is useful for a certain class of problem where model objects are update frequently – more frequently than you wish to update the control. A backup program may be able to backup several files a second, but does not wish to update the list ctrl that often. A packet sniffer will receive hundreds of packets per second, but should not try to update the list ctrl for each packet. A batched update adapter solves situations like these in a trivial manner.
All other message are passed directly to the ObjectListView and are thus unbatched. This means that sorting and changes to columns are unbatched and will take effect immediately.
You need to be a little careful when using batched updates. There are at least two things you need to avoid, or at least be careful about:
Don’t mix batched and unbatched updates. If you go behind the back of the batched update wrapper and make direct changes to the underlying control, you will probably get bitten by difficult-to-reproduce bugs. For example:
self.olvBatched.SetObjects(objects) # Batched update
self.olvBatched.objectlistView.AddObject(aModel) # unbatched update
This will almost certainly not do what you expect, or at best, will only sometimes do what you want.
You cannot assume that objects will immediately appear in the list and thus be available for further operations. For example:
self.olv.AddObject(aModel)
self.olv.Check(aModel)
If self.olv is a batched update adapter, this code may not work since the AddObject() might not have yet taken effect, so the Check() will not find aModel in the control. Worse, it may work most of the time and fail only occassionally.
If you need to be able to do further processing on objects just added, it would be better not to use a batched adapter.