Data.GI.Gtk.ModelView.TreeModel

The tree interface used by TreeView.

Detail

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 Data.GI.Gtk.ModelView.CustomStore provides the necessary functions to implement the TreeMode interface, it is often sufficient to use the wo implementations that come with gi-gtk-hs, 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 CellRenderer or one of its derivatives, it is possible to state how a row is mapped to the attributes of a renderer using the cellLayoutSetAttributes function. Some widgets do not use 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 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).

Class Hierarchy

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

data ColumnId row ty

The type of a tree column.

Constructors

makeColumnIdInt :: Int32 -> ColumnId row Int32

Create a ColumnId to extract an integer.

makeColumnIdBool :: Int32 -> ColumnId row Bool

Create a ColumnId to extract an Boolean.

makeColumnIdString :: Int32 -> ColumnId row Text

Create a ColumnId to extract an string.

makeColumnIdPixbuf :: Int32 -> ColumnId row Pixbuf

Create a ColumnId to extract an Pixbuf.

invalidColumnId :: ColumnId row ty

The invalid ColumnId. Widgets use this value if no column id has been set.

Methods

columnIdToNumber :: ColumnId row ty -> Int32

Convert a ColumnId to a bare number.

stringToTreePath :: Text -> [Int32]

Convert a comma or colon separated string into a TreePath. Any non-digit characters are assumed to separate indices, thus, the function always is always successful.

treeModelGetValue

Arguments

:: IsTreeModel self

=> self

-> TreeIter

-> ColumnId row ty

column - The column to lookup the value at.

-> IO ty

Read the value of at a specific column and TreeIter.

treeModelGetIter :: (MonadIO m, IsTreeModel model) => model -> TreePath -> m (Maybe TreeIter)

Gets the a TreeIter or Nothing if the path is invalid or empty

Orphan instances

Eq (ColumnId row ty)

Methods

(==) :: ColumnId row ty -> ColumnId row ty -> Bool

(/=) :: ColumnId row ty -> ColumnId row ty -> Bool

Show (ColumnId row ty)

Methods

showsPrec :: Int -> ColumnId row ty -> ShowS

show :: ColumnId row ty -> String

showList :: [ColumnId row ty] -> ShowS