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

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

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

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.

# 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