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.

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.

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.

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.

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.

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.

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.

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:

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:

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.