gtk3-0.15.10: Binding to the Gtk+ 3 graphical user interface library

Maintainer | gtk2hs-users@lists.sourceforge.net
Stability | provisional
Portability | portable (depends on GHC)
Safe Haskell | None
Language | Haskell98

Graphics.UI.Gtk.ModelView.TreeModel

Contents

- Detail
- Class Hierarchy
- Types
- Constructors
- Methods
- Signals
- Orphan instances

Description

The tree interface used by `TreeView`.

Synopsis

- data TreeModel
- class GObjectClass o => TreeModelClass o
- castToTreeModel :: GObjectClass obj => obj -> TreeModel
- gTypeTreeModel :: GType
- toTreeModel :: TreeModelClass o => o -> TreeModel
- data TypedTreeModel row
- class TypedTreeModelClass (model :: Type -> Type)
- toTypedTreeModel :: TypedTreeModelClass model => model row -> TypedTreeModel row
- data TreeIter = TreeIter !CInt !Word32 !Word32 !Word32
- type TreePath = [Int]
- data ColumnId row ty
- makeColumnIdInt :: Int -> ColumnId row Int
- makeColumnIdBool :: Int -> ColumnId row Bool
- makeColumnIdString :: GlibString string => Int -> ColumnId row string
- makeColumnIdPixbuf :: Int -> ColumnId row Pixbuf
- invalidColumnId :: ColumnId row ty
- columnIdToNumber :: ColumnId row ty -> Int
- stringToTreePath :: DefaultGlibString -> TreePath
- treeModelGetFlags :: TreeModelClass self => self -> IO [TreeModelFlags]
- treeModelGetIter :: TreeModelClass self => self -> TreePath -> IO (Maybe TreeIter)
- treeModelGetIterFromString :: (TreeModelClass self, GlibString string) => self -> string -> IO (Maybe TreeIter)
- treeModelGetIterFirst :: TreeModelClass self => self -> IO (Maybe TreeIter)
- treeModelGetPath :: TreeModelClass self => self -> TreeIter -> IO TreePath
- treeModelGetValue :: TreeModelClass self => self -> TreeIter -> ColumnId row ty -> IO ty
- 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)
- treeModelForeach :: TreeModelClass self => self -> (TreeIter -> IO Bool) -> IO ()
- treeModelGetStringFromIter :: (TreeModelClass self, GlibString string) => self -> TreeIter -> IO string
- treeModelRefNode :: TreeModelClass self => self -> TreeIter -> IO ()
- treeModelUnrefNode :: TreeModelClass self => self -> TreeIter -> IO ()
- treeModelRowChanged :: TreeModelClass self => self -> TreePath -> TreeIter -> IO ()
- treeModelRowInserted :: TreeModelClass self => self -> TreePath -> TreeIter -> IO ()
- treeModelRowHasChildToggled :: TreeModelClass self => self -> TreePath -> TreeIter -> IO ()
- treeModelRowDeleted :: TreeModelClass self => self -> TreePath -> IO ()
- treeModelRowsReordered :: TreeModelClass self => self -> TreePath -> Maybe TreeIter -> [Int] -> IO ()
- rowChanged :: TreeModelClass self => Signal self (TreePath -> TreeIter -> IO ())
- rowInserted :: TreeModelClass self => Signal self (TreePath -> TreeIter -> IO ())
- rowHasChildToggled :: TreeModelClass self => Signal self (TreePath -> TreeIter -> IO ())
- rowDeleted :: TreeModelClass self => Signal self (TreePath -> IO ())
- rowsReordered :: TreeModelClass self => Signal self (TreePath -> Maybe TreeIter -> [Int] -> IO ())

# 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 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 `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 `CellRenderer`s 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 `String`s or `Int`s). 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 `ColumnId`s 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 `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. 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

# Types

data TreeModel Source #

#### Instances

Instances details

Eq TreeModel Source # |
Instance details Defined in Graphics.UI.Gtk.Types Methods (==) :: TreeModel -> TreeModel -> Bool Source # (/=) :: TreeModel -> TreeModel -> Bool Source #
Ord TreeModel Source # |

Instance details

Defined in Graphics.UI.Gtk.Types

Methods

compare :: TreeModel -> TreeModel -> Ordering Source #

(<) :: TreeModel -> TreeModel -> Bool Source #

(<=) :: TreeModel -> TreeModel -> Bool Source #

(>) :: TreeModel -> TreeModel -> Bool Source #

(>=) :: TreeModel -> TreeModel -> Bool Source #

max :: TreeModel -> TreeModel -> TreeModel Source #

min :: TreeModel -> TreeModel -> TreeModel Source #

GObjectClass TreeModel Source # |
Instance details Defined in Graphics.UI.Gtk.Types Methods toGObject :: TreeModel -> GObject Source # unsafeCastGObject :: GObject -> TreeModel Source #
TreeModelClass TreeModel Source # |
Instance details Defined in Graphics.UI.Gtk.Types

class GObjectClass o => TreeModelClass o Source #

#### Instances

Instances details

TreeModelClass TreeModel Source # |
Instance details Defined in Graphics.UI.Gtk.Types
TreeModelClass (ListStore a) Source # |
Instance details Defined in Graphics.UI.Gtk.ModelView.ListStore
TreeModelClass (TreeStore a) Source # |
Instance details Defined in Graphics.UI.Gtk.ModelView.TreeStore
TreeModelClass (TypedTreeModelFilter a) Source # |
Instance details Defined in Graphics.UI.Gtk.ModelView.TreeModelFilter
TreeModelClass (TypedTreeModelSort a) Source # |
Instance details Defined in Graphics.UI.Gtk.ModelView.TreeModelSort
TreeModelClass (CustomStore private row) Source # |
Instance details Defined in Graphics.UI.Gtk.ModelView.CustomStore

castToTreeModel :: GObjectClass obj => obj -> TreeModel Source #

gTypeTreeModel :: GType Source #

toTreeModel :: TreeModelClass o => o -> TreeModel Source #

data TypedTreeModel row Source #

#### Instances

Instances details

TypedTreeModelClass TypedTreeModel Source # |
Instance details Defined in Graphics.UI.Gtk.ModelView.Types Methods dummy :: TypedTreeModel a -> a

class TypedTreeModelClass (model :: Type -> Type) Source #

#### Instances

Instances details

TypedTreeModelClass ListStore Source # |
Instance details Defined in Graphics.UI.Gtk.ModelView.ListStore Methods dummy :: ListStore a -> a
TypedTreeModelClass TreeStore Source # |
Instance details Defined in Graphics.UI.Gtk.ModelView.TreeStore Methods dummy :: TreeStore a -> a
TypedTreeModelClass TypedTreeModel Source # |
Instance details Defined in Graphics.UI.Gtk.ModelView.Types Methods dummy :: TypedTreeModel a -> a
TypedTreeModelClass TypedTreeModelFilter Source # |
Instance details Defined in Graphics.UI.Gtk.ModelView.Types Methods dummy :: TypedTreeModelFilter a -> a
TypedTreeModelClass TypedTreeModelSort Source # |
Instance details Defined in Graphics.UI.Gtk.ModelView.Types Methods dummy :: TypedTreeModelSort a -> a

toTypedTreeModel :: TypedTreeModelClass model => model row -> TypedTreeModel row Source #

data TreeIter Source #

Tree Iterator: a pointer to an entry in a `TreeModel`. The constructor of this structure is public for the sake of creating custom tree models. The first value is a time stamp that is handled by the functions that interface with Gtk. The time stamps are used to print warnings if programmers use an iter to a model that has changed meanwhile. The other three fields are used by the custom model implementation to implement an indexing scheme. The precise use of the three words is therefore implementation specific. See also `TreePath`.

Constructors

TreeIter !CInt !Word32 !Word32 !Word32 |

#### Instances

Instances details

Storable TreeIter Source # |

Instance details

Defined in Graphics.UI.Gtk.ModelView.Types

Methods

sizeOf :: TreeIter -> Int Source #

alignment :: TreeIter -> Int Source #

peekElemOff :: Ptr TreeIter -> Int -> IO TreeIter Source #

pokeElemOff :: Ptr TreeIter -> Int -> TreeIter -> IO () Source #

peekByteOff :: Ptr b -> Int -> IO TreeIter Source #

pokeByteOff :: Ptr b -> Int -> TreeIter -> IO () Source #

peek :: Ptr TreeIter -> IO TreeIter Source #

poke :: Ptr TreeIter -> TreeIter -> IO () Source #

Show TreeIter Source # |
Instance details Defined in Graphics.UI.Gtk.ModelView.Types Methods showsPrec :: Int -> TreeIter -> ShowS Source # show :: TreeIter -> String Source # showList :: [TreeIter] -> ShowS Source #

type TreePath = [Int] Source #

TreePath : a list of indices to specify a subtree or node in a `TreeModel`. The node that correspond to a given `TreePath` might change if nodes are removed or added and a `TreePath` may refer to a different or even non-existent node after a modification of the model. In contrast, a `TreeIter` is a more compact representation of a `TreePath` which becomes invalid after each modification of the underlying model. An intelligent index that is adjusted with each update of the model to point to the same node (whenever possible) is `TreeRowReference`.

data ColumnId row ty Source #

The type of a tree column.

#### Instances

Instances details

Show (ColumnId row ty) Source # |
Instance details Defined in Graphics.UI.Gtk.ModelView.TreeModel Methods showsPrec :: Int -> ColumnId row ty -> ShowS Source # show :: ColumnId row ty -> String Source # showList :: [ColumnId row ty] -> ShowS Source #
Eq (ColumnId row ty) Source # |
Instance details Defined in Graphics.UI.Gtk.ModelView.TreeModel Methods (==) :: ColumnId row ty -> ColumnId row ty -> Bool Source # (/=) :: ColumnId row ty -> ColumnId row ty -> Bool Source #

# Constructors

makeColumnIdInt :: Int -> ColumnId row Int Source #

Create a `ColumnId` to extract an integer.

makeColumnIdBool :: Int -> ColumnId row Bool Source #

Create a `ColumnId` to extract an Boolean.

makeColumnIdString :: GlibString string => Int -> ColumnId row string Source #

Create a `ColumnId` to extract an string.

makeColumnIdPixbuf :: Int -> ColumnId row Pixbuf Source #

Create a `ColumnId` to extract an `Pixbuf`.

invalidColumnId :: ColumnId row ty Source #

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

# Methods

columnIdToNumber :: ColumnId row ty -> Int Source #

Convert a `ColumnId` to a bare number.

stringToTreePath :: DefaultGlibString -> TreePath Source #

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.

treeModelGetFlags :: TreeModelClass self => self -> IO [TreeModelFlags] Source #

Returns a set of flags supported by this interface.

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

treeModelGetIter Source #

Arguments

:: 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 Source #

Arguments

:: (TreeModelClass self, GlibString string) |
=> 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.

treeModelGetIterFirst :: TreeModelClass self => self -> IO (Maybe TreeIter) Source #

Retrieves an `TreeIter` to the first entry.

Returns `Nothing` if the table is empty.

treeModelGetPath :: TreeModelClass self => self -> TreeIter -> IO TreePath Source #

Turn an abstract `TreeIter` into a `TreePath`.

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

treeModelGetValue Source #

Arguments

:: TreeModelClass 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`.

treeModelIterNext :: TreeModelClass self => self -> TreeIter -> IO (Maybe TreeIter) Source #

Retrieve an iterator to the node following it at the current level. If there is no next node, `Nothing` is returned.

treeModelIterChildren Source #

Arguments

:: TreeModelClass self |
=> self |
-> TreeIter | `parent` - a pointer to the parent
-> IO (Maybe TreeIter) |

Retrieve an iterator to the first child of `parent`. If `parent` has no children, `Nothing`.

treeModelIterHasChild Source #

Arguments

:: 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 Source #

Arguments

:: 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 Source #

Arguments

:: 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 of `parent`, counting from zero. If `n` is too big or `parent` has no children, `Nothing` is returned. If `Nothing` is specified for the `parent` argument, the function will return the `n`th root node.

treeModelIterParent :: TreeModelClass self => self -> TreeIter -> IO (Maybe TreeIter) Source #

Retrieve the parent of this iterator.

treeModelForeach :: TreeModelClass self => self -> (TreeIter -> IO Bool) -> IO () Source #

Maps a function over each node in model in a depth-first fashion. If it returns `True`, then the tree ceases to be walked, and `treeModelForeach` returns.

treeModelGetStringFromIter Source #

Arguments

:: (TreeModelClass self, GlibString string) |
=> self |
-> TreeIter | `iter` - An `TreeIter`.
-> IO string | the returned string representation

Generates a string representation of the iter. This string is a ':' separated list of numbers. For example, "4:10:0:3" would be an acceptable return value for this string.

- Available since Gtk+ version 2.2

treeModelRefNode Source #

Arguments

:: TreeModelClass self |
=> self |
-> TreeIter | `iter` - The `TreeIter`.
-> IO () |

Lets the tree ref the node. This is an optional method for models to implement. To be more specific, models may ignore this call as it exists primarily for performance reasons.

This function is primarily meant as a way for views to let caching model know when nodes are being displayed (and hence, whether or not to cache that node.) For example, a file-system based model would not want to keep the entire file-hierarchy in memory, just the sections that are currently being displayed by every current view.

A model should be expected to be able to get an iter independent of its reffed state.

treeModelUnrefNode Source #

Arguments

:: TreeModelClass self |
=> self |
-> TreeIter | `iter` - The `TreeIter`.
-> IO () |

Lets the tree unref the node. This is an optional method for models to implement. To be more specific, models may ignore this call as it exists primarily for performance reasons.

For more information on what this means, see `treeModelRefNode`. Please note that nodes that are deleted are not unreffed.

treeModelRowChanged Source #

Arguments

:: TreeModelClass self |
=> self |
-> TreePath | `path` - A `TreePath` pointing to the changed row
-> TreeIter | `iter` - A valid `TreeIter` pointing to the changed row
-> IO () |

Emits the `rowChanged` signal on the model.

- This function is only necessary to implement a custom tree model. When using `ListStore` or `TreeStore`, this function is called automatically.

treeModelRowInserted Source #

Arguments

:: TreeModelClass self |
=> self |
-> TreePath | `path` - A `TreePath` pointing to the inserted row
-> TreeIter | `iter` - A valid `TreeIter` pointing to the inserted row
-> IO () |

Emits the `rowInserted` signal on the model.

- This function is only necessary to implement a custom tree model. When using `ListStore` or `TreeStore`, this function is called automatically.

treeModelRowHasChildToggled Source #

Arguments

:: TreeModelClass self |
=> self |
-> TreePath | `path` - A `TreePath` pointing to the changed row
-> TreeIter | `iter` - A valid `TreeIter` pointing to the changed row
-> IO () |

Emits the `rowHasChildToggled` signal on the model. This should be called by models after the child state of a node changes.

- This function is only necessary to implement a custom tree model. When using `ListStore` or `TreeStore`, this function is called automatically.

treeModelRowDeleted Source #

Arguments

:: TreeModelClass self |
=> self |
-> TreePath | `path` - A `TreePath` pointing to the previous location of the deleted row.
-> IO () |

Emits the `rowDeleted` signal on the model. This should be called by models after a row has been removed. The location pointed to by `path` should be the location that the row previously was at. It may not be a valid location anymore.

- This function is only necessary to implement a custom tree model. When using `ListStore` or `TreeStore`, this function is called automatically.

treeModelRowsReordered Source #

Arguments

:: TreeModelClass self |
=> self |
-> TreePath | `path` - A `TreePath` pointing to the tree node whose children have been reordered
-> Maybe TreeIter | `iter` - A valid `TreeIter` pointing to the node whose children have been reordered, or `Nothing` if `path` is `[]`.
-> [Int] | `newOrder` - a list of integers giving the previous position of each node at this hierarchy level.
-> IO () |

Emits the `rowsReordered` signal on the model. This should be called by models when their rows have been reordered. The length of `newOrder` must be equal to the value returned by `treeModelIterNChildren self iter`.

- This function is only necessary to implement a custom tree model. When using `ListStore` or `TreeStore`, this function is called automatically.

# Signals

rowChanged :: TreeModelClass self => Signal self (TreePath -> TreeIter -> IO ()) Source #

This signal is emitted when a row in the model has changed.

rowInserted :: TreeModelClass self => Signal self (TreePath -> TreeIter -> IO ()) Source #

This signal is emitted when a new row has been inserted in the model.

rowHasChildToggled :: TreeModelClass self => Signal self (TreePath -> TreeIter -> IO ()) Source #

This signal is emitted when a row has gotten the first child row or lost its last child row.

rowDeleted :: TreeModelClass self => Signal self (TreePath -> IO ()) Source #

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.

rowsReordered :: TreeModelClass self => Signal self (TreePath -> Maybe TreeIter -> [Int] -> IO ()) Source #

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.

# Orphan instances

Show (ColumnId row ty) Source # |
Instance details Methods showsPrec :: Int -> ColumnId row ty -> ShowS Source # show :: ColumnId row ty -> String Source # showList :: [ColumnId row ty] -> ShowS Source #
Eq (ColumnId row ty) Source # |
Instance details Methods (==) :: ColumnId row ty -> ColumnId row ty -> Bool Source # (/=) :: ColumnId row ty -> ColumnId row ty -> Bool Source #