gtk.TreeStore
Prev | The gtk Class Reference | Next

## gtk.TreeStore

gtk.TreeStore — a model for tree widgets with columns

## Synopsis

    class gtk.TreeStore(gobject.GObject, gtk.TreeModel, gtk.TreeDragSource, gtk.TreeDragDest, gtk.TreeSortable):
        gtk.TreeStore(...)
        def set_value(iter, column, value)
        def set(iter, ...)
        def remove(iter)
        def insert(parent, position, row=None)
        def insert_before(parent, sibling, row=None)
        def insert_after(parent, sibling, row=None)
        def prepend(parent, row=None)
        def append(parent, row=None)
        def is_ancestor(iter, descendant)
        def iter_depth(iter)
        def clear()
        def iter_is_valid(iter)
        def reorder(parent, new_order)
        def swap(a, b)
        def move_after(iter, position)
        def move_before(iter, position)

## Ancestry

    +-- gobject.GObject
      +-- gtk.TreeStore (implements gtk.TreeModel, gtk.TreeDragSource, gtk.TreeDragDest, gtk.TreeSortable)

## gtk.TreeStore Signal Prototypes

gobject.GObject Signal Prototypes

gtk.TreeSortable Signal Prototypes

gtk.TreeModel Signal Prototypes

## Description

A `gtk.TreeStore` is a model for multi-columned tree widgets. A `gtk.TreeStore` is a subclass of gobject.GObject and implements the `gtk.TreeModel`, `gtk.TreeDragSource`, `gtk.TreeDragDest` and `gtk.TreeSortable` interfaces.

The `gtk.TreeStore` objects support the Python mapping and iterator protocols. See the `gtk.TreeModel` Description and the PyGTK tutorial for more information.

## Constructor

        gtk.TreeStore(...)

`...` : | one or more column types
Returns : | a new `gtk.TreeStore`

Creates a new tree store as with one or more columns each of the types passed in. As an example:

      gtk.TreeStore(gobject.TYPE_INT, gobject.TYPE_STRING, gtk.gdk.Pixbuf)

will create a new `gtk.TreeStore` with three columns, of type int, string and `gtk.gdk.Pixbuf` respectively.

## Methods

### gtk.TreeStore.set_value

        def set_value(iter, column, value)

`iter` : | a `gtk.TreeIter` for the row being modified
`column` : | the column number to modify
`value` : | a new value for the cell

The `set_value`() method sets the data in the cell specified by `iter` and `column` to the value specified by `value`. The type of `value` must be convertible to the type of the column.

### gtk.TreeStore.set

        def set(iter, ...)

`iter` : | a `gtk.TreeIter` for the row being modified
`...` : | one or more column ID-value pairs

The `set`() method sets the value of one or more cells in the row referenced by `iter`. The argument list following `iter` should contain pairs of integer column numbers followed by the value to be set. For example, to set column 0 with type `gobject.TYPE_STRING` to "Foo", you would write:

      store.set(iter, 0, "Foo")

### gtk.TreeStore.remove

        def remove(iter)

`iter` : | a `gtk.TreeIter`
Returns : | `None` in PyGTK 2.0. Returns `True` in PyGTK 2.2 and above if `iter` is still valid.

The `remove`() method removes the row pointed to by `iter` from the treestore. After being removed, `iter` is set to the next valid row at that level, or invalidated if it previously pointed to the last one.

### gtk.TreeStore.insert

        def insert(parent, position, row=None)

`parent` : | a `gtk.TreeIter`, or `None`
`position` : | the position to insert the new row
`row` : | an optional list or tuple containing column values (in order) to set on the row or `None`
Returns : | a `gtk.TreeIter` pointing to the new row

The `insert`() method inserts a new row at `position`. If `parent` is not `None`, then the row will be made a child of `parent`. Otherwise, the row will be created at the toplevel. If `position` is larger than the number of rows at that level, then the new row will be inserted to the end of the list. This method returns a `gtk.TreeIter` pointing at the new row. If `row` is not `None` it must be a tuple or list containing ordered column values that are used to set values in the columns of the row.

### gtk.TreeStore.insert_before

        def insert_before(parent, sibling, row=None)

`parent` : | a `gtk.TreeIter`, or `None`
`sibling` : | a `gtk.TreeIter`, or `None`
`row` : | an optional list or tuple containing ordered column values to set on the row or `None`
Returns : | a `gtk.TreeIter` pointing to the new row

The `insert_before`() method inserts a new row before the row pointed to by `sibling`. If `sibling` is `None`, then the row will be appended to the children of the row pointed to by `parent`. If `parent` and `sibling` are `None`, the row will be appended to the toplevel. If both `sibling` and `parent` are set, then `parent` must be the parent of `sibling`. When `sibling` is set, `parent` is optional. This method returns a `gtk.TreeIter` pointing at the new row. If `row` is not `None` it must be a tuple or list containing ordered column values that are used to set values in the columns of the row.

### gtk.TreeStore.insert_after

        def insert_after(parent, sibling, row=None)

`parent` : | a `gtk.TreeIter`, or `None`
`sibling` : | a `gtk.TreeIter`, or `None`
`row` : | a tuple or list containing ordered column values to be set in the new row
Returns : | a `gtk.TreeIter` pointing to the new row

The `insert_after`() method inserts a new row after the row pointed to by `sibling`. If `sibling` is `None`, then the row will be prepended to the beginning of the children of `parent`. If `parent` and `sibling` are `None`, then the row will be prepended to the toplevel. If both `sibling` and `parent` are set, `parent` must be the parent of `sibling`. When `sibling` is set, `parent` is optional. This method returns a `gtk.TreeIter` pointing at the new row. If `row` is not `None` it must be a tuple or list containing ordered column values that are used to set values in the columns of the row.

### gtk.TreeStore.prepend

        def prepend(parent, row=None)

`parent` : | a `gtk.TreeIter`, or `None`
`row` : | a tuple or list containing ordered column values to be set in the new row
Returns : | a `gtk.TreeIter` pointing to the new row

The `prepend`() method prepends a new row to the treestore. If `parent` is not `None`, the new row will be prepended before the first child of `parent`, otherwise it will prepend a row to the top level. This method returns a `gtk.TreeIter` pointing at the new row. If `row` is not `None` it must be a tuple or list containing ordered column values that are used to set values in the columns of the row.

### gtk.TreeStore.append

        def append(parent, row=None)

`parent` : | a `gtk.TreeIter`, or `None`
`row` : | a tuple or list containing ordered column values to be set in the new row
Returns : | a `gtk.TreeIter` pointing to the new row

The `append`() method appends a new row to the treestore. If `parent` is not `None`, the new row will be prepended after the last child of `parent`, otherwise it will append a row to the top level. This method returns a `gtk.TreeIter` pointing at the new row. If `row` is not `None` it must be a tuple or list containing ordered column values that are used to set values in the columns of the row.

### gtk.TreeStore.is_ancestor

        def is_ancestor(iter, descendant)

`iter` : | a `gtk.TreeIter`
`descendant` : | a `gtk.TreeIter`
Returns : | `True`, if `iter` is an ancestor of `descendant`

The `is_ancestor`() method returns `True` if the row pointed to by `iter` is an ancestor of the row pointed to by `descendant`. That is, `iter` is the parent (or grandparent or great-grandparent) of `descendant`.

### gtk.TreeStore.iter_depth

        def iter_depth(iter)

`iter` : | a `gtk.TreeIter`
Returns : | the depth of `iter`

The `iter_depth`() method returns the depth of the row pointed to by `iter`. This will be 0 for anything on the root level, 1 for anything down a level, etc.

### gtk.TreeStore.clear

        def clear()

The `clear`() method removes all rows from the treestore.

### gtk.TreeStore.iter_is_valid

        def iter_is_valid(iter)

`iter` : | a `gtk.TreeIter`.
Returns : | `True` if `iter` is valid for the tree store,

### Note

This method is available in PyGTK 2.2 and above.

The `iter_is_valid`() method returns `True` if `iter` is a valid `gtk.TreeIter` for the tree store.

### Warning

This function is slow. Only use it for debugging and/or testing purposes.

### gtk.TreeStore.reorder

        def reorder(parent, new_order)

`parent` : | a `gtk.TreeIter`.
`new_order` : | a list of integers mapping the new position of each child to its old position before the re-ordering, i.e. `new_order``[newpos] = oldpos`.

### Note

This method is available in PyGTK 2.2 and above.

The `reorder`() method reorders the children of the tree store node pointed to by `parent` to match the order of the list of row numbers contained in `new_order`. Note that this method only works with unsorted stores.

### gtk.TreeStore.swap

        def swap(a, b)

`a` : | a `gtk.TreeIter`.
`b` : | another `gtk.TreeIter`.

### Note

This method is available in PyGTK 2.2 and above.

The `swap`() method swaps the tree store nodes pointed to by `a` and `b` in the same level of the tree store. Note that this method only works with unsorted stores.

### gtk.TreeStore.move_after

        def move_after(iter, position)

`iter` : | a `gtk.TreeIter`.
`position` : | a second `gtk.TreeIter` or `None`.

### Note

This method is available in PyGTK 2.2 and above.

The `move_after`() method moves the tree store node specified by `iter` to the position after the node specified by `position`. `iter` and `position` should be in the same level. Note that this method only works with unsorted stores. If `position` is `None`, `iter` will be moved to the start of the level.

### gtk.TreeStore.move_before

        def move_before(iter, position)

`iter` : | a `gtk.TreeIter`.
`position` : | a `gtk.TreeIter` or `None`.

### Note

This method is available in PyGTK 2.2 and above.

The move_before() method moves the tree store node pointed to by `iter` to the position before the node specified by `position`. `iter` and `position` should be in the same level. Note that this method only works with unsorted stores. If `position` is `None`, `iter` will be moved to the end of the level.

Prev | Up | Next
gtk.TreeSortable | Home | gtk.TreeView