The TreeModel interface defines a generic storage object for use by the TreeView and similar widgets. Specifically, the functions in defined here are used by Gtk's widgets to access the stored data. Thus, rather than calling these functions, an application programmer has to implement them. While the module Graphics.UI.Gtk.ModelView.CustomStore provides the necessary functions to implement the TreeMode interface, it is often sufficient to use the wo implementations that come with Gtk2Hs, namely are ListStore and TreeStore.

The model is represented as a hierarchical tree of values. It is important to note that this interface only provides a way of examining a model and observing changes. The implementation of each individual model decides how and if changes are made.

Two generic models are provided that implement the TreeModel interface: the TreeStore and the ListStore. To use these, the developer simply inserts data into these models as necessary. These models provide the data structure as well as the TreeModel interface. In fact, they implement other interfaces, making drag and drop and storing data trivial.

A TreeModel stores records of the same type. Each record is referred to as row, just like in a relational database. Defining how the information of a row is displayed can be done in two ways: If the widget displays data using Graphics.UI.Gtk.ModelView.CellRenderer.CellRenderer or one of its derivatives, it is possible to state how a row is mapped to the attributes of a renderer using the Graphics.UI.Gtk.ModelView.CellLayout.cellLayoutSetAttributes function. Some widgets do not use Graphics.UI.Gtk.ModelView.CellRenderer.CellRenderers to display their data. In this case an extraction function can be defined that maps a row to one of a few basic types (like Strings or Ints). This extraction function is associated with a ColumnId using Graphics.UI.Gtk.ModelView.CustomStore.treeModelSetColumn. The latter can be set in the widget for the property that should be set. The widget then uses the function treeModelGetValue and the ColumnId to extract the value from the model. As the name suggests, using ColumnIds creates a view of the data as if each row were divided into a well-defined set of columns, again, like a relational database.

Models are accessed on a node level of granularity. There are two index types used to reference a particular node in a model. They are the TreePath and the TreeIter. Most of the interface consists of operations on a TreeIter.

A path is essentially a potential node. It is a location on a model that may or may not actually correspond to a node on a specific model. A TreePath is in fact a synonym for a list of Ints and hence are easy to manipulate. Each number refers to the offset at that level. Thus, the path [0] refers to the root node and the path [2,4] refers to the fifth child of the third node.

By contrast, a TreeIter is a reference to a specific node on a specific model. It is an abstract data type filled in by the model. One can convert a path to an iterator by calling treeModelGetIter. These iterators are the primary way of accessing a model and are similar to the iterators used by TextBuffer. The model interface defines a set of operations using them for navigating the model. Iterators are expected to always be valid for as long as the model is unchanged (and doesn't emit a signal).

 | GInterface
 | +----TreeModel
 | +--------TypedTreeModel

Returns a set of flags supported by this interface.

The flags supported should not change during the lifecycle of the tree_model.

Retrieves an TreeIter to the first entry.

Returns Nothing if the table is empty.

Turn an abstract TreeIter into a TreePath.

In case the given TreeIter was invalid, an empty list is returned.

This signal is emitted when a row has been deleted.

Note that no iterator is passed to the signal handler, since the row is already deleted.

Implementations of TreeModel must emit row-deleted before removing the node from its internal data structures. This is because models and views which access and monitor this model might have references on the node which need to be released in the rowDeleted handler.

This signal is emitted when the children of a node in the TreeModel have been reordered. See treeModelRowsReordered for more information about the parameters that this signal carries.

Note that this signal is not emitted when rows are reordered by DND, since this is implemented by removing and then reinserting the row.