ObjectList tutorial

This blog post will give you an introduction to the ObjectList widget which is a part of the kiwi library.

* Rationale

Creating graphical user interfaces which displays a sequence of objects is a common task. In the GTK+ toolkit you will normally use a GtkTreeView for this. GtkTreeView is a very flexible and extensible widget, for instance it allows you to separate the data storage from the representation. However the disadvantage of using the GtkTreeView is that it’s a little bit too complicated to use, especially for beginners.

The ObjectList aims to provide a familiar API to create, manipulate and access sequences of objects. It builds on top of GtkTreeView, and allows you to access the “raw” objects (view, columns, model, cellrenderers, selection) in case you want to do something which is not directly supported by the ObjectList.

Kiwi and ObjectList are tied to the Python programming language and depends heavily on PyGTK (and thus CPython). However the concepts introduced in the widget are usually not specific to Python, it’s very possible to implement similar high level wrappers on top of GtkTreeView for C#, Java etc.

* Simple ObjectList example

Here is the source code and the output of a simple ObjectList example

Let’s walk through the example and explain what it does.

• The class Fruit is defined with two attributes; name and price.
• An ObjectList called fruits is created which has two columns, name and price
• 5 objects are created and inserted into the list.

The example is concluded by creating a PyGTK window, adding the objectlist to it and running the main loop.
The data displayed in the ObjectList is stored in normal python instances, there is no need to create and set column types for a GtkTreeModel and extract the data from your python objects and insert it into the model. The model / view separation is kept while still keeping it easy to use.

Notice that the data is appended to the list by calling the append() method of the ObjectList, this is intentionally similar to the append method of the builtin list type of python. If you wanted you could use the extend() method to insert a list of object at one go.

The objects inserted into the list can be modified by using standard python list concepts:

• iteration: for item in list
• accessing an individual item: list[n]
• removing an item: del list[n] or list.remove(item)
• accessing parts of the item: list[n:m]

There are also methods beyond a normal python list routines which only makes sense in graphical interfaces:

• selecting an item: list.select(item)
• getting the selected item: list.get_selected()
• changing the columns: list.set_columns(columns)
• getting the columsn: list.get_columns()
• etc…

* Columns

When you create a column you define how the data is going to be displayed. Column width, sorting, justification, markup and so on. Here is an incomplete list of the support column attributes:

• title: the text will be used in the column header
• justify: the justification, eg left or right aligned
• format: printf style format string
• width: width in pixels of the column
• sorted: if we should sort the data after the content in this column
• editable: is the column editable?
• use_markup: should the content be interpreted as markup?
• use_stock: treat the content as stock icon names and display icons

Here is a more complicated, real world example from Stoq, a Retail Management System written on top of Kiwi.

The interface shows the accounts payable application which lists outgoing payments.

What we can see from the screenshot is:

• The first column is sorted and it has the title “#”
• The third column is the supplier name which is a bit too wide to fit and uses ellipsize
• The fourth column is the date the purchase was sold and is formatted according to the current locale
• The last column uses the special datatype currency which formats a number according to the monetary rules defined for the current locale, with thousand separators, decimal points and currency symbols set right.

This is all for now, for more information about Kiwi check out Howto, the API reference and the source code repository