gtk.ListStore
Prev | The gtk Class Reference | Next

## gtk.ListStore

gtk.ListStore — a list model to use with a `gtk.TreeView`

## Synopsis

    class gtk.ListStore(gobject.GObject, gtk.TreeModel, gtk.TreeDragSource, gtk.TreeDragDest, gtk.TreeSortable):
        gtk.ListStore(column_type, ...)
        def set_column_types(type, ...)
        def set_value(iter, column, value)
        def set(iter, column_num, value, ...)
        def remove(iter)
        def insert(position, row=None)
        def insert_before(sibling, row=None)
        def insert_after(sibling, row=None)
        def prepend(row=None)
        def append(row=None)
        def clear()
        def iter_is_valid(iter)
        def reorder(new_order)
        def swap(a, b)
        def move_after(iter, position)
        def move_before(iter, position)

## Ancestry

    +-- gobject.GObject
      +-- gtk.ListStore

## Implemented Interfaces

`gtk.Bin` implements `gtk.Buildable` gtk.TreeModel gtk.TreeDragSource gtk.TreeDragDest gtk.TreeSortable

## gtk.ListStore Signal Prototypes

gobject.GObject Signal Prototypes

gtk.TreeModel Signal Prototypes

gtk.TreeSortable Signal Prototypes

## Description

The `gtk.ListStore` object is a list model for use with a `gtk.TreeView` widget. It implements the `gtk.TreeModel` interface, the `gtk.TreeSortable` and the tree drag and drop interfaces.

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

## Constructor

        gtk.ListStore(column_type, ...)

`column_type` : | the column type of the first column
`...` : | optional types for succeeding columns
Returns : | a new `gtk.ListStore`

Creates a new list store as with one or more columns with the type specified by the arguments passed to the constructor. For example, `gtk.ListStore(gobject.TYPE_INT, gobject.TYPE_STRING, gtk.gdk.Pixbuf);` will create a new `gtk.ListStore` with three columns, of type int, string and `gtk.gdk.Pixbuf` respectively. The built-in `GObject` types are:

- `gobject.TYPE_BOOLEAN`
- `gobject.TYPE_BOXED`
- `gobject.TYPE_CHAR`
- `gobject.TYPE_DOUBLE`
- `gobject.TYPE_ENUM`
- `gobject.TYPE_FLAGS`
- `gobject.TYPE_FLOAT`
- `gobject.TYPE_INT`
- `gobject.TYPE_INT64`
- `gobject.TYPE_INTERFACE`
- `gobject.TYPE_INVALID`
- `gobject.TYPE_LONG`
- `gobject.TYPE_NONE`
- `gobject.TYPE_OBJECT`
- `gobject.TYPE_PARAM`
- `gobject.TYPE_POINTER`
- `gobject.TYPE_PYOBJECT`
- `gobject.TYPE_STRING`
- `gobject.TYPE_UCHAR`
- `gobject.TYPE_UINT`
- `gobject.TYPE_UINT64`
- `gobject.TYPE_ULONG`

The column types can be any `GObject` type including those that are PyGTK objects or application defined objects that are subclassed from the `GObject` class.

## Methods

### gtk.ListStore.set_column_types

        def set_column_types(type, ...)

`type` : | the type of the first column
`...` : | zero or more type specifications

### Note

This method is available in PyGTK 2.2 and above.

The `set_column_types`() method sets the liststore columns to the types specified by `type` and any additional type parameters. This method is meant primarily for classes that inherit from `gtk.ListStore`, and should only be used when constructing a new `gtk.ListStore`. It will not function after a row has been added, or a method on the `gtk.TreeModel` interface is called.

### gtk.ListStore.set_value

        def set_value(iter, column, value)

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

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

### gtk.ListStore.set

        def set(iter, column_num, value, ...)

`iter` : | A valid `gtk.TreeIter` for the row being modified
`column_num` : | the number of the column to modify
`value` : | the new cell value
`...` : | additional optional sets of column number - value pairs

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

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

### gtk.ListStore.remove

        def remove(iter)

`iter` : | A valid `gtk.TreeIter` for the row
Returns : | `True` if `iter` is still valid.

The `remove`() method removes the row specified by `iter` from the list store and returns True if `iter` is still valid. After being removed, `iter` is set to be the next valid row, or is invalidated if it pointed to the last row.

### Note

Prior to PyGTK 2.4 this method returned a new `gtk.TreeIter` that is a copy of `iter`.

### gtk.ListStore.insert

        def insert(position, row=None)

`position` : | the integer position to insert the new row
`row` : | an optional list or tuple containing ordered column values to set on the row or `None`
Returns : | A `gtk.TreeIter` pointing at the new row

The `insert`() method creates a new row at the location specified by `position`. If `position` is larger than the number of rows on the list, then the new row will be appended to the list. The row will be empty if `row` is not specified or is `None`. If `row` is specified it must contain a list or tuple of ordered column values (e.g. [`gobject.TYPE_STRING`, `gobject.TYPE_INT`]) that are used to set the values in the cells of the new row. Alternatively, the application can fill in row cell values using the `set`() or `set_value`() methods.

### gtk.ListStore.insert_before

        def insert_before(sibling, row=None)

`sibling` : | A valid `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 at the new row

The `insert_before`() method inserts a new row before the row specified by the `gtk.TreeIter` `sibling`. The row will be empty if `row` is not specified or is `None`. If `row` is specified it must contain a list or tuple of ordered column values (e.g. [`gobject.TYPE_STRING`, `gobject.TYPE_INT`]) that are used to set the values in the cells of the new row. Alternatively, the application can fill in row cell values using the `set`() or `set_value`() methods.

In PyGTK 2.4, if `sibling` is `None` the row will be appended to the liststore.

### gtk.ListStore.insert_after

        def insert_after(sibling, row=None)

`sibling` : | A valid `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 at the new row

The `insert_after`() method inserts a new row after the row specified by the `gtk.TreeIter` `sibling`. The row will be empty if `row` is not specified or is `None`. If `row` is specified it must contain a list or tuple of ordered column values (e.g. [`gobject.TYPE_STRING`, `gobject.TYPE_INT`]) that are used to set the values in the cells of the new row. Alternatively, the application can fill in row cell values using the `set`() or `set_value`() methods.

In PyGTK 2.4, if `sibling` is `None` the row will be prepended to the liststore.

### gtk.ListStore.prepend

        def prepend(row=None)

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

The `prepend`() method prepends a new row to the liststore. The row will be empty if `row` is not specified or is `None`. If `row` is specified it must contain a list or tuple of ordered column values (e.g. [`gobject.TYPE_STRING`, `gobject.TYPE_INT`]) that are used to set the values in the cells of the new row. Alternatively, the application can fill in row cell values using the `set`() or `set_value`() methods.

### gtk.ListStore.append

        def append(row=None)

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

The `append`() method appends a new row to the liststore. The row will be empty if `row` is not specified or is `None`. If `row` is specified it must contain a list or tuple of ordered column values (e.g. [`gobject.TYPE_STRING`, `gobject.TYPE_INT`]) that are used to set the values in the cells of the new row. Alternatively, the application can fill in row cell values using the `set`() or `set_value`() methods.

### gtk.ListStore.clear

        def clear()

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

### gtk.ListStore.iter_is_valid

        def iter_is_valid(iter)

`iter` : | A `gtk.TreeIter`.
Returns : | `True` if the iter is valid, `False` if the iter is invalid.

### Note

This method is available in PyGTK 2.2 and above.

### Warning

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

The `iter_is_valid`() method checks if the `gtk.TreeIter` specified by `iter` is a valid iter for this `gtk.ListStore`.

### gtk.ListStore.reorder

        def reorder(new_order)

`new_order` : | a list of integers. The `gtk.ListStore` nodes will be rearranged so that the `gtk.ListStore` node that is at position index `new_order``[i]` will be located at position index `i`.

### Note

This method is available in PyGTK 2.2 and above.

The `reorder`() method reorders the `gtk.ListStore` items to follow the order indicated by `new_order`. The `gtk.ListStore` nodes will be rearranged so that the `gtk.ListStore` node that is at position index `new_order``[i]` will be located at position index `i`. Note that this method only works with unsorted stores.

### gtk.ListStore.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 liststore rows specified by the `gtk.TreeIter`s `a` and `b`. Note that this method only works with unsorted stores.

### gtk.ListStore.move_after

        def move_after(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_after`() method moves the liststore row referenced by `iter` to the position after the row referenced by `position`. Note that this method only works with unsorted stores. If `position` is `None`, the row referenced by `iter` will be moved to the start of the list.

### gtk.ListStore.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 liststore row referenced by `iter` to the position before the row referenced by `position`. Note that this method only works with unsorted stores. If `position` is `None`, the row referenced by `iter` will be moved to the end of the list.

Prev | Up | Next
gtk.LinkButton | Home | gtk.Menu