8.8. TreeView

The TreeView object is a widget for displaying trees and lists. The sole purpose of this widget is for displaying the data on the screen and setting other parts of the view using the associated objects.

The standard tree and list widgets in Gtk are very powerful, but somewhat complex. For your conveniance, the Java-Gnome project has derived a number of simpler classes for common uses of these widgets (ex. SimpleList). If you choose not to use those, or your requirements are such that you cannot use them, you will have to learn how to use the full objects.

There is only one widget which is placed in any applications to create trees, lists and tables. This is the TreeView. An application can have any number of treeviews and they can be placed as can normal widgets. The data for the widget, and the method in which it is displayed is controlled by other classes. Gtk has been designed so that any number of treeview widgets can be linked to the same data store. TreeViewColumns, CellRenderers and TreeSelections are created for each view, so Views can use the same data store but have their own column layout, data display within those columns (linked to any of the dataBlocks in the store); and their own selections.

Models are used to store data. Data is stored in what could be considered a table. There are a number of DataBlocks, which could be considered as data columns (in fact, in the C version of gtk, they are always refered to as columns; but this can get confused with TreeViewColumns which are quite a different matter). These dataBlocks each store one type of data (String, boolean, int, etc.). The 'rows' of the data table, or the individual records in the data store are accessible using iterators called TreeIters. These are used extensively in many methods. Setting data involves getting an iterator (usually be creating a new row) and then setting the value for each of the dataBlocks. The ordering of these dataBlocks has absolutely no meaning - you can decide exactly which blocks are used on screen by setting Attribute mappings to the CellRenderers which render data on the screen (see below).

Currently, there are two implementations of TreeModel. ListStore is used for tables and lists. Data is organised in rows and columns. TreeStore is for the hierarchical trees. Data is organised using TreePath's.

Both trees and lists can have multiple columns of data. Columns are added and removed using the TreeView class. Columns are objects which determine how the data is displayed. They have settings such as the column title, whether the column can be resized, and even whether the columns can be reorganized (by dragging the columns). Each TreeView widget has it's own set of columns. Determining how the data is displayed in the columns is done by CellRenderers (see below). Any number of renderers can be added to the same column.

Tree and list `cells' may contain a large variety of data types. Determining how they are displayed is done by the CellRenderer family of classes. If the data is unusual, or you want to combine a number of data types in a single column, you may construct your own renderer. However, you are recommended to stick with the regular choices.

The CellRenderer's need data to be able to display. This is set using TreeViewColumn.addAttributeMapping(CellRenderer, CellRendererAttribute, int). The renderer attributes vary with each renderer, for example CellRendererText has a TEXT attribute for the text the be displayed. The final parameter is for the dataBlock in the store in which the data is contained.