| Gtk2Hs | Contents | Index

Graphics.UI.Gtk.TreeList.TreeModel

Portability | portable (depends on GHC)
Stability | provisional
Maintainer | gtk2hs-users@lists.sourceforge.net

Contents

Detail
Class Hierarchy
Types
Methods

Description

The tree interface used by `TreeView`

- This module and all other modules in Graphics.UI.Gtk.TreeList are deprecated. Please use the modules in Graphics.UI.Gtk.ModelView.

Synopsis

data TreeModel
class GObjectClass o => TreeModelClass o
castToTreeModel :: GObjectClass obj => obj -> TreeModel
toTreeModel :: TreeModelClass o => o -> TreeModel

data TreeModelFlags

= TreeModelItersPersist
| TreeModelListOnly

type TreePath = [Int]
data TreeIter
treeModelGetFlags :: TreeModelClass self => self -> IO [TreeModelFlags]
treeModelGetNColumns :: TreeModelClass self => self -> IO Int
treeModelGetColumnType :: TreeModelClass self => self -> Int -> IO TMType
treeModelGetValue :: TreeModelClass self => self -> TreeIter -> Int -> IO GenericValue
treeModelGetIter :: TreeModelClass self => self -> TreePath -> IO (Maybe TreeIter)
treeModelGetIterFromString :: TreeModelClass self => self -> String -> IO (Maybe TreeIter)
gtk_tree_model_get_iter_from_string :: Ptr TreeModel -> Ptr TreeIter -> Ptr CChar -> IO CInt
treeModelGetIterFirst :: TreeModelClass self => self -> IO (Maybe TreeIter)
treeModelGetPath :: TreeModelClass self => self -> TreeIter -> IO TreePath
treeModelIterNext :: TreeModelClass self => self -> TreeIter -> IO (Maybe TreeIter)
treeModelIterChildren :: TreeModelClass self => self -> TreeIter -> IO (Maybe TreeIter)
treeModelIterHasChild :: TreeModelClass self => self -> TreeIter -> IO Bool
treeModelIterNChildren :: TreeModelClass self => self -> Maybe TreeIter -> IO Int
treeModelIterNthChild :: TreeModelClass self => self -> Maybe TreeIter -> Int -> IO (Maybe TreeIter)
treeModelIterParent :: TreeModelClass self => self -> TreeIter -> IO (Maybe TreeIter)

Detail

The `TreeModel` interface defines a generic storage object for use by the `TreeView` widget. It is purely abstract, concrete implementations that store data for a list or tree are `ListStore` and `TreeStore`.

The model is represented as a hierarchical tree of strongly-typed, columned data. In other words, the model can be seen as a tree where every node has different values depending on which column is being queried. The type of data found in a column can be arbitrary, ranging from basic types like `String`s or `Int` to user specific types. The types are homogeneous per column across all nodes. 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 pushes 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, sorting, and storing data trivial.

Models are accessed on a node/column level of granularity. One can query for the value of a model at a certain node and a certain column on that node. There are two structures 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 just a list of `Int`s 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.

The lifecycle of an iterator can be a little confusing at first. Iterators are expected to always be valid for as long as the model is unchanged (and doesn't emit a signal). Additionally, the `TreeStore` and `ListStore` models guarantee that an iterator is valid for as long as the node it refers to is valid. Although generally uninteresting, as one always has to allow for the case where iterators do not persist beyond a signal, some very important performance enhancements were made in the sort model. As a result, the `TreeModelItersPersist` flag was added to indicate this behavior.

Class Hierarchy

     |  GInterface
     |   +----TreeModel

Types
data TreeModel

Instances

GObjectClass TreeModel
TreeModelClass TreeModel

class GObjectClass o => TreeModelClass o

Instances

TreeModelClass TreeModelSort
TreeModelClass ListStore
TreeModelClass TreeStore
TreeModelClass TreeModel
TreeModelClass (TypedTreeModelSort a)
TreeModelClass (ListStore a)
TreeModelClass (TreeStore a)
TreeModelClass (CustomStore private row)

castToTreeModel :: GObjectClass obj => obj -> TreeModel
toTreeModel :: TreeModelClass o => o -> TreeModel
data TreeModelFlags

These flags indicate various properties of a `TreeModel`.

- If a model has TreeModelItersPersist set, iterators remain valid after a TreeModel signal was emitted.
- The TreeModelListOnly flag is set if the rows are arranged in a simple flat list. This is set in the ListStore implementation.

Constructors

TreeModelItersPersist |
TreeModelListOnly |

Instances

Bounded TreeModelFlags
Enum TreeModelFlags
Flags TreeModelFlags

type TreePath = [Int]
TreePath : a list of indices to specify a subtree or node in the hierarchical TreeStore database.
data TreeIter

Tree Iterator: a pointer to an entry in a Graphics.UI.Gtk.ModelView.TreeModel.
Instances

Show TreeIter
Storable TreeIter

Methods
treeModelGetFlags :: TreeModelClass self => self -> IO [TreeModelFlags]
Returns a set of flags supported by this interface. The flags supported should not change during the lifecycle of the tree_model.
treeModelGetNColumns

:: TreeModelClass self |
=> self |
-> IO Int | returns The number of columns.
Returns the number of columns supported by the tree model.

treeModelGetColumnType

:: TreeModelClass self |
=> self |
-> Int | `index` - The column index.
-> IO TMType |
Returns the type of the column.

treeModelGetValue

:: TreeModelClass self |
=> self |
-> TreeIter |
-> Int | `column` - The column to lookup the value at.
-> IO GenericValue |
Read the value of at a specific column and `TreeIter`.

treeModelGetIter

:: TreeModelClass self |
=> self |
-> TreePath | `path` - The `TreePath`.
-> IO (Maybe TreeIter) |
Turn a `TreePath` into a `TreeIter`. Returns `Nothing` if the given `TreePath` was invalid. The empty list is always invalid. The root node of a tree can be accessed by passing `[0]` as `path`.

treeModelGetIterFromString

:: TreeModelClass self |
=> self |
-> String | `pathString` - A string representation of a `TreePath`.
-> IO (Maybe TreeIter) |

Turn a `String` into a `TreeIter`.

- Returns `Nothing` if the string is not a colon separated list of numbers that references a valid node.

gtk_tree_model_get_iter_from_string :: Ptr TreeModel -> Ptr TreeIter -> Ptr CChar -> IO CInt
treeModelGetIterFirst :: TreeModelClass self => self -> IO (Maybe TreeIter)
Retrieves an `TreeIter` to the first entry. Returns `Nothing` if the table is empty.
treeModelGetPath :: TreeModelClass self => self -> TreeIter -> IO TreePath
Turn an abstract `TreeIter` into a `TreePath`. In case the given `TreeIter` was invalid, an empty list is returned.
treeModelIterNext :: TreeModelClass self => self -> TreeIter -> IO (Maybe TreeIter)
Retrieve an iterator to the next child.
treeModelIterChildren :: TreeModelClass self => self -> TreeIter -> IO (Maybe TreeIter)
Retrieve an iterator to the first child.
treeModelIterHasChild

:: TreeModelClass self |
=> self |
-> TreeIter | `iter` - The `TreeIter` to test for children.
-> IO Bool | returns `True` if `iter` has children.
Returns `True` if `iter` has children, `False` otherwise.

treeModelIterNChildren

:: TreeModelClass self |
=> self |
-> Maybe TreeIter | `iter` - The `TreeIter`, or `Nothing`.
-> IO Int | returns The number of children of `iter`.
Returns the number of children that `iter` has. As a special case, if `iter` is `Nothing`, then the number of toplevel nodes is returned.

treeModelIterNthChild

:: TreeModelClass self |
=> self |
-> Maybe TreeIter | `parent` - The `TreeIter` to get the child from, or `Nothing`.
-> Int | `n` - Then index of the desired child.
-> IO (Maybe TreeIter) |
Retrieve the `n`th child. If `Nothing` is specified for the `self` argument, the function will work on toplevel elements.

treeModelIterParent :: TreeModelClass self => self -> TreeIter -> IO (Maybe TreeIter)
Retrieve the parent of this iterator.
Produced by Haddock version 2.4.2