Widget components

The following section covers the usage of the components used by the ocempgui.widgets module. Components denote elements, which are strongly wired with or used by a widget, but do not inherit from the BaseWidget in any way. The components can be found in the ocempgui.widgets.components submodule.


The ListItem component is an abstract base class for creating own item implementations, which are suitable for the usage in list or tree widgets. It contains a set of attributes and methods, which make it ready to be used in the ListItemCollection collection class.

You usually will not create ListItem objects directly, but instead subclass them, whenever you need a more advanced or specialized item type, than the TextListItem and FileListItem offer.

Similar to the widgets inheriting from the BaseWidget class, the ListItem offers a style attribute, that lets you set up an instance specific look and feel for it.

# Create the instance specific style information.
listitem.style['font']['size'] = 16 

The collection, the item should be or is bound to, can be read and set by accessing its collection attribute.

if listitem.collection != my_collection:
    listitem.set_collection (my_collection)

To make the ListItem suitable for tree or list widgets, it contains a selected attribute that, as the name says, can be used by the according widget implementation to set or determine the selection state of the item.

if not listitem.selected:
    listitem.selected = True

For optimization purposes in drawing the ListItem contains, similar to the BaseWidget, a dirty attribute and set_dirty() method.

listitem.dirty = True
Changing its value to True will try to inform its collection about that the item has changed, so that an updating process can be started.

For concrete implementations and examples, the author recommends to look at the source code of the TextListItem and FileListItem implementations, which will be explained hereafter.


The TextListItem - as its name suggests - is a ListItem, that is able to store and show text. Besides this it does not offer anything oustanding so that its only improvements are to set and get text.

A TextListItem is created by passing the text it should store to its constructor.

listitem = TextListItem ("This is a TextListItem")
It is not needed to set the text explicitly at creation time. It can be fetched or changed at any time with the text attribute.
listitem.text = "I contain changed text."


The FileListItem is an advanced TextListItem, which contains additional attributes to make it suitable for storing different file related information.

The FileListItem requires besides a text the file mode information (those are explained in detail in the stat documentation).

# Retrieve the stats for a file.
st = os.stat ("myfile")

# Create the item with the file modes.
listitem = ("myfile", st.st_mode)

Dependant on the passed file mode, which will be stored in the filetype attribute,

if stat.S_ISDIR (listitem.filetype):
    print "Item %s is a directory, hooray!" % listitem.text
the FileListItem will set load a matching icon into its icon attribute (at construction time). This icon will be taken from the Icons16x16 icon constants of the ocempgui.widgets.images submodule by default.


The ListItemCollection is a wrapper around the python builtin type list. It supports a set of most important list operations, such as iterators, slicing and sorting. Several methods, especially the arithmetic overloads (addition, mulitplication, etc.) are not available. For a complete list of supported operations, browse the documentation strings of the ListItemCollection.

The ListItemCollection is created by simply invoking its constructor.

collection = ListItemCollection ()
Items can be added in a similar way to the list type using the insert(), append() or extend() methods for example.
collection.append (item1)
collection.insert (9, item2)

The specialities of the ListItemCollection are, that it only accepts ListItem objects as valid items on the one hand and supports two notification slots on the other. Those notification slots are implemented as attributes, item_changed and list_changed. Any method or function can be bound to those to get informed about item changes in the list (e.g. an item has changed its contents) and list changes in general (items were added, removed, etc.). The item_changed attribute additionally passes the affected item to the notification handler, while list_changed() will pass the ListItemCollection.

You can find the following example as a python script under examples/listitemcollection.py.

# ListItemCollection example.
from ocempgui.widgets.components import ListItemCollection, TextListItem

# Item change handler.
def item_has_changed (item):
    print "Item '%s' has changed" % item.text

# List change handler.
def list_has_changed (l):
    print "List now contains %d item(s)" % l.length

collection = ListItemCollection ()

# Set up a notification handler for item changes.
collection.item_changed = item_has_changed

# Set up a notification handler for list changes
collection.list_changed = list_has_changed

for i in xrange (5):
    collection.append (TextListItem ("Item no. %d" % i))

collection[2].text = "New text in item 3"

# Use a tuple as constructor argument.
items = (TextListItem ("String 1"), TextListItem ("String 2"),
         TextListItem ("String 3"))
collection = ListItemCollection (items)
print "New collection:"
print collection

Example 47. ListItemCollection example