Major Classes Reference

Interface documentation of the major classes

Major Classes Reference

  • :ref:objectlistview-class
  • :ref:columndefn-class
  • :ref:grouplistview-class
  • :ref:batchedupdate-class

ObjectListView

class ObjectListView.ObjectListView(*args, **kwargs)

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.)

  • cellEditMode

    This control whether and how the cells of the control are editable. It can be set to one of the following values:

    CELLEDIT_NONE

    Cell editing is not allowed on the control This is the default.

    CELLEDIT_SINGLECLICK

    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.

    CELLEDIT_DOUBLECLICK

    Double clicking any cell starts an edit operation on that cell, including the primary cell. Pressing F2 edits the primary cell.

    CELLEDIT_F2ONLY

    Pressing F2 edits the primary cell. Tab/Shift-Tab can be used to edit other cells. Clicking does not start any editing.

  • evenRowsBackColor

    When useAlternateBackColors is true, even numbered rows will have this background color.

  • handleStandardKeys

    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.

    Ctrl-A

    Select all model objects

    Ctrl-C

    Put a text version of the selected rows onto the clipboard (on Windows, this is will also put a HTML version into the clipboard)

    Left-Arrow, Right-Arrow

    [GroupListView only] This will collapse/expand all selected groups.

  • oddRowsBackColor

    When useAlternateBackColors is true, odd numbered rows will have this background color.

  • rowFormatter

    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.

  • typingSearchesSortColumn

    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.

  • useAlternateBackColors

    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.

__init__(*args, **kwargs)

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.

AddColumnDefn(defn)

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.

AddImages(smallImage=None, normalImage=None)
Add the given images to the list of available images. Return the index of the image.
AddNamedImages(name, smallImage=None, normalImage=None)

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.

AddObject(modelObject)

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

AddObjects(modelObjects)

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

AutoSizeColumns()
Resize our auto sizing columns to match the data
CancelCellEdit()
Cancel an edit operation on the given cell.
Check(modelObject)
Mark the given model object as checked.
ClearAll()
Remove all items and columns
CopyObjectsToClipboard(objects)

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.

CopySelectionToClipboard()
Copy the selected objects to the clipboard
CreateCheckStateColumn(columnIndex=0)

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.

DeleteAllItems()
Remove all items
DeselectAll()
De-selected all rows in the control
EnableSorting()
Enable automatic sorting when the user clicks on a column title
EnsureCellVisible(rowIndex, subItemIndex)

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.

FinishCellEdit()
Finish and commit an edit operation on the given cell.
GetCheckState(modelObject)

Return the check state of the given model object.

Returns a boolean or None (which means undetermined)

GetCheckedObjects()
Return a collection of the modelObjects that are checked in this control.
GetFilter()
Return the filter that is currently operating on this control.
GetFilteredObjects()

Return the model objects that are actually displayed in the control.

If no filter is in effect, this is the same as GetObjects().

GetFocusedRow()
Return the index of the row that has the focus. -1 means no focus
GetImageAt(modelObject, columnIndex)
Return the index of the image that should be display at the given column of the given modelObject
GetIndexOf(modelObject)

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.

GetObjectAt(index)
Return the model object at the given row of the list.
GetObjects()

Return the model objects that are available to the control.

If no filter is in effect, this is the same as GetFilteredObjects().

GetPrimaryColumn()

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.

GetPrimaryColumnIndex()

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.

GetSelectedObject()
Return the selected modelObject or None if nothing is selected or if more than one is selected.
GetSelectedObjects()
Return a list of the selected modelObjects
GetSortColumn()
Return the column by which the rows of this control should be sorted
GetStringValueAt(modelObject, columnIndex)
Return a string representation of the value that should be display at the given column of the given modelObject
GetSubItemRect(rowIndex, subItemIndex, flag)

Poor mans replacement for missing wxWindows method.

The rect returned takes scroll position into account, so negative x and y are possible.

GetValueAt(modelObject, columnIndex)
Return the value that should be display at the given column of the given modelObject
HitTestSubItem(pt)

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.

InstallCheckStateColumn(column)

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.

IsCellEditing()
Is some cell currently being edited?
IsChecked(modelObject)
Return a boolean indicating if the given modelObject is checked.
IsObjectSelected(modelObject)
Is the given modelObject selected?
RefreshIndex(index, modelObject)
Refresh the item at the given index with data associated with the given object
RefreshObject(modelObject)
Refresh the display of the given model
RefreshObjects(aList)
Refresh all the objects in the given list
RegisterSortIndicators(sortUp=None, sortDown=None)

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

RemoveObject(modelObject)
Remove the given object from our collection of objects.
RemoveObjects(modelObjects)
Remove the given collections of objects from our collection of objects.
RepopulateList()
Completely rebuild the contents of the list control
SelectAll()
Selected all rows in the control
SelectObject(modelObject, deselectOthers=True, ensureVisible=False)
Select the given modelObject. If deselectOthers is True, all other rows will be deselected
SelectObjects(modelObjects, deselectOthers=True)
Select all of the given modelObjects. If deselectOthers is True, all other rows will be deselected
SetCheckState(modelObject, state)

Set the check state of the given model object.

‘state’ can be True, False or None (which means undetermined)

SetColumnFixedWidth(colIndex, width)
Make the given column to be fixed width
SetColumns(columns, repopulate=True)

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.

SetEmptyListMsg(msg)
When there are no objects in the list, show this message in the control
SetEmptyListMsgFont(font)
In what font should the empty list msg be rendered?
SetFilter(filter)

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.

SetImageLists(smallImageList=None, normalImageList=None)

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.

SetObjects(modelObjects, preserveSelection=False)
Set the list of modelObjects to be displayed by the control.
SetSortColumn(column, resortNow=False)

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

SetValue(modelObjects, preserveSelection=False)
Set the list of modelObjects to be displayed by the control.
SortBy(newColumnIndex, ascending=True)
Sort the items by the given column
SortListItemsBy(cmpFunc, ascending=None)

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.

StartCellEdit(rowIndex, subItemIndex)
Begin an edit operation on the given cell.
ToggleCheck(modelObject)

Toggle the “checkedness” of the given model.

Checked becomes unchecked; unchecked or undetermined becomes checked.

Uncheck(modelObject)
Mark the given model object as unchecked.
YieldSelectedObjects()
Progressively yield the selected modelObjects

ColumnDefn

class ObjectListView.ColumnDefn(title='title', align='left', width=-1, valueGetter=None, imageGetter=None, stringConverter=None, valueSetter=None, isEditable=True, fixedWidth=None, minimumWidth=-1, maximumWidth=-1, isSpaceFilling=False, cellEditorCreator=None, autoCompleteCellEditor=False, autoCompleteComboBoxCellEditor=False, checkStateGetter=None, checkStateSetter=None, isSearchable=True, useBinarySearch=None, headerImage=-1, groupKeyGetter=None, groupKeyConverter=None, useInitialLetterForGroupKey=False, groupTitleSingleItem=None, groupTitlePluralItems=None)

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):

  • align

    How will the title and the cells of the this column be aligned. Possible values: ‘left’, ‘centre’, ‘right’

  • cellEditorCreator

    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).

  • freeSpaceProportion

    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.

  • groupKeyConverter

    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.”

  • groupKeyGetter

    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.

  • groupTitleSingleItem

    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]”

  • groupTitlePluralItems

    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]”

  • headerImage

    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.

  • imageGetter

    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).

  • isEditable

    Can the user edit cell values in this column? Default is True

  • isSearchable

    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.

  • isSpaceFilling

    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.

  • maximumWidth

    An integer indicate the number of pixels above which this column will not resize. Default is -1, which means there is no limit.

  • minimumWidth

    An integer indicate the number of pixels below which this column will not resize. Default is -1, which means there is no limit.

  • useBinarySearch

    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.

  • stringConverter

    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.

  • title

    A string that will be used as the title of the column in the listview

  • valueGetter

    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.

  • valueSetter

    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
      
  • useInitialLetterForGroupKey

    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.

  • width

    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.

__init__(title='title', align='left', width=-1, valueGetter=None, imageGetter=None, stringConverter=None, valueSetter=None, isEditable=True, fixedWidth=None, minimumWidth=-1, maximumWidth=-1, isSpaceFilling=False, cellEditorCreator=None, autoCompleteCellEditor=False, autoCompleteComboBoxCellEditor=False, checkStateGetter=None, checkStateSetter=None, isSearchable=True, useBinarySearch=None, headerImage=-1, groupKeyGetter=None, groupKeyConverter=None, useInitialLetterForGroupKey=False, groupTitleSingleItem=None, groupTitlePluralItems=None)

Create a new ColumnDefn using the given attributes.

The attributes behave as described in the class documentation, except for:

  • fixedWidth

    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.

  • autoCompleteCellEditor

    If this is True, the column will use an autocomplete TextCtrl when values of this column are edited. This overrules the cellEditorCreator parameter.

  • autoCompleteComboBoxCellEditor

    If this is True, the column will use an autocomplete ComboBox when values of this column are edited. This overrules the cellEditorCreator parameter.

CalcBoundedWidth(width)
Calculate the given width bounded by the (optional) minimum and maximum column widths
GetAlignment()
Return the alignment that this column uses
GetAlignmentForText()
Return the alignment of this column in a form that can be used as a style flag on a text control
GetCheckState(modelObject)
Return the check state of the given model object
GetGroupKey(modelObject)
Return the group key for this column from the given modelObject
GetGroupKeyAsString(groupKey)
Return the given group key as a human readable string
GetGroupTitle(group, useItemCount)
Return a title of the group
GetImage(modelObject)
Return the image index for this column from the given modelObject. -1 means no image.
GetStringValue(modelObject)
Return a string representation of the value for this column from the given modelObject
GetValue(modelObject)
Return the value for this column from the given modelObject
HasCheckState()
Return if this column is showing a check box?
IsFixedWidth()
Is this column fixed width?
SetCheckState(modelObject, state)
Set the check state of the given model object
SetFixedWidth(width)
Make this column fixed width
SetValue(modelObject, value)
Set this columns aspect of the given modelObject to have the given value.

GroupListView

class ObjectListView.GroupListView(*args, **kwargs)

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:

  • putBlankLineBetweenGroups

    When this is True (the default), the list will be built so there is a blank line between groups.

__init__(*args, **kwargs)

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.

AddObjects(modelObjects)
Add the given collections of objects to our collection of objects.
Collapse(group)
Collapse the given group and redisplay the list
CollapseAll(groups=None)
Collapse the given groups (or all groups) and redisplay the list
CreateCheckStateColumn(columnIndex=0)
Create a fixed width column at the given index to show the checkedness of objects in this list.
Expand(group)
Expand the given group and redisplay the list
ExpandAll(groups=None)
Expand the given groups (or all groups) and redisplay the list
FindGroupFor(modelObject)
Return the group that contains the given object or None if the given object is not found
GetAlwaysGroupByColumn()
Get the column by which the rows should be always be grouped.
GetFilteredObjects()
Return the model objects that are actually displayed in the control.
GetGroupByColumn()
Return the column by which the rows should be grouped
GetObjectAt(index)

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.

GetSelectedGroups()
Return a list of the groups that are selected
GetShowGroups()
Return whether or not this control is showing groups of objects or a straight list
GetShowItemCounts()
Return whether or not the number of items in a groups should be included in the title
OnGetItemAttr(itemIdx)
Return the display attributes that should be used for the given row
OnGetItemColumnImage(itemIdx, colIdx)
Return the image index at should be shown at the given cell
OnGetItemImage(itemIdx)
Return the image index that should be shown on the primary column of the given item
OnGetItemText(itemIdx, colIdx)
Return the text that should be shown at the given cell
RebuildGroups()

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.

RemoveObjects(modelObjects)
Remove the given collections of objects from our collection of objects.
Reveal(modelObject)
Ensure that the given modelObject is visible, expanding the group it belongs to, if necessary
SelectAll()

Selected all model objects in the control.

In a GroupListView, this does not select blank lines or groups

SelectGroup(modelObject, deselectOthers=True, ensureVisible=False)
Select the given modelObject. If deselectOthers is True, all other rows will be deselected
SelectGroups(modelObjects, deselectOthers=True)
Select all of the given modelObjects. If deselectOthers is True, all other rows will be deselected
SetAlwaysGroupByColumn(column)

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

SetColumns(columns, repopulate=True)
Set the columns for this control.
SetGroups(groups)

Present the collection of ListGroups in this control.

Calling this automatically put the control into ShowGroup mode

SetObjects(modelObjects, preserveSelection=False)
Set the list of modelObjects to be displayed by the control.
SetShowGroups(showGroups=True)
Set whether or not this control is showing groups of objects or a straight list
SetShowItemCounts(showItemCounts=True)
Set whether or not the number of items in a groups should be included in the title
SortGroups(groups=None, ascending=None)

Sort the given collection of groups in the given direction (defaults to ascending).

The model objects within each group will be sorted as well

ToggleExpansion(group)
Toggle the expanded/collapsed state of the given group and redisplay the list
YieldSelectedObjects()

Progressively yield the selected modelObjects.

Only return model objects, not blank lines or ListGroups


BatchedUpdate

class ObjectListView.BatchedUpdate(objectListView, updatePeriod=0)

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.

This class only intercepts the following messages:
  • AddObject(), AddObjects()
  • RefreshObject(), RefreshObjects()
  • RemoveObject(), RemoveObjects()
  • RepopulateList()
  • SetObjects()

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:

  1. 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.

  2. 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.