GTK+ 2.0 Tree View Tutorial

Tim-Philipp Müller

This is a tutorial on how to use the GTK (the GIMP Toolkit) GtkTreeView widget through its C interface.

Please mail all comments and suggestions to

A tarball of the tutorial for off-line reading including the example source codes is available here: treeview-tutorial.tar.gz.

There is also a version in PDF format (for easier printing) and the raw docbook XML source document.

This tutorial is work-in-progress. The latest version can be found at http://scentric.net/tutorial/.

Some sections are a bit outdated (e.g. GtkTreeModelFilter has been in Gtk since 2.4), just haven't gotten around to rewrite them or update them. Sorry!

Last updated: September 29th, 2006

Table of Contents
1. Lists and Trees: the GtkTreeView Widget
1.1. Hello World
2. Components: Model, Renderer, Column, View
3. GtkTreeModels for Data Storage: GtkListStore and GtkTreeStore
3.1. How Data is Organised in a Store
3.2. Refering to Rows: GtkTreeIter, GtkTreePath, GtkTreeRowReference
3.2.1. GtkTreePath
3.2.2. GtkTreeIter
3.2.3. GtkTreeRowReference
3.2.4. Usage
3.3. Adding Rows to a Store
3.3.1. Adding Rows to a List Store
3.3.2. Adding Rows to a Tree Store
3.3.3. Speed Issues when Adding a Lot of Rows
3.4. Manipulating Row Data
3.5. Retrieving Row Data
3.5.1. Freeing Retrieved Row Data
3.6. Removing Rows
3.7. Removing Multiple Rows
3.8. Storing GObjects (Pixbufs etc.)
3.9. Storing Data Structures: of Pointers, GBoxed Types, and GObject (TODO)
4. Creating a Tree View
4.1. Connecting Tree View and Model
4.1.1. Reference counting
4.2. Tree View Look and Feel
5. Mapping Data to the Screen: GtkTreeViewColumn and GtkCellRenderer
5.1. Cell Renderers
5.2. Attributes
5.3. Cell Data Functions
5.4. GtkCellRendererText and Integer, Boolean and Float Types
5.5. GtkCellRendererText, UTF8, and pango markup
5.6. A Working Example
5.7. How to Make a Whole Row Bold or Coloured
5.8. How to Pack Icons into the Tree View
6. Selections, Double-Clicks and Context Menus
6.1. Handling Selections
6.1.1. Selection Modes
6.1.2. Getting the Currently Selected Rows
6.1.3. Using Selection Functions
6.1.4. Checking Whether a Row is Selected
6.1.5. Selecting and Unselecting Rows
6.1.6. Getting the Number of Selected Rows
6.2. Double-Clicks on a Row
6.3. Context Menus on Right Click
7. Sorting
7.1. GtkTreeSortable
7.2. GtkTreeModelSort
7.3. Sorting and Tree View Column Headers
7.4. Case-insensitive String Comparing
8. Editable Cells
8.1. Editable Text Cells
8.1.1. Setting the cursor to a specific cell
8.2. Editable Toggle and Radio Button Cells
8.3. Editable Spin Button Cells
9. Miscellaneous
9.1. Getting the Column Number from a Tree View Column Widget
9.2. Column Expander Visibility
9.2.1. Hiding the Column Expander
9.2.2. Forcing Column Expander Visibility
9.3. Getting the Cell Renderer a Click Event Happened On
9.4. Glade and Tree Views
10. Drag'n'Drop (DnD) **** needs revision ***
10.1. Drag'n'Dropping Row-Unrelated Data to and from a Tree View from other Windows or Widgets
10.2. Dragging Rows Around Within a Tree **** TODO ***
10.3. Dragging Rows from One Tree to Another **** TODO ***
11. Writing Custom Models
11.1. When is a Custom Model Useful?
11.2. What Does Writing a Custom Model Involve?
11.3. Example: A Simple Custom List Model
11.3.1. custom-list.h
11.3.2. custom-list.c
11.4. From a List to a Tree
11.5. Additional interfaces, here: the GtkTreeSortable interface
11.6. Working Example: Custom List Model Source Code
11.6.1. custom-list.h
11.6.2. custom-list.c
11.6.3. main.c
12. Writing Custom Cell Renderers
12.1. Working Example: a Progress Bar Cell Renderer
12.1.1. custom-cell-renderer-progressbar.h
12.1.2. custom-cell-renderer-progressbar.c
12.1.3. main.c
12.2. Cell Renderers Others Have Written
13. Other Resources
14. Copyright, License, Credits, and Revision History
14.1. Copyright and License
14.2. Credits
14.3. Revision History
  Next >>>
  Lists and Trees: the GtkTreeView Widget