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.