TreeStore

Deprecated since version 4.10: Use TreeListModel instead

class TreeStore(*column_types)

Superclasses: Object

Implemented Interfaces: Buildable, TreeDragDest, TreeDragSource, TreeModel, TreeSortable

A tree-like data structure that can be used with the TreeView.

The GtkTreeStore object is a list model for use with a GtkTreeView widget. It implements the TreeModel interface, and consequently, can use all of the methods available there. It also implements the TreeSortable interface so it can be sorted by the view. Finally, it also implements the tree [drag]:obj:TreeDragSource and [drop]:obj:TreeDragDest interfaces.

GtkTreeStore is deprecated since GTK 4.10, and should not be used in newly written code. You should use TreeListModel for a tree-like model object.

GtkTreeStore as GtkBuildable

The GtkTreeStore implementation of the GtkBuildable interface allows to specify the model columns with a <columns> element that may contain multiple <column> elements, each specifying one model column. The “type” attribute specifies the data type for the column.

An example of a UI Definition fragment for a tree store:

<object class="GtkTreeStore">
  <columns>
    <column type="gchararray"/>
    <column type="gchararray"/>
    <column type="gint"/>
  </columns>
</object>

Constructors

class TreeStore
classmethod new(types: Sequence[type]) → TreeStore

Creates a new tree store.

The tree store will have n_columns, with each column using the corresponding type passed to this function.

Note that only types derived from standard GObject fundamental types are supported.

As an example:

gtk_tree_store_new (3, G_TYPE_INT, G_TYPE_STRING, GDK_TYPE_TEXTURE);

will create a new GtkTreeStore with three columns of type int, gchararray, and GdkTexture respectively.

Deprecated since version 4.10: Use TreeListModel instead

Parameters:

types

Methods

class TreeStore
append(parent, row=None)

Appends a new row to tree_store.

If parent is non-None, then it will append the new row after the last child of parent, otherwise it will append a row to the top level.

The iter parameter will be changed to point to this new row. The row will be empty after this function is called. To fill in values, you need to call set() or set_value().

Deprecated since version 4.10: Use TreeListModel instead

Parameters:

  • parent – A valid GtkTreeIter

  • row

clear() → None

Removes all rows from tree_store

Deprecated since version 4.10: Use TreeListModel instead

insert(parent, position, row=None)

Creates a new row at position.

If parent is non-None, then the row will be made a child of parent. Otherwise, the row will be created at the toplevel.

If position is -1 or is larger than the number of rows at that level, then the new row will be inserted to the end of the list.

The iter parameter will be changed to point to this new row. The row will be empty after this function is called. To fill in values, you need to call set() or set_value().

Deprecated since version 4.10: Use TreeListModel instead

Parameters:

  • parent – A valid GtkTreeIter

  • position – position to insert the new row, or -1 for last

  • row

insert_after(parent, sibling, row=None)

Inserts a new row after sibling.

If sibling is None, then the row will be prepended to parent’s children.

If parent and sibling are None, then the row will be prepended 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.

The iter parameter will be changed to point to this new row. The row will be empty after this function is called. To fill in values, you need to call set() or set_value().

Deprecated since version 4.10: Use TreeListModel instead

Parameters:

  • parent – A valid GtkTreeIter

  • sibling – A valid GtkTreeIter

  • row

insert_before(parent, sibling, row=None)

Inserts a new row before sibling.

If sibling is None, then the row will be appended to parent’s children.

If parent and sibling are None, then 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.

The iter parameter will be changed to point to this new row. The row will be empty after this function is called. To fill in values, you need to call set() or set_value().

Deprecated since version 4.10: Use TreeListModel instead

Parameters:

  • parent – A valid GtkTreeIter

  • sibling – A valid GtkTreeIter

  • row

insert_with_values(parent: TreeIter | None, position: int, columns: Sequence[int], values: Sequence[Any]) → TreeIter

Creates a new row at the given position.

The iter parameter will be changed to point to this new row.

If position is -1, or larger than the number of rows on the list, then the new row will be appended to the list. The row will be filled with the values given to this function.

Calling

gtk_tree_store_insert_with_values (tree_store, iter, position, …)

has the same effect as calling

gtk_tree_store_insert (tree_store, iter, position);
gtk_tree_store_set (tree_store, iter, ...);

with the different that the former will only emit a row_inserted signal, while the latter will emit row_inserted, row_changed and if the tree store is sorted, rows_reordered.

Since emitting the rows_reordered signal repeatedly can affect the performance of the program, insert_with_values() should generally be preferred when inserting rows in a sorted tree store.

Deprecated since version 4.10: Use TreeListModel instead

Parameters:

  • parent – A valid GtkTreeIter

  • position – position to insert the new row, or -1 to append after existing rows

  • columns

  • values

is_ancestor(iter: TreeIter, descendant: TreeIter) → bool

Checks if iter is an ancestor of descendant.

Deprecated since version 4.10: Use TreeListModel instead

Parameters:

  • iter – A valid GtkTreeIter

  • descendant – A valid GtkTreeIter

iter_depth(iter: TreeIter) → int

Returns the depth of the position pointed by the iterator

The depth will be 0 for anything on the root level, 1 for anything down a level, etc.

Deprecated since version 4.10: Use TreeListModel instead

Parameters:

iter – A valid GtkTreeIter

iter_is_valid(iter: TreeIter) → bool

Checks if the given iter is a valid iter for this GtkTreeStore.

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

Deprecated since version 4.10: Use TreeListModel instead

Parameters:

iter – the iterator to check

move_after(iter: TreeIter, position: TreeIter | None = None) → None

Moves iter in tree_store to the position after position.

iter and position should be in the same level.

Note that this function only works with unsorted stores.

If position is None, iter will be moved to the start of the level.

Deprecated since version 4.10: Use TreeListModel instead

Parameters:

  • iter – A GtkTreeIter.

  • position – A GtkTreeIter.

move_before(iter: TreeIter, position: TreeIter | None = None) → None

Moves iter in tree_store to the position before position.

iter and position should be in the same level.

Note that this function only works with unsorted stores.

If position is None, iter will be moved to the end of the level.

Deprecated since version 4.10: Use TreeListModel instead

Parameters:

  • iter – A GtkTreeIter

  • position – A GtkTreeIter

prepend(parent, row=None)

Prepends a new row to tree_store.

If parent is non-None, then it will prepend the new row before the first child of parent, otherwise it will prepend a row to the top level. The iter parameter will be changed to point to this new row. The row will be empty after this function is called. To fill in values, you need to call set() or set_value().

Deprecated since version 4.10: Use TreeListModel instead

Parameters:

  • parent – A valid GtkTreeIter

  • row

remove(iter: TreeIter) → bool

Removes iter from tree_store.

After being removed, iter is set to the next valid row at that level, or invalidated if it previously pointed to the last one.

Deprecated since version 4.10: Use TreeListModel instead

Parameters:

iter – A valid GtkTreeIter

set(treeiter, *args)

Sets the value of one or more cells in the row referenced by iter.

The variable argument list should contain integer column numbers, each column number followed by the value to be set.

The list is terminated by a value of -1.

For example, to set column 0 with type G_TYPE_STRING to “Foo”, you would write

gtk_tree_store_set (store, iter, 0, "Foo", -1);

The value will be referenced by the store if it is a G_TYPE_OBJECT, and it will be copied if it is a G_TYPE_STRING or G_TYPE_BOXED.

Deprecated since version 4.10: Use TreeListModel instead

Parameters:

  • treeiter

  • args

set_column_types(types: Sequence[type]) → None

Sets the type of the columns in a tree store.

This function is meant primarily for types that inherit from GtkTreeStore, and should only be used when constructing a new GtkTreeStore.

This functions cannot be called after a row has been added, or a method on the GtkTreeModel interface is called on the tree store.

Deprecated since version 4.10: Use TreeListModel instead

Parameters:

types – An array of GType types, one for each column

set_value(treeiter, column, value)

Sets the data in the cell specified by iter and column.

The type of value must be convertible to the type of the column.

Deprecated since version 4.10: Use TreeListModel instead

Parameters:

  • treeiter

  • column – column number to modify

  • value – new value for the cell

swap(a: TreeIter, b: TreeIter) → None

Swaps a and b in the same level of tree_store.

Note that this function only works with unsorted stores.

Deprecated since version 4.10: Use TreeListModel instead

Parameters:

  • a – A GtkTreeIter.

  • b – Another GtkTreeIter.

Fields

class TreeStore
parent
priv