GTK+ By Example/Tree View/Tree View

Creating a Tree View edit

In order to display data in a tree view widget, we need to create one first, and we need to instruct it where to get the data to display from.

A new tree view is created with:

  GtkWidget *view;

  view = gtk_tree_view_new();

Connecting Tree View and Model edit

Before we proceed to the next section where we display data on the screen, we need connect our data store to the tree view, so it knows where to get the data to display from. This is achieved with gtk_tree_view_set_model, which will by itself do very little. However, it is a prerequisite for what we do in the following sections. gtk_tree_view_new_with_model is a convenience function for the previous two.

gtk_tree_view_get_model will return the model that is currently attached to a given tree view, which is particularly useful in callbacks where you only get passed the tree view widget (after all, we do not want to go down the road of global variables, which will inevitably lead to the Dark Side, do we?).

Reference counting edit

Tree models like GtkListStore and GtkTreeStore are GObjects and have a reference count of 1 after creation. The tree view will add its own reference to the model when you add the model with gtk_tree_view_set_model, and will unref it again when you replace the model with another model, unset the model by passing NULL as a model, or when the tree view is destroyed. [1]

This means that you need to take care of "your" reference yourself, otherwise the model will not be destroyed properly when you disconnect it from the tree view, and its memory will not be freed (which does not matter much if the same model is connected to the tree view from application start to end). If you plan to use the same model for a tree view for the whole duration of the application, you can get rid of "your" reference right after you have connected the model to the view - then the model will be destroyed automatically when the tree view is destroyed (which will be automatically destroyed when the window it is in is destroyed):

  GtkListStore *liststore;
  GtkWidget    *view;

  view = gtk_tree_view_new();

  liststore = gtk_list_store_new(1, G_TYPE_STRING);

  gtk_tree_view_set_model(GTK_TREE_VIEW(view), GTK_TREE_MODEL(liststore));

  g_object_unref(liststore);

  /* Now the model will be destroyed when the tree view is destroyed */

Notes [1]

'Reference counting' means that an object has a counter that can be increased or decreased (ref-ed and unref-ed). If the counter is unref-ed to 0, the object is automatically destroyed. This is useful, because other objects or application programmers only have to think about whether they themselves are still using that object or not, without knowing anything about others also using it. The object is simply automatically destroyed when no one is using it any more.

Tree View Look and Feel edit

There are a couple of ways to influence the look and feel of the tree view. You can hide or show column headers with gtk_tree_view_set_headers_visible, and set them clickable or not with gtk_tree_view_set_headers_clickable (which will be done automatically for you if you enable sorting).

gtk_tree_view_set_rules_hint will enable or disable rules in the tree view. [1] As the function name implies, this setting is only a hint; in the end it depends on the active Gtk+ theme engine if the tree view shows ruled lines or not. Users seem to have strong feelings about rules in tree views, so it is probably a good idea to provide an option somewhere to disable rule hinting if you set it on tree views (but then, people also seem to have strong feelings about options abundance and 'sensible' default options, so whatever you do will probably upset someone at some point).

The expander column can be set with gtk_tree_view_set_expander_column. This is the column where child elements are indented with respect to their parents, and where rows with children have an 'expander' arrow with which a node's children can be collapsed (hidden) or expanded (shown). By default, this is the first column. Notes [1]

'Rules' means that every second line of the tree view has a shaded background, which makes it easier to see which cell belongs to which row in tree views that have a lot of columns.