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.
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.
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 TreeViews 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.
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
TreeViewColumns. 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.