org.gnome.gtk

## Class TreeModel

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

- Direct Known Subclasses:
    ListStore, TreeModelFilter, TreeModelSort, TreeStore

      public abstract class TreeModel
      extends Object

  The data use as the model backing a `TreeView`. TreeModel comes in two flavours which actually store data: `ListStore`, for a list of rows, and `TreeStore`, for data which has a hierarchical relationship between the rows.

  TreeModels are tabular, and as such have "columns", each of which is strongly typed, and which are represented in java-gnome by the `DataColumn` classes.

  While the "columns" (and their types) must be declared when instantiating a TreeModel, the "rows" in a TreeModel are dynamic; it grows as you add data to the model. An instance of `TreeIter` points to an individual row in a TreeModel; these are used both when adding new rows and when dealing with identifying which row has been selected in a TreeView. Be warned that TreeIters are very transient and are only valid so long as you haven't changed the structure of the model (ie, by adding another row, sorting it, filtering it, etc) so when populating a TreeModel we tend to do so one complete row at a time.

  ## Populating TreeModels

  You add data to a TreeModel by first calling `appendRow()` which returns a TreeIter pointing to the new row, and then using the `setValue()` method appropriate to the data type of each column [`setValue()` has an overload for each concrete DataColumn type, so if you've declared the columns as fully derived DataColumnString or DataColumnInteger or whatever (as recommended), the following will Just Work]:

       final DataColumnString column;
       final ListStore model;
       TreeIter row;

       row = model.appendRow();
       model.setValue(row, column, "King George V");

  You'll note that in this example we called the TreeIter `row` and the DataColumn `column`; doing so made the first two arguments of each of the `setValue()` methods make sense: you are setting a value in the ListStore or TreeStore at the co-ordinates row, column. In practise, of course, you have many DataColumns,

       final DataColumnString monarchNameColumn;
       final DataColumnInteger coronatedYearColumn;
       final DataColumnPixbuf portraitColumn;
       final DataColumnReference monarchObjectColumn;
       final ListStore model;
       TreeIter row;
       Pixbuf portrait;
       ...

       row = model.appendRow();
       model.setValue(row, monarchNameColumn, "King George V");
       model.setValue(row, coronatedYearColumn, 1910);
       model.setValue(row, portraitColumn, portrait);

  There is a special kind of DataColumn for storing references to Java objects, DataColumnReference. This is used so that you can find your way back to the domain object model that your data came from in the first place. Indeed, the above code would probably have been done as follows:

       Monarch george;
       ...

       row = model.appendRow();
       model.setValue(row, monarchNameColumn, george.getFormalName());
       model.setValue(row, coronatedYearColumn, george.getCoronationYear());
       model.setValue(row, portraitColumn, george.getPortrait());
       model.setValue(row, monarchObjectColumn, george);

  (assuming we created our model with such a DataColumnReference in the first place). The key part is the last line, where we store [a reference to] the object itself in the model.

  ## Retrieving data

  You can retrieve data from a TreeModel with the same row, column co-ordinates used when storing data:

       String name;

       name = model.getValue(row, column);

  The `row` TreeIter in this case usually comes from a TreeView `TreeView.RowActivated` signal or a TreeSelection `TreeSelection.Changed` signal. You can also get a TreeIter for a specific row via `getIter()`. Less frequently you will want to iterate over all the rows in the model, which is possible as follows:

       row = model.getIterFirst();
       do {
           name = model.getValue(row, column);
           // do something with name
       } while (row.iterNext());

  Although we have illustrated getting a String out of the TreeModel here, you will normally only need to retrieve the Java object from your domain model from which the data in this row was derived and which it represents:

       ruler = (Monarch) model.getValue(row, monarchObjectColumn);

  once you have the Java object that has been "selected" by the user in your TreeView in hand, you can carry on from there with your application logic.

  As discussed in the documentation for DataColumn, TreeModels are only really meant as the backing store for a TreeView. By in large, you only use them as the means to drive what is being displayed by a TreeView; there's no reason to try and store a complex domain model in a GTK TreeModel. [By analogy, the String you pass to Label's `setLabel()` is merely setting the label property which is the "data store" backing the text displayed by the Label. You only push down what you want displayed; the rest of your data model stays in Java, of course. It's the same with TreeView]

  Since:
    4.0.5
  Author:
    Andrew Cowie, Peter Miller, Vreixo Formoso

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static interface` | `TreeModel.RowChanged` The signal emitted when a row in the model is changed.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `connect(TreeModel.RowChanged handler)` Hook up a handler for `TreeModel.RowChanged` signals.
    `TreeIter` | `getIter(TreePath path)` Convert a TreePath to a TreeIter appropriate for this TreeModel.
    `TreeIter` | `getIterFirst()` Initialize a new iterator at the beginning of the model.
    `TreePath` | `getPath(TreeIter row)` Get a TreePath corresponding to the row being pointed at by the given TreeIter.
    `boolean` | `getValue(TreeIter row, DataColumnBoolean column)` Get the `boolean` value stored in this TreeModel at the specified `row` and `column`.
    `Icon` | `getValue(TreeIter row, DataColumnIcon column)` Get the named Icon stored in this TreeModel at the specified `row` and `column`.
    `int` | `getValue(TreeIter row, DataColumnInteger column)` Get the `int` value stored in this TreeModel at the specified `row` and `column`.
    `long` | `getValue(TreeIter row, DataColumnLong column)` Get the `long` value stored in this TreeModel at the specified `row` and `column`.
    `<T> T` | `getValue(TreeIter row, DataColumnReference<T> column)` Get a reference to the Java object stored in this TreeModel at the specified `row` and `column`.
    `Stock` | `getValue(TreeIter row, DataColumnStock column)` Get the Stock icon stored in this TreeModel at the specified `row` and `column`.
    `String` | `getValue(TreeIter row, DataColumnString column)` Get the String stored in this TreeModel at the specified `row` and `column`.
    `void` | `setValue(TreeIter row, DataColumnBoolean column, boolean value)` Store a `boolean` in this TreeModel at the specified `row` and `column`.
    `void` | `setValue(TreeIter row, DataColumnIcon column, Icon value)` Store a named `Icon` constant in this TreeModel at the specified `row` and `column`.
    `void` | `setValue(TreeIter row, DataColumnInteger column, int value)` Store an `int` in this TreeModel at the specified `row` and `column`.
    `void` | `setValue(TreeIter row, DataColumnLong column, long value)` Store an `int` in this TreeModel at the specified `row` and `column`.
    `void` | `setValue(TreeIter row, DataColumnPixbuf column, Pixbuf value)` Store a Pixbuf in this TreeModel at the specified `row` and `column`.
    `<T> void` | `setValue(TreeIter row, DataColumnReference<T> column, T value)` Store a reference to a Java object in the TreeModel at the specified `row` and `column`.
    `void` | `setValue(TreeIter row, DataColumnStock column, Stock value)` Store a `Stock` constant in this TreeModel at the specified `row` and `column`.
    `void` | `setValue(TreeIter row, DataColumnString column, String value)` Store a String in this TreeModel at the specified `row` and `column`.

    - ### Methods inherited from class org.freedesktop.bindings.Pointer

      `toString`

    - ### Methods inherited from class Object

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

- - ### Method Detail

    - #### connect

          public void connect(TreeModel.RowChanged handler)

      Hook up a handler for `TreeModel.RowChanged` signals.
      Since:
        4.0.6

    - #### getIter

          public TreeIter getIter(TreePath path)

      Convert a TreePath to a TreeIter appropriate for this TreeModel. See `TreePath` for a full explanation of how to specify paths into ListStores and TreeStores.
      Returns:
        `null` if it can't figure out how to make the conversion of the given TreePath into a TreeIter pointing into this TreeModel.

    - #### getIterFirst

          public TreeIter getIterFirst()

      Initialize a new iterator at the beginning of the model. Since you presumably want to iterate through the remaining rows, use the `iterNext()` method you'll find on TreeIter as follows:

           TreeIter row;

           row = model.getIterFirst();
           do {
               // do something with row
           } while (row.iterNext());

      Returns:
        `null` if the model is presently empty.

    - #### getPath

          public TreePath getPath(TreeIter row)

      Get a TreePath corresponding to the row being pointed at by the given TreeIter.

      Remember that TreePaths, like TreeIters, are not stable across changes to the model; if you need to reliably point to a given row use `TreeRowReference` instead.

      Since:
        4.0.6

    - #### getValue

          public boolean getValue(TreeIter row,
                         DataColumnBoolean column)

      Get the `boolean` value stored in this TreeModel at the specified `row` and `column`.

    - #### getValue

          public Icon getValue(TreeIter row,
                      DataColumnIcon column)

      Get the named Icon stored in this TreeModel at the specified `row` and `column`.
      Since:
        4.0.7

    - #### getValue

          public int getValue(TreeIter row,
                     DataColumnInteger column)

      Get the `int` value stored in this TreeModel at the specified `row` and `column`.

    - #### getValue

          public long getValue(TreeIter row,
                      DataColumnLong column)

      Get the `long` value stored in this TreeModel at the specified `row` and `column`.

    - #### getValue

          public <T> T getValue(TreeIter row,
                       DataColumnReference<T> column)

      Get a reference to the Java object stored in this TreeModel at the specified `row` and `column`. You'll have to cast the return value to whatever type you put in there in the first place, obviously.

    - #### getValue

          public Stock getValue(TreeIter row,
                       DataColumnStock column)

      Get the Stock icon stored in this TreeModel at the specified `row` and `column`.
      Since:
        4.0.7

    - #### getValue

          public String getValue(TreeIter row,
                        DataColumnString column)

      Get the String stored in this TreeModel at the specified `row` and `column`.

    - #### setValue

          public void setValue(TreeIter row,
                      DataColumnBoolean column,
                      boolean value)

      Store a `boolean` in this TreeModel at the specified `row` and `column`.

    - #### setValue

          public void setValue(TreeIter row,
                      DataColumnIcon column,
                      Icon value)

      Store a named `Icon` constant in this TreeModel at the specified `row` and `column`.
      Since:
        4.0.17

    - #### setValue

          public void setValue(TreeIter row,
                      DataColumnInteger column,
                      int value)

      Store an `int` in this TreeModel at the specified `row` and `column`.

    - #### setValue

          public void setValue(TreeIter row,
                      DataColumnLong column,
                      long value)

      Store an `int` in this TreeModel at the specified `row` and `column`.

    - #### setValue

          public void setValue(TreeIter row,
                      DataColumnPixbuf column,
                      Pixbuf value)

      Store a Pixbuf in this TreeModel at the specified `row` and `column`. This is used to provide the image data needed by a TreeViewColumn with a `CellRendererPixbuf` in it.

    - #### setValue

          public <T> void setValue(TreeIter row,
                          DataColumnReference<T> column,
                          T value)

      Store a reference to a Java object in the TreeModel at the specified `row` and `column`. This is used so you can get back to your Java side domain object model in response to an event on the TreeView.

    - #### setValue

          public void setValue(TreeIter row,
                      DataColumnStock column,
                      Stock value)

      Store a `Stock` constant in this TreeModel at the specified `row` and `column`.
      Since:
        4.0.7

    - #### setValue

          public void setValue(TreeIter row,
                      DataColumnString column,
                      String value)

      Store a String in this TreeModel at the specified `row` and `column`.