Gtk.TreeModel

Data itself is stored within classes that implement the Gtk.TreeModel interface. GTK+ provides four types of built-in tree model classes, but only Gtk.ListStore and Gtk.TreeStore is covered in this chapter.

The Gtk.TreeModel interface provides a standard set of methods for retrieving general information about the data that is stored. For example, it allows you to get the number of rows in the tree and the number of children of a certain row. Gtk.TreeModel also gives you a way to retrieve the data that is stored in a specific row of the store.

Gtk.ListStore allows you to create a list of elements with multiple columns. Each row is a child of the root node, so only one level of rows is displayed. Basically, Gtk.ListStore is a tree structure that has no hierarchy. It is only provided because faster algorithms exist for interacting with models that do not have any child items.

Gtk.TreeStore provides the same functionality as Gtk.ListStore, except the data can be organized into a multilayered tree. GTK+ provides a method for creating your own custom model types as well, but the two available types should be suitable in most cases.

While Gtk.ListStore and Gtk.TreeStore should fit most applications, a time may come when you need to implement your own store object. For example, if it needs to hold a huge number of rows, you should create a new model that is more efficient. In Chapter 12, you learn how to create new classes derived from GObject, which can be used as a guide to get you started deriving a new class that implements the Gtk.TreeModel interface.

After you have created the tree model, the view is used to display the data. By separating the tree view and its model, you are able to display the same set of data in multiple views. These views can be exact copies of each other, or the data can be displayed in varying ways. All the views are updated simultaneously as you make alterations to a model.

Models are composed of columns that contain the same data type and rows that hold each set of data. Each model column can hold a single type of data. A tree model column should not be confused with a tree view column, which is composed of a single header but may be rendered with data from multiple model columns. For example, a tree column may display a text string that has a foreground color defined by a model column that is not visible to the user. Figure 9-2 illustrates the difference between model columns and tree columns.

Each row within a model contains one piece of data corresponding to each model column. In Figure 9-2, each row contains a text string and a Gdk.Color value. These two values are used to display the text with the corresponding color in the tree column. You learn how to implement this in code later in this chapter. For now, you should simply understand the differences between the two types of columns and how they relate.

New list and tree stores are created with a number of columns, each defined by an existing GObject.TYPE. Usually, you need to use only those already implemented in GLib . For example, if you want to display text you can use GObject.TYPE_STRING, GObject.TYPE_BOOLEAN, and a few of the number types like GObject.TYPE_INT.

Gtk.TreeViewColumn and Gtk.CellRenderer

As previously mentioned, a tree view displays one or more Gtk.TreeViewColumn objects. Tree columns are composed of a header and cells of data that are organized into one column. Each tree view column also contains one or more visible columns of data. For example, in a file browser, a tree view column may contain one column of images and one column of file names.

The header of the Gtk.TreeViewColumn widget contains a title that describes what data is held in the cells below. If you make the column sortable, the rows are sorted when one of the column headers is clicked.

Tree view columns do not actually render anything to the screen. This is done with an object derived from Gtk.CellRenderer. Cell renderers are packed into tree view columns similar to how you add widgets into a horizontal box. Each tree view column can contain one or more cell renderers, which are used to render the data. For example, in a file browser, the image column would be rendered with

Gtk.CellRendererPixbuf and the file name with Gtk.CellRendererText. An example of this was shown in Figure 9-1.

Each cell renderer is responsible for rendering a column of cells, one for every row in the tree view. It begins with the first row, rendering its cell and then proceeding to the next row down until the whole column, or part of the column, is rendered.

In GTK+ 3 the g_object_set() function is no longer available. So you must add attributes to the renderer. Column attributes correspond to tree model columns and are associated with cell renderer properties, as shown in Figure 9-3. These properties are applied to each cell as it is rendered.

In Figure 9-3, there are two tree model columns with the types GObject.TYPE_STRING and Gdk.RGBA. These are applied to Gtk.CellRendererText’s text and foreground properties and used to render the tree view column accordingly.

An additional way to change cell renderer properties is by defining a cell data function. This function is called for every row in the tree view before it is rendered. This allows you to customize how every cell is rendered without the need for the data to be stored in a tree model. For example, a cell data function can be used to define how many decimal places of a floating-point number to display. Cell data functions are covered in detail in the “Cell Data Methods” section of this chapter.

This chapter also covers cell renderers that are used to display text (strings, numbers, and Boolean values), toggle buttons, spin buttons, progress bars, pixbufs, combo boxes, and keyboard accelerators. In addition, you can create custom cell renderer types, but this is usually not needed, since GTK+ now provides such a wide variety of types.

This section has taught you what objects are needed to use the Gtk.TreeView widget, what they do, and how they interrelate. Now that you have a basic understanding of the Gtk.TreeView widget, the next section has a simple example of the Gtk.ListStore tree model.

Creating the Tree View

Creating the Gtk.TreeView widget is the easiest part of the process. You need only to call Gtk.TreeView.new(). A tree model can easily be applied to a Gtk.TreeView after initialization with treeview.set_model(store).

Until GTK+ 3 came along, there were functions to hide/unhide the column header for a Gtk.TreeViewColumn. Those functions have been deprecated in GTK+ 3 and now all column headers are always visible.

Gtk.TreeViewColumn headers provide more functionality beyond column titles for some tree views. In sortable tree models, clicking the column header can initiate sorting of all of the rows according to the data held in the corresponding column. It also gives a visual indication of the sort order of the column if applicable. You should not hide the headers if the user needs them to sort the tree view rows.

As a GTK+ developer, you should be very careful about changing visual properties. Users have the ability to choose themes that fit their needs, and you can make your application unusable by changing how widgets are displayed.

Renderers and Columns

After creating the Gtk.TreeView, you need to add one or more columns to the view for it to be of any use. Each Gtk.TreeViewColumn is composed of a header, which displays a short description of its content, and at least one cell renderer. Tree view columns do not actually render any content. Tree view columns hold one or more cell renderers that are used to draw the data on the screen.

All cell renderers are derived from the Gtk.CellRenderer class and are referred to as objects in this chapter, because Gtk.CellRenderer is derived directly from GObject, not from Gtk.Widget. Each cell renderer contains a number of properties that determine how the data is drawn within a cell.

The Gtk.CellRenderer class provides common properties to all derivative renderers, including background color, size parameters, alignments, visibility, sensitivity, and padding. A full list of Gtk.CellRenderer properties can be found in Appendix A. It also provides the editing-canceled and editing-started signals, which allow you to implement editing in custom cell renderers.

In Listing 9-1, you were introduced to Gtk.CellRendererText, which is capable of rendering strings, numbers, and boolean values as text. Textual cell renderers are initialized with Gtk.CellRendererText.new().

Gtk.CellRendererText provides a number of additional properties that dictate how each cell is rendered. You should always set the text property, which is the string that is displayed in the cell. The rest of the properties are similar to those used with text tags.

The preceding function accepts a string to display in the column header, a cell renderer, and a list of attributes. Each attribute contains a string that refers to the renderer property and the tree view column number. The important thing to realize is that the column number provided to Gtk.TreeViewColumn() refers to the tree model column, which may not be the same as the number of tree model columns or cell renderers used by the tree view.

If you want to add multiple renderers to the tree view column, you need to pack each renderer and set its attributes separately. For example, in a file manager, you might want to include a text and an image renderer in the same column. However, if every column only needs one cell renderer, it is easiest to use Gtk.TreeViewColumn().

After you have finished setting up a tree view column, it needs to be added to the tree view with treeview.append_column(column). Columns may also be added into an arbitrary position of the tree view with treeview.insert_column(column) or removed from the view with treeview.remove_column(column).

Creating the Gtk.ListStore

The tree view columns are now set up with the desired cell renderers, so it is time to create the tree model that interfaces between the renderers and the tree view. For the example found in Listing 9-1, we used Gtk.ListStore so that the items would be shown as a list of elements.

In Python 3, the column type parameters are formed into a tuple. That tells the method not only the column type but also the number of columns.

Next, we need to set which column and what values are to be loaded with data. This is done with the store.set() method. One or more rows can be set with this method. The preceding example stores values in each column of the row from left to right, but the column can be listed in any order since we are also specifying the column number where the value is loaded.

There are multiple other functions for adding rows to a list store, including store.prepend() and store.insert(). A full list of available functions can be found in the Gtk.ListStore API documentation.

In addition, store.clear() is provided, which can be used to remove all rows from a list store. You are left with a Gtk.ListStore that contains no data.

After the list store is created, you need to call treeview.set_model() to add it to the tree view. By calling this method, the reference count of the tree model is incremented by one.

Tree Paths

For example, if you are presented with the string 3:7:5, you would start at the fourth root element (recall that indexing begins at zero, so element three is actually the fourth element in the level). You would next proceed to the eighth child of that root element. The row in question is that child’s sixth child.

To illustrate this graphically, Figure 9-6 shows the tree view created in Figure 9-5 with the tree paths labeled. Each root element is referred to as only one element, 0 and 1. The first root element has two children, referred to as 0:0 and 0:1.

Two functions are provided that allow you to convert back and forth between a path and its equivalent string: treepath.to_string() and Gtk.TreePath.new_from_string(). You usually do not have to deal with the string path directly unless you are trying to save the state of a tree view, but using it helps in understanding the way tree paths work.

In addition to treepath.up(), there are other functions that allow you to navigate through a tree model. You can use treepath.down() to move to the child row and treepath.next() or treepath.prev() to move to the next or previous row in the same level. When you move to the previous row or parent row, False is returned if it was not successful.

Problems can arise with tree paths when a row is added or removed from the tree model. The path could end up pointing to a different row within the tree or, worse, a row that does not exist anymore! For example, if a tree path points to the last element of a tree and you remove that row, it now points beyond the limits of the tree. To get around this problem, you can convert the tree path into a tree row reference.

Tree Row References

Gtk.TreeRowReference objects are used to watch a tree model for changes. Internally, they connect to the "row-inserted", "row-deleted", and "rows-reordered" signals, updating the stored path based on the changes.

When you need to retrieve the path, you can use treerowref.get_path(), which returns None if the row no longer exists within the model. Tree row references are able to update the tree path based on changes within the tree model, but if you remove all elements from the same level as the tree path’s row, it no longer has a row to point to.

You should be aware that tree row references do add a small bit of overhead processing when adding, removing, or sorting rows within a tree model, since the references have to handle all of the signals emitted by these actions. This overhead does not matter for most applications, because there will not be enough rows for the user to notice. However, if your application contains a large number of rows, you should use tree row references wisely.

Tree Iterators

GTK+ provides the Gtk.TreeIter object, which can be used to reference a specific row within a Gtk.TreeModel. These iterators are used internally by models, which means that you should never directly alter the content of a tree iterator.

You have already seen multiple instances of Gtk.TreeIter, from which you can discern that tree iterators are used in a similar way to Gtk.TreeIter. Tree iterators are used for manipulation of tree models. Tree paths, however, are used to point to rows within a tree model in a way that provides a human-readable interface. Tree row references can be used to make sure that tree paths adjust where they point throughout changes of a tree model.

GTK+ provides a number of built-in methods to perform operations on the tree iterators. Typically, iterators are used to add rows to a model, set the content of a row, and retrieve the content of a model. In Figure 9-1 and Figure 9-2, tree iterators were used to add rows to Gtk.ListStore and Gtk.TreeStore models and then set the initial content of each row.

Gtk.TreeModel provides a number of iter_*() methods, which can be used to move iterators and retrieve information about them. For example, to move to the next iterator position, you could use treemodel.iter_next(), which returns True if the action was successful. A full list of available functions can be found in the Gtk.TreeModel API documentation.

The first method in Listing 9-4, treemodel.get_path() converts a valid tree iterator into a tree path. That path is then sent to treemodel.get_iter(), which converts it back into an iterator. Notice that the second method accepts two parameters.

Even if the iterator is set to persist, it is not a good idea to store tree iterator objects, since they are used internally by tree models. Instead, you should use tree row references to keep track of rows over time, since references will not become invalidated when the tree model changes.

Single Selections

Selection information is held for each tree view by a Gtk.TreeSelection object. You can retrieve this object with treeview.get_selection(). A Gtk.TreeSelection object is automatically created for you for every Gtk.TreeView, so there is never a need to create your own tree selection.

The treeselection.get_selected() method can be used to retrieve the tree model associated with the Gtk.TreeSelection object and a tree iterator pointing to the selected row. True is returned if the model and iterator were successfully set. This function will not work with a selection mode of Gtk.SelectionMode.MULTIPLE!

If no row has been selected, the tree iterator is set to None, and False is returned from the function. Therefore, treeselection.get_selected() can also be used as a test to check whether or not there is a selected row.

Multiple Selections

You can then perform some operation on each row within the list. However, you need to be careful. If you need to edit the tree model within the List, you want to first convert all of the tree paths to tree row references, so they continue to be valid throughout the duration of your actions.

If you want to loop through all of the rows manually, you are also able to use treeselection.count_selected_rows(), which returns the number of rows that are currently selected.

Adding New Rows

Now that you have been introduced to selections, it is time to add the ability to add new products to the list.

The only difference in this example in comparison to the previous Grocery List application is visible in Figure 9-7, which shows that an Add and Remove buttons were added along the bottom of the tree view. Also, the selection mode was changed to allow the user to select multiple rows at a time.

Listing 9-6 is the implementation of the callback function that is run when the user clicks the Add button. It presents the user with a Gtk.Dialog that asks the user to choose a category, enter a product name and quantity of products to buy, and select whether or not to purchase the product.

Handling Double-clicks

In Listing 9-8, the callback method row_activated() is called when the user activates a row within the tree view. The activated row is retrieved from the tree path object with treemodel.get_iter(). From there, you are free to use whatever functions/methods you have learned thus far to retrieve or alter the content of the row.

Toggle Button Renderers

Displaying Boolean values as “TRUE” or “FALSE” with Gtk.CellRendererText is a bit tacky, and it takes up a large amount of valuable space in each row, especially when there are a lot of visible Boolean columns. You might be thinking that it would be nice if you could display a check button for Boolean values instead of text strings. It turns out that you can — with the help of a type of cell renderer named Gtk.CellRendererToggle.

By default, toggle button cell renderers are drawn as a check button, as shown in Figure 9-10. You can also set up toggle button renderers to be drawn as radio buttons, but you need to manage the radio button functionality yourself.

Toggle cell renderers are created with Gtk.CellRendererToggle.new(). After creating a toggle cell renderer, you want to set its activatable property to True so that it can be toggled; otherwise, the user will not be able to toggle the button (which can be useful if you only want to display a setting but not allow it to be edited). column.property_set() can be used to apply this setting to every cell.

Next, the active property should be added as a column attribute instead of text, which was used by Gtk.CellRendererText. This property is set to True or False, depending on the desired state of the toggle button.

Then, you should connect the Gtk.CellRendererToggle cell renderer to a callback function for the toggled signal. Listing 9-11 gives an example callback function for the toggled signal. This callback function receives the cell renderer and a Gtk.TreePath string pointing to the row that contains the toggle button.

To toggle the value, you can use model.get() to retrieve the current value stored by the cell. Since the cell is storing a Boolean value, you can set the new value to the opposite of the current in model.set_row().

You need to realize that the only thing that is changed by setting radio to True is the rendering of the toggle button! You have to manually implement the functionality of a radio button through your toggled callback function. This includes activating the new toggle button and deactivating the previously selected toggle button.

Pixbuf Renderers

Adding images in the form of GdkPixbuf objects as a column in a Gtk.TreeView is a very useful feature provided by Gtk.CellRendererPixbuf. An example of a pixbuf renderer is shown in Figure 9-11, in which there is a small icon to the left of each item.

New Gtk.CellRendererPixbuf objects are created with Gtk.CellRendererPixbuf.new(). You then want to add the renderer to the column. Since there is multiple renderers Gtk.CellRendererPixbuf.new() in our column, you can use column.pack_start() to add the renderer to the column. It is important to pack the renderer into the column BEFORE adding an attributes. Failure to do this invalidates the renderer and you receive a runtime warning and no data appears in the column.

Next, you need to add attributes to the column for the Gtk.CellRendererPixbuf. In Listing 9-12, the pixbuf property was used so that we could load a custom icon from a file. However, pixbufs are not the only type of image supported by Gtk.CellRendererPixbuf.

If you are using a Gtk.TreeStore, it is useful to display a different pixbuf when the row is expanded and when it is retracted. To do this, you can specify two GdkPixbuf objects to pixbuf-expander-open and pixbuf-expander-closed. For example, you may want to do this to display an open folder when the row is expanded and a closed folder when the row is retracted.

When you create the tree model, you need to use a new type called GdkPixbuf.Pixbuf, which stores GdkPixbuf objects in each model column. Every time you add a GdkPixbuf to a tree model column, its reference count is incremented by one.

Spin Button Renderers

In Chapter 5, you learned how to use the Gtk.SpinButton widget. While Gtk.CellRendererText can display numbers, a better option is to use Gtk.CellRendererSpin. Instead of displaying a Gtk.Entry when the content is to be edited, a Gtk.SpinButton is used. An example of a cell rendered with Gtk.CellRendererSpin that is being edited is shown in Figure 9-12.

Recall that if you want to dictate the number of decimal places shown by a floating-point number in a column using Gtk.CellRendererText or another derived renderer, you need to use a cell data function. In Listing 9-13, a sample cell data function was shown that reads in the current floating-point number and forces the renderer to display no decimal places. This is necessary because Gtk.CellRendererSpin stores numbers as floating-point numbers.

Gtk.CellRendererSpin provides three properties: adjustment, climb rate, and digits. These are stored in a Gtk.Adjustment defining the spin button’s properties, the acceleration rate when an arrow button is held down, and the number of decimal places to display in the spin button respectively. The climb rate and number of decimals to display are both set to zero by default.

After setting up the cell renderer, you should then connect to the edited signal to the cell renderer, which is used to apply the new value chosen by the user to the cell. There is usually no need to filter this value, because the adjustment already limits the values allowed by the cell. The callback function is run after the user presses the Enter key or moves focus from the spin button of a cell that is being edited.

Within the cell_edited()callback method in Listing 9-14 you need to first retrieve the adjustment of the spin button renderer, because it stores the new value that is to be displayed. This new value can then be applied to the given cell.

You can retrieve the adjustment’s value with renderer.get_property("adjustment"), applying it to the appropriate column. if the QUANTITY column is used to display a floating-point number (GObject.TYPE_FLOAT), you can use the returned type in its current state. We have instead chosen to convert the float value to a string value.

When creating the tree model, the column must be of the type GObject.TYPE_FLOAT, even if you want to store an integer. You should use cell data functions to limit the number of decimal places displayed by each cell.

Combo Box Renderers

Gtk.CellRendererCombo provides a cell renderer for a widget that you have just learned about, Gtk.ComboBox. Combo box cell renderers are useful, because they allow you to present multiple predefined options to the user. Gtk.CellRendererCombo renders text in a similar way to Gtk.CellRendererText, but instead of showing a Gtk.Entry widget when editing, a Gtk.ComboBox widget is presented to the user. An example of a Gtk.CellRendererCombo cell being edited is shown in Figure 9-13.

The first property you need to set is "text_column", which refers to the column in the combo box’s tree model that is displayed in the cell renderer. This must be a type supported by Gtk.CellRendererText, such as GObject.TYPE_STRING, GObject.TYPE_INT, or GObject.TYPE_BOOLEAN. The model property is a Gtk.TreeModel that is used as the content of the combo box. You must also set the editable property to True, so the cell content may be edited.

Lastly, there is a widget called Gtk.ComboBoxEntry that gives the user choices like a normal combo box, but it also uses a Gtk.Entry widget to allow the user to enter a custom string instead of choosing an existing option. To allow this functionality with a combo box cell renderer, you must set the has-entry property to True. This is turned on by default, which means that you must turn it off to restrict the choices to those that appear in Gtk.CellRendererCombo’s tree model.

As with other cell renderers derived from Gtk.CellRendererText, you want to use the text field as the column attribute and set its initial text when creating the tree view’s model. You can then use the edited signal to apply the text to the tree model. In Listing 9-15, the changes are only applied when the "new_text" string is not empty, since the user is free to enter free-form text as well.

Progress Bar Renderers

Another type of cell renderer is Gtk.CellRendererProgress, which implements the Gtk.ProgressBar widget. While progress bars support pulsing, Gtk.CellRendererProgress only allows you to set the current value of the progress bar. Figure 9-14 shows a Gtk.TreeView widget that has a progress bar cell renderer in the second column, which displays textual feedback.

Progress bar cell renderers are another easy feature to implement in a program. You can use Gtk.CellRendererProgress() to create new Gtk.CellRendererProgress objects. Gtk.CellRendererProgress provides two properties: "text" and "value". The progress bar state is defined by the "value" property, which is an integer with a value between 0 and 100. A value of 0 refers to an empty progress bar, and 100 refers to a full progress bar. Since it is stored as an integer, the tree model column corresponding to the value of the progress bar should have the type GObject.TYPE_INT.

The second property provided by Gtk.CellRendererProgress is text. This property is a string that is drawn over the top of the progress bar. This property can be ignored in some cases, but it is usually a good idea to give the user more information about the progress of a process. Examples of possible progress bar strings are “67% Complete”, “3 of 80 Files Processed”, “Installing foo . . .”, and so on.

Gtk.CellRendererProgress is a useful cell renderer in some cases, but you should be careful when you deploy it. You should avoid using multiple progress bars in one row, because doing so could confuse the user and takes up a lot of horizontal space. Also, tree views with many rows appear messy. In many cases, it would be better for the user to use a textual cell renderer instead of a progress bar cell renderer.

However, there are some cases where Gtk.CellRendererProgress is a good choice. For example, if your application has to manage multiple downloads at the same time, progress bar cell renderers are an easy way to give coherent feedback about progress for each download.

Keyboard Accelerator Renderers

GTK+ 2.10 introduced a new type of cell renderer called Gtk.CellRendererAccel, which displays a textual representation of a keyboard accelerator. An example of an accelerator cell renderer is shown in Figure 9-15.

Listing 9-16 creates a list of actions along with their keyboard accelerators. This type of tree view could be used to allow the user to edit the accelerators for an application. The accelerator is displayed as text, since the renderer is derived from Gtk.CellRendererText.

Gtk.CellRendererAccel provides two signals. The first, accel-cleared, allows you to reset the accelerator when the user removes the current value. In most cases, you will not need to do this unless you have a default value that you want the accelerator to revert to.

Of greater importance, accel-edited allows you to apply changes that the user makes to the keyboard accelerator, as long as you set the editable property to True. The callback function receives a path string to the row in question along with the accelerator key code, mask and hardware key code. In the callback function, you can apply the changes with store.set(), as you would with any other editable type of cell.

Exercise 1: File Browser

By now, you have probably had enough of Grocery List applications, so let’s try something different. In this exercise, create a file browser using the Gtk.TreeView widget. You should use Gtk.ListStore for the file browser and allow the user to browse through the file system.

The file browser should show images to differentiate among directories and files. Images are found in the downloadable source code at www.gtkbook.com . You can also use the Python directory utility functions to retrieve directory content. Double-clicking a directory should move you to that location.