Tree and List Widget Overview3GTK LibraryTree and List Widget OverviewOverview of GtkTreeModel, GtkTreeView, and other associated widgetsOverview
To create a tree or list in GTK+, you need to 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 tree view widget (GtkTreeView)the view column (GtkTreeViewColumn)the cell renderers (GtkCellRenderer etc.)and the model interface (GtkTreeModel)
The View is composed of the first three,
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 you
render it as a string of "True" or "False", "On" or "Off", or should
you render it as a checkbox?
Creating a model
GTK+ 2.0 provides two types of models that can be used:
GtkListStore and
GtkTreeStore. GtkListStore is
used to model columned list widgets, while GtkTreeStore models
columned tree widgets. 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.
Columns and cell renderers
Once the GtkTreeView widget
has a model, it will need to know how to display the model. It
does this with columns and cell renderers.
Cell renderers are used to draw the data in the tree model in a
way. There are three cell renderers that come with GTK+ 2.0.
They are the GtkCellRendererText, GtkCellRendererPixbuf and
the GtkCellRendererToggle.
It is relatively easy to write a custom renderer.
A GtkTreeViewColumn is the
object that GtkTreeView uses to organize the vertical columns in
the tree view. It needs to know the name of the column to label
for the user, what type of cell renderer to use, and which piece of
data to retrieve from the model for a given row.
At this point, all the steps in creating a displayable tree have been
covered. The model is created, data is stored in it, a tree view is
created and columns are added to it.
Selection handling
Most applications will need to not only deal with displaying data, but also
receiving input events from users. To do this, simply get a reference to
a selection object and connect to the "changed" signal.
Then to retrieve data for the row selected:
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.