339 lines
16 KiB
HTML
339 lines
16 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||
<html>
|
||
<head>
|
||
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
|
||
<title>Tree and List Widget Overview: GTK+ 3 Reference Manual</title>
|
||
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
|
||
<link rel="home" href="index.html" title="GTK+ 3 Reference Manual">
|
||
<link rel="up" href="TreeWidgetObjects.html" title="Tree, List and Icon Grid Widgets">
|
||
<link rel="prev" href="TreeWidgetObjects.html" title="Tree, List and Icon Grid Widgets">
|
||
<link rel="next" href="GtkTreeModel.html" title="GtkTreeModel">
|
||
<meta name="generator" content="GTK-Doc V1.27 (XML mode)">
|
||
<link rel="stylesheet" href="style.css" type="text/css">
|
||
</head>
|
||
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
||
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
|
||
<td width="100%" align="left" class="shortcuts"></td>
|
||
<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
|
||
<td><a accesskey="u" href="TreeWidgetObjects.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
|
||
<td><a accesskey="p" href="TreeWidgetObjects.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
|
||
<td><a accesskey="n" href="GtkTreeModel.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
|
||
</tr></table>
|
||
<div class="refentry">
|
||
<a name="TreeWidget"></a><div class="titlepage"></div>
|
||
<div class="refnamediv"><table width="100%"><tr>
|
||
<td valign="top">
|
||
<h2><span class="refentrytitle">Tree and List Widget Overview</span></h2>
|
||
<p>Tree and List Widget Overview — Overview of GtkTreeModel, GtkTreeView, and friends</p>
|
||
</td>
|
||
<td class="gallery_image" valign="top" align="right"></td>
|
||
</tr></table></div>
|
||
<div class="refsect1">
|
||
<a name="id-1.3.12.2.3"></a><h2>Overview</h2>
|
||
<p>
|
||
To create a tree or list in GTK+, use the <a class="link" href="GtkTreeModel.html" title="GtkTreeModel"><span class="type">GtkTreeModel</span></a> interface in
|
||
conjunction with the <a class="link" href="GtkTreeView.html" title="GtkTreeView"><span class="type">GtkTreeView</span></a> widget. This widget is
|
||
designed around a <em class="firstterm">Model/View/Controller</em>
|
||
design and consists of four major parts:
|
||
</p>
|
||
<table border="0" summary="Simple list" class="simplelist">
|
||
<tr><td>The tree view widget (<span class="structname">GtkTreeView</span>)</td></tr>
|
||
<tr><td>The view column (<span class="structname">GtkTreeViewColumn</span>)</td></tr>
|
||
<tr><td>The cell renderers (<span class="structname">GtkCellRenderer</span> etc.)</td></tr>
|
||
<tr><td>The model interface (<span class="structname">GtkTreeModel</span>)</td></tr>
|
||
</table>
|
||
<p>
|
||
The <span class="emphasis"><em>View</em></span> is composed of the first three
|
||
objects, while the last is the <span class="emphasis"><em>Model</em></span>. One
|
||
of the prime benefits of the MVC design is that multiple views
|
||
can be created of a single model. For example, a model mapping
|
||
the file system could be created for a file manager. Many views
|
||
could be created to display various parts of the file system,
|
||
but only one copy need be kept in memory.
|
||
</p>
|
||
<p>
|
||
The purpose of the cell renderers is to provide extensibility to the
|
||
widget and to allow multiple ways of rendering the same type of data.
|
||
For example, consider how to render a boolean variable. Should it
|
||
render it as a string of "True" or "False", "On" or "Off", or should
|
||
it be rendered as a checkbox?
|
||
</p>
|
||
</div>
|
||
<div class="refsect1">
|
||
<a name="id-1.3.12.2.4"></a><h2>Creating a model</h2>
|
||
<p>
|
||
GTK+ provides two simple models that can be used: the <a class="link" href="GtkListStore.html" title="GtkListStore"><span class="type">GtkListStore</span></a>
|
||
and the <a class="link" href="GtkTreeStore.html" title="GtkTreeStore"><span class="type">GtkTreeStore</span></a>. GtkListStore is used to model list widgets,
|
||
while the GtkTreeStore models trees. It is possible to develop a new
|
||
type of model, but the existing models should be satisfactory for all
|
||
but the most specialized of situations. Creating the model is quite
|
||
simple:
|
||
</p>
|
||
<div class="informalexample"><pre class="programlisting">
|
||
GtkListStore *store = gtk_list_store_new (2, G_TYPE_STRING, G_TYPE_BOOLEAN);
|
||
</pre></div>
|
||
<p>
|
||
This creates a list store with two columns: a string column and a boolean
|
||
column. Typically the 2 is never passed directly like that; usually an
|
||
enum is created wherein the different columns are enumerated, followed by
|
||
a token that represents the total number of columns. The next example will
|
||
illustrate this, only using a tree store instead of a list store. Creating
|
||
a tree store operates almost exactly the same.
|
||
</p>
|
||
<div class="informalexample"><pre class="programlisting">
|
||
enum
|
||
{
|
||
TITLE_COLUMN,
|
||
AUTHOR_COLUMN,
|
||
CHECKED_COLUMN,
|
||
N_COLUMNS
|
||
};
|
||
|
||
GtkTreeStore *store = gtk_tree_store_new (N_COLUMNS, /* Total number of columns */
|
||
G_TYPE_STRING, /* Book title */
|
||
G_TYPE_STRING, /* Author */
|
||
G_TYPE_BOOLEAN); /* Is checked out? */
|
||
</pre></div>
|
||
<p>
|
||
Adding data to the model is done using <a class="link" href="GtkTreeStore.html#gtk-tree-store-set" title="gtk_tree_store_set ()"><code class="function">gtk_tree_store_set()</code></a> or
|
||
<a class="link" href="GtkListStore.html#gtk-list-store-set" title="gtk_list_store_set ()"><code class="function">gtk_list_store_set()</code></a>, depending upon which sort of model was
|
||
created. To do this, a <a class="link" href="GtkTreeModel.html#GtkTreeIter"><span class="type">GtkTreeIter</span></a> must be acquired. The iterator
|
||
points to the location where data will be added.
|
||
</p>
|
||
<p>
|
||
Once an iterator has been acquired, <a class="link" href="GtkTreeStore.html#gtk-tree-store-set" title="gtk_tree_store_set ()"><code class="function">gtk_tree_store_set()</code></a> is used to
|
||
apply data to the part of the model that the iterator points to.
|
||
Consider the following example:
|
||
</p>
|
||
<div class="informalexample"><pre class="programlisting">
|
||
GtkTreeIter iter;
|
||
|
||
gtk_tree_store_append (store, &iter, NULL); /* Acquire an iterator */
|
||
|
||
gtk_tree_store_set (store, &iter,
|
||
TITLE_COLUMN, "The Principle of Reason",
|
||
AUTHOR_COLUMN, "Martin Heidegger",
|
||
CHECKED_COLUMN, FALSE,
|
||
-1);
|
||
</pre></div>
|
||
<p>
|
||
Notice that the last argument is -1. This is always done because
|
||
this is a variable-argument function and it needs to know when to stop
|
||
processing arguments. It can be used to set the data in any or all
|
||
columns in a given row.
|
||
</p>
|
||
<p>
|
||
The third argument to <a class="link" href="GtkTreeStore.html#gtk-tree-store-append" title="gtk_tree_store_append ()"><code class="function">gtk_tree_store_append()</code></a> is the parent iterator. It
|
||
is used to add a row to a GtkTreeStore as a child of an existing row. This
|
||
means that the new row will only be visible when its parent is visible and
|
||
in its expanded state. Consider the following example:
|
||
</p>
|
||
<div class="informalexample"><pre class="programlisting">
|
||
GtkTreeIter iter1; /* Parent iter */
|
||
GtkTreeIter iter2; /* Child iter */
|
||
|
||
gtk_tree_store_append (store, &iter1, NULL); /* Acquire a top-level iterator */
|
||
gtk_tree_store_set (store, &iter1,
|
||
TITLE_COLUMN, "The Art of Computer Programming",
|
||
AUTHOR_COLUMN, "Donald E. Knuth",
|
||
CHECKED_COLUMN, FALSE,
|
||
-1);
|
||
|
||
gtk_tree_store_append (store, &iter2, &iter1); /* Acquire a child iterator */
|
||
gtk_tree_store_set (store, &iter2,
|
||
TITLE_COLUMN, "Volume 1: Fundamental Algorithms",
|
||
-1);
|
||
|
||
gtk_tree_store_append (store, &iter2, &iter1);
|
||
gtk_tree_store_set (store, &iter2,
|
||
TITLE_COLUMN, "Volume 2: Seminumerical Algorithms",
|
||
-1);
|
||
|
||
gtk_tree_store_append (store, &iter2, &iter1);
|
||
gtk_tree_store_set (store, &iter2,
|
||
TITLE_COLUMN, "Volume 3: Sorting and Searching",
|
||
-1);
|
||
</pre></div>
|
||
</div>
|
||
<div class="refsect1">
|
||
<a name="id-1.3.12.2.5"></a><h2>Creating the view component</h2>
|
||
<p>
|
||
While there are several different models to choose from, there is
|
||
only one view widget to deal with. It works with either the list
|
||
or the tree store. Setting up a <a class="link" href="GtkTreeView.html" title="GtkTreeView"><span class="type">GtkTreeView</span></a> is not a difficult
|
||
matter. It needs a <a class="link" href="GtkTreeModel.html" title="GtkTreeModel"><span class="type">GtkTreeModel</span></a> to know where to retrieve its data
|
||
from.
|
||
</p>
|
||
<div class="informalexample"><pre class="programlisting">
|
||
GtkWidget *tree;
|
||
|
||
tree = gtk_tree_view_new_with_model (GTK_TREE_MODEL (store));
|
||
</pre></div>
|
||
<div class="refsect2">
|
||
<a name="id-1.3.12.2.5.4"></a><h3>Columns and cell renderers</h3>
|
||
<p>
|
||
Once the <a class="link" href="GtkTreeView.html" title="GtkTreeView"><span class="type">GtkTreeView</span></a> widget has a model, it will need to know how
|
||
to display the model. It does this with columns and cell renderers.
|
||
</p>
|
||
<p>
|
||
Cell renderers are used to draw the data in the tree model in a
|
||
way. There are a number of cell renderers that come with GTK+,
|
||
including the <a class="link" href="GtkCellRendererText.html" title="GtkCellRendererText"><span class="type">GtkCellRendererText</span></a>, <a class="link" href="GtkCellRendererPixbuf.html" title="GtkCellRendererPixbuf"><span class="type">GtkCellRendererPixbuf</span></a> and
|
||
the <a class="link" href="GtkCellRendererToggle.html" title="GtkCellRendererToggle"><span class="type">GtkCellRendererToggle</span></a>.
|
||
It is relatively easy to write a custom renderer.
|
||
</p>
|
||
<p>
|
||
A <a class="link" href="GtkTreeViewColumn.html" title="GtkTreeViewColumn"><span class="type">GtkTreeViewColumn</span></a> is the object that GtkTreeView uses to organize
|
||
the vertical columns in the tree view. It needs to know the name of
|
||
the column to label for the user, what type of cell renderer to use,
|
||
and which piece of data to retrieve from the model for a given row.
|
||
</p>
|
||
<div class="informalexample"><pre class="programlisting">
|
||
GtkCellRenderer *renderer;
|
||
GtkTreeViewColumn *column;
|
||
|
||
renderer = gtk_cell_renderer_text_new ();
|
||
column = gtk_tree_view_column_new_with_attributes ("Author",
|
||
renderer,
|
||
"text", AUTHOR_COLUMN,
|
||
NULL);
|
||
gtk_tree_view_append_column (GTK_TREE_VIEW (tree), column);
|
||
</pre></div>
|
||
<p>
|
||
At this point, all the steps in creating a displayable tree have been
|
||
covered. The model is created, data is stored in it, a tree view is
|
||
created and columns are added to it.
|
||
</p>
|
||
</div>
|
||
<hr>
|
||
<div class="refsect2">
|
||
<a name="id-1.3.12.2.5.5"></a><h3>Selection handling</h3>
|
||
<p>
|
||
Most applications will need to not only deal with displaying data, but
|
||
also receiving input events from users. To do this, simply get a
|
||
reference to a selection object and connect to the
|
||
<a class="link" href="GtkTreeSelection.html#GtkTreeSelection-changed" title="The “changed” signal"><span class="type">“changed”</span></a> signal.
|
||
</p>
|
||
<div class="informalexample"><pre class="programlisting">
|
||
/* Prototype for selection handler callback */
|
||
static void tree_selection_changed_cb (GtkTreeSelection *selection, gpointer data);
|
||
|
||
/* Setup the selection handler */
|
||
GtkTreeSelection *select;
|
||
|
||
select = gtk_tree_view_get_selection (GTK_TREE_VIEW (tree));
|
||
gtk_tree_selection_set_mode (select, GTK_SELECTION_SINGLE);
|
||
g_signal_connect (G_OBJECT (select), "changed",
|
||
G_CALLBACK (tree_selection_changed_cb),
|
||
NULL);
|
||
</pre></div>
|
||
<p>
|
||
Then to retrieve data for the row selected:
|
||
</p>
|
||
<div class="informalexample"><pre class="programlisting">
|
||
static void
|
||
tree_selection_changed_cb (GtkTreeSelection *selection, gpointer data)
|
||
{
|
||
GtkTreeIter iter;
|
||
GtkTreeModel *model;
|
||
gchar *author;
|
||
|
||
if (gtk_tree_selection_get_selected (selection, &model, &iter))
|
||
{
|
||
gtk_tree_model_get (model, &iter, AUTHOR_COLUMN, &author, -1);
|
||
|
||
g_print ("You selected a book by %s\n", author);
|
||
|
||
g_free (author);
|
||
}
|
||
}
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
<div class="refsect1">
|
||
<a name="id-1.3.12.2.6"></a><h2>Simple Example</h2>
|
||
<p>
|
||
Here is a simple example of using a <a class="link" href="GtkTreeView.html" title="GtkTreeView"><span class="type">GtkTreeView</span></a> widget in context
|
||
of the other widgets. It simply creates a simple model and view,
|
||
and puts them together. Note that the model is never populated
|
||
with data — that is left as an exercise for the reader.
|
||
More information can be found on this in the <a class="link" href="GtkTreeModel.html" title="GtkTreeModel"><span class="type">GtkTreeModel</span></a> section.
|
||
</p>
|
||
<div class="informalexample"><pre class="programlisting">
|
||
enum
|
||
{
|
||
TITLE_COLUMN,
|
||
AUTHOR_COLUMN,
|
||
CHECKED_COLUMN,
|
||
N_COLUMNS
|
||
};
|
||
|
||
void
|
||
setup_tree (void)
|
||
{
|
||
GtkTreeStore *store;
|
||
GtkWidget *tree;
|
||
GtkTreeViewColumn *column;
|
||
GtkCellRenderer *renderer;
|
||
|
||
/* Create a model. We are using the store model for now, though we
|
||
* could use any other GtkTreeModel */
|
||
store = gtk_tree_store_new (N_COLUMNS,
|
||
G_TYPE_STRING,
|
||
G_TYPE_STRING,
|
||
G_TYPE_BOOLEAN);
|
||
|
||
/* custom function to fill the model with data */
|
||
populate_tree_model (store);
|
||
|
||
/* Create a view */
|
||
tree = gtk_tree_view_new_with_model (GTK_TREE_MODEL (store));
|
||
|
||
/* The view now holds a reference. We can get rid of our own
|
||
* reference */
|
||
g_object_unref (G_OBJECT (store));
|
||
|
||
/* Create a cell render and arbitrarily make it red for demonstration
|
||
* purposes */
|
||
renderer = gtk_cell_renderer_text_new ();
|
||
g_object_set (G_OBJECT (renderer),
|
||
"foreground", "red",
|
||
NULL);
|
||
|
||
/* Create a column, associating the "text" attribute of the
|
||
* cell_renderer to the first column of the model */
|
||
column = gtk_tree_view_column_new_with_attributes ("Author", renderer,
|
||
"text", AUTHOR_COLUMN,
|
||
NULL);
|
||
|
||
/* Add the column to the view. */
|
||
gtk_tree_view_append_column (GTK_TREE_VIEW (tree), column);
|
||
|
||
/* Second column.. title of the book. */
|
||
renderer = gtk_cell_renderer_text_new ();
|
||
column = gtk_tree_view_column_new_with_attributes ("Title",
|
||
renderer,
|
||
"text", TITLE_COLUMN,
|
||
NULL);
|
||
gtk_tree_view_append_column (GTK_TREE_VIEW (tree), column);
|
||
|
||
/* Last column.. whether a book is checked out. */
|
||
renderer = gtk_cell_renderer_toggle_new ();
|
||
column = gtk_tree_view_column_new_with_attributes ("Checked out",
|
||
renderer,
|
||
"active", CHECKED_COLUMN,
|
||
NULL);
|
||
gtk_tree_view_append_column (GTK_TREE_VIEW (tree), column);
|
||
|
||
/* Now we can manipulate the view just like any other GTK widget */
|
||
...
|
||
}
|
||
</pre></div>
|
||
<p>
|
||
</p>
|
||
</div>
|
||
</div>
|
||
<div class="footer">
|
||
<hr>Generated by GTK-Doc V1.27</div>
|
||
</body>
|
||
</html> |