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 `DataColumn`s. 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

    Constructors
    Constructor and Description
    `TreeStore(DataColumn[] types)` Construct a new TreeStore with the given column types.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `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, getValue, setValue, 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`