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");
 

 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);
 

 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);
 

Retrieving data

 String name;
 
 name = model.getValue(row, column);
 

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

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

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

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.

Overview  Package   Class		java-gnome
PREV CLASS   NEXT CLASS	FRAMES    NO FRAMES    All Classes
SUMMARY: NESTED | FIELD | CONSTR | METHOD	DETAIL: FIELD | CONSTR | METHOD