TreeModel (java-gnome 4.1.3 API Documentation)

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.

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.

Class TreeModel

Populating TreeModels

Retrieving data

Nested Class Summary

Method Summary

Methods inherited from class org.freedesktop.bindings.Pointer

Methods inherited from class Object

Method Detail

connect

getIter

getIterFirst

getPath

getValue

getValue

getValue

getValue

getValue

getValue

getValue

setValue

setValue

setValue

setValue

setValue

setValue

setValue

setValue