Tree and List Widget Overview

Overview

To create a tree or list in GTK+, use the GtkTreeModel interface in conjunction with the GtkTreeView widget. This widget is designed around a Model/View/Controller design and consists of four major parts:

The View is composed of the first three objects, while the last is the Model. One of the prime benefits of the MVC design is that multiple views can be created of a single model. For example, a model mapping the file system could be created for a file manager. Many views could be created to display various parts of the file system, but only one copy need be kept in memory.

The purpose of the cell renderers is to provide extensibility to the widget and to allow multiple ways of rendering the same type of data. For example, consider how to render a boolean variable. Should it render it as a string of "True" or "False", "On" or "Off", or should it be rendered as a checkbox?

Creating a model

GTK+ provides two simple models that can be used: the GtkListStore and the GtkTreeStore. GtkListStore is used to model list widgets, while the GtkTreeStore models trees. It is possible to develop a new type of model, but the existing models should be satisfactory for all but the most specialized of situations. Creating the model is quite simple:

This creates a list store with two columns: a string column and a boolean column. Typically the 2 is never passed directly like that; usually an enum is created wherein the different columns are enumerated, followed by a token that represents the total number of columns. The next example will illustrate this, only using a tree store instead of a list store. Creating a tree store operates almost exactly the same.

Adding data to the model is done using gtk_tree_store_set() or gtk_list_store_set(), depending upon which sort of model was created. To do this, a GtkTreeIter must be acquired. The iterator points to the location where data will be added.

Once an iterator has been acquired, gtk_tree_store_set() is used to apply data to the part of the model that the iterator points to. Consider the following example:

Notice that the last argument is -1. This is always done because this is a variable-argument function and it needs to know when to stop processing arguments. It can be used to set the data in any or all columns in a given row.

The third argument to gtk_tree_store_append() is the parent iterator. It is used to add a row to a GtkTreeStore as a child of an existing row. This means that the new row will only be visible when its parent is visible and in its expanded state. Consider the following example:

Creating the view component

While there are several different models to choose from, there is only one view widget to deal with. It works with either the list or the tree store. Setting up a GtkTreeView is not a difficult matter. It needs a GtkTreeModel to know where to retrieve its data from.

Simple Example

Here is a simple example of using a GtkTreeView widget in context of the other widgets. It simply creates a simple model and view, and puts them together. Note that the model is never populated with data — that is left as an exercise for the reader. More information can be found on this in the GtkTreeModel section.

GtkListStore *store = gtk_list_store_new (2, G_TYPE_STRING, G_TYPE_BOOLEAN);