14.3. TreeViews
Prev | Chapter 14. Tree View Widget | Next

## 14.3. TreeViews

A `TreeView` is basically a container for the `TreeViewColumn` and `CellRenderer` objects that do the actual display of the data store data. It also provides an interface to the displayed data rows and to the characteristics that control the data display.

### 14.3.1. Creating a TreeView

A `TreeView` is created using its constructor:

      treeview = gtk.TreeView(model=None)

where `model` is an object implementing the `TreeModel` interface (usually a `ListStore` or `TreeStore`). If `model` is `None` or not specified the `TreeView` will not be associated with a data store.

### 14.3.2. Getting and Setting the TreeView Model

The tree model providing the data store for a `TreeView` can be retrieved using the `get_model`() method:

      model = treeview.get_model()

A `TreeModel` may be simultaneously associated with more than one `TreeView` which automatically changes its display when the `TreeModel` data changes. While a `TreeView` always displays all of the rows of its tree model, it may display only some of the tree model columns. This means that two `TreeView`s associated with the same `TreeModel` may provide completely different views of the same data.

It's also important to realize that there is no preset relation between the columns in a `TreeView` and the columns of its `TreeModel`. That is, the fifth column of data in a `TreeModel` may be displayed in the first column of one `TreeView` and in the third column in another.

A `TreeView` can change its tree model using the `set_model`() method:

      treeview.set_model(model=None)

where `model` is an object implementing the `TreeModel` interface (e.g. `ListStore` and `TreeStore`). If `model` is `None`, the current model is discarded.

### 14.3.3. Setting TreeView Properties

The `TreeView` has a number of properties that can be managed using its methods:

"enable-search" | Read-Write | If `TRUE`, the user can search through columns interactively. Default is `TRUE`
"expander-column" | Read-Write | The column for the expander. Default is 0
"fixed-height-mode" | Read-Write | If `TRUE`, assume all rows have the same height thereby speeding up display. Available in GTK+ 2.4 and above. Default is `FALSE`
"hadjustment" | Read-Write | The horizontal `Adjustment` for the widget. New one created by default.
"headers-clickable" | Write | If `TRUE`, the column headers respond to click events. Default is `FALSE`
"headers-visible" | Read-Write | If `TRUE`, show the column header buttons. Default is `TRUE`
"model" | Read-Write | The model for the tree view. Default is `None`
"reorderable" | Read-Write | If `TRUE`, the view is reorderable. Default is `FALSE`
"rules-hint" | Read-Write | If `TRUE`, hint to the theme engine to draw rows in alternating colors. Default is `FALSE`
"search-column" | Read-Write | The model column to search when searching through code. Default is -1.
"vadjustment" | Read-Write | The vertical `Adjustment` for the widget. New one created by default.

The corresponding methods are:

      enable_search = treeview.get_enable_search()
      treeview.set_enable_search(enable_search)

      column = treeview.get_expander_column()
      treeview.set_expander_column(column)

      hadjustment = treeview.get_hadjustment()
      treeview.set_hadjustment(adjustment)

      treeview.set_headers_clickable(active)

      headers_visible = treeview.get_headers_visible()
      treeview.set_headers_visible(headers_visible)

      reorderable = treeview.get_reorderable()
      treeview.set_reorderable(reorderable)

      riles_hint = treeview.get_rules_hint()
      treeview.set_rules_hint(setting)

      column = treeview.get_search_column()
      treeview.set_search_column(column)

      vadjustment = treeview.get_vadjustment()
      treeview.set_vadjustment(adjustment)

Most of these are obvious from the description. However, the "enable-search" property requires the "search-column" property to be set to the number of a valid column in the tree model. Then when the user presses Control+f a search dialog is popped up that the user can type in. The first matching row will be automatically selected as the user types.

Likewise, the "headers-clickable" property really just sets the "clickable" property of the underlying `TreeViewColumn`s. A `TreeViewColumn` will not be sortable unless the tree model implements the `TreeSortable` interface and the `TreeViewColumn` `set_sort_column_id`() method has been called with a valid column number.

The "reorderable" property enables the user to reorder the `TreeView` model by dragging and dropping the `TreeView` rows displayed.

The "rules-hint" property should only be set if you have lots of columns and think that alternating colors may help the user.

Prev | Up | Next
14.2. The TreeModel Interface and Data Stores | Home | 14.4. CellRenderers