org.gnome.gtk
Class TreeStore

Object
  org.freedesktop.bindings.Pointer
      org.freedesktop.bindings.Proxy
          org.gnome.glib.Object
              org.gnome.gtk.TreeModel
                  org.gnome.gtk.TreeStore

All Implemented Interfaces:

TreeDragDest, TreeDragSource, TreeSortable

public class TreeStore
extends TreeModel
implements TreeDragSource, TreeDragDest, TreeSortable

A TreeModel that stores its data in a hierarchical tree. TreeStore is a concrete TreeModel subclass where rows can also have other rows that are children. This model is suitable for hierarchical data where each row has a parent and a list of children. If you just want to store a list of rows (ie, plain tabular data), ListStore is a more appropriate choice.

Instantiating a TreeStore is done identically as with a ListStore, by specifying an array of DataColumns. For example, given:

 final TreeStore model;
 final DataColumnString place;
 ...
 

you would build a model as follows:

 model = new TreeStore(new DataColumn[] {
         place = new DataColumnString(),
         ...
 });
 

The caveat described in ListStore applies here; don't declare your model as abstract type TreeModel; keep them as concrete type TreeStore so you can get to the TreeStore specific methods for adding rows and navigating the hierarchy.

To add a new row at the top level of the hierarchy, you just use appendRow() as you have seen with ListStore:

 parent = model.appendRow();
 model.setValue(parent, place, "Europe");
 

If, however, you want to add a new row as a child of an existing row, you need to use the appendChild() method instead:

 child = model.appendRow(parent);
 model.setValue(child, place, "London");
 child = model.appendRow(parent);
 model.setValue(child, place, "Paris");
 ...
 

passing the TreeIter representing the parent you wish to create a child under.

You may also want to read the discussion at TreePath to understand how to address a particular row in a given TreeStore. You will also probably want to be aware of TreeView's expandRow(), expandAll(), and corresponding collapse methods.

Since:

4.0.7

Author:

Vreixo Formoso, Andrew Cowie

Nested Class Summary

Nested classes/interfaces inherited from class org.gnome.gtk.TreeModel

TreeModel.RowChanged

Constructor Summary

TreeStore(DataColumn[] types)
Construct a new TreeStore with the given column types.

Method Summary

TreeIter	appendChild(TreeIter parent) Append a new row after the last child of the given row.
TreeIter	appendRow() Append a new row at the top level of this TreeStore.
void	clear() Remove all elements from this TreeStore.
TreeIter	insertRow(TreeIter parent, int position) Insert a new row in the TreeStore.
TreeIter	insertRow(TreeIter parent, TreeIter sibling) Insert a new row in the TreeStore.
TreeIter	iterChildren(TreeIter row) Get the children of the given row, if any.
boolean	iterHasChild(TreeIter row) Returns whether the given row has at least one child row.
TreeIter	iterParent(TreeIter row) Get the parent of the given row, assuming there is one.
boolean	removeRow(TreeIter row) Delete a row from the TreeStore.
void	setSortColumn(DataColumn column, SortType ordering) Specify the column from your (underlying) data model which will be used for sorting this TreeModelSort.

Methods inherited from class org.gnome.gtk.TreeModel

connect, getIter, getIterFirst, getPath, getValue, getValue, getValue, getValue, getValue, getValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue

Methods inherited from class org.freedesktop.bindings.Pointer

toString

Methods inherited from class Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

TreeStore

public TreeStore(DataColumn[] types)

Construct a new TreeStore with the given column types. See DataColumn for details. You must include at least one DataColumn in your types array (you can't have a TreeStore with no columns).

Since:

4.0.7

Method Detail

appendChild

public TreeIter appendChild(TreeIter parent)

Append a new row after the last child of the given row. You'll need to fill in the various columns with one of the various setValue() methods, of course.

To add a top level row, use appendRow().

Parameters:

parent - The row to which a new child will be added.

Returns:

A pointer to the newly created child row.

Since:

4.0.7

appendRow

public TreeIter appendRow()

Append a new row at the top level of this TreeStore. If what you want is to add a row as a child of an already existing row, you use appendChild(parent).

Returns:

A pointer to the newly created top level row.

Since:

4.0.7

clear

public void clear()

Remove all elements from this TreeStore.

Since:

4.0.7

insertRow

public TreeIter insertRow(TreeIter parent,
                          int position)

Insert a new row in the TreeStore. The row will be placed as a child of parent at the position specified. If parent is null then the new row will be inserted at the top level of the TreeStore.

Since:

4.0.7

insertRow

public TreeIter insertRow(TreeIter parent,
                          TreeIter sibling)

Insert a new row in the TreeStore. The empty row will be a child of parent and will be placed in front of the supplied sibling.

Since:

4.0.7

iterChildren

public TreeIter iterChildren(TreeIter row)

Get the children of the given row, if any.

You can use the returned TreeIter to iterate on children rows as follows:

 child = model.iterChildren(row);
 if (child == null) {
     return;
 }
 
 do {
     // do something with child row
 } while (child.iterNext());
 

which works because iterating with a TreeIter will only iterate over the rows that are siblings, ie, are at the same level of the hierarchy.

Returns:

A TreeIter pointing at the first child of this row, or null if the row has no children.

Since:

4.0.7

iterHasChild

public boolean iterHasChild(TreeIter row)

Returns whether the given row has at least one child row.

You can use iterChildren() to get the actual children.

Returns:

true if the specified row has one or more children, false otherwise.

Since:

4.0.7

iterParent

public TreeIter iterParent(TreeIter row)

Get the parent of the given row, assuming there is one.

Returns:

The parent row, or null if this row has no parent.

Since:

4.0.7

removeRow

public boolean removeRow(TreeIter row)

Delete a row from the TreeStore. If there is another row after this at this level then true will be returned and the TreeIter will still be valid. Otherwise, false is returned and row is invalidated.

Since:

4.0.7

setSortColumn

public void setSortColumn(DataColumn column,
                          SortType ordering)

Description copied from interface: TreeSortable

Specify the column from your (underlying) data model which will be used for sorting this TreeModelSort. Specify ASCENDING or DESCENDING order via the ordering parameter.

Specified by:

setSortColumn in interface TreeSortable