|
5
by JazzyNico
Adding gtk2 libraries. |
1 |
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
2 |
<html> |
|
3 |
<head> |
|
4 |
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> |
|
5 |
<title>Tree and List Widget Overview</title> |
|
6 |
<meta name="generator" content="DocBook XSL Stylesheets V1.77.1"> |
|
7 |
<link rel="home" href="index.html" title="GTK+ 2 Reference Manual"> |
|
8 |
<link rel="up" href="TreeWidgetObjects.html" title="Tree, List and Icon Grid Widgets"> |
|
9 |
<link rel="prev" href="TreeWidgetObjects.html" title="Tree, List and Icon Grid Widgets"> |
|
10 |
<link rel="next" href="GtkTreeModel.html" title="GtkTreeModel"> |
|
11 |
<meta name="generator" content="GTK-Doc V1.18 (XML mode)"> |
|
12 |
<link rel="stylesheet" href="style.css" type="text/css"> |
|
13 |
</head> |
|
14 |
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> |
|
15 |
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle"> |
|
16 |
<td><a accesskey="p" href="TreeWidgetObjects.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td> |
|
17 |
<td><a accesskey="u" href="TreeWidgetObjects.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td> |
|
18 |
<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td> |
|
19 |
<th width="100%" align="center">GTK+ 2 Reference Manual</th> |
|
20 |
<td><a accesskey="n" href="GtkTreeModel.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td> |
|
21 |
</tr></table> |
|
22 |
<div class="refentry"> |
|
23 |
<a name="TreeWidget"></a><div class="titlepage"></div> |
|
24 |
<div class="refnamediv"><table width="100%"><tr> |
|
25 |
<td valign="top"> |
|
26 |
<h2><span class="refentrytitle">Tree and List Widget Overview</span></h2> |
|
27 |
<p>Tree and List Widget Overview — Overview of GtkTreeModel, GtkTreeView, and friends</p> |
|
28 |
</td> |
|
29 |
<td valign="top" align="right"></td> |
|
30 |
</tr></table></div> |
|
31 |
<div class="refsect1"> |
|
32 |
<a name="idp44269680"></a><h2>Overview</h2> |
|
33 |
<p> |
|
34 |
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 |
|
35 |
conjunction with the <a class="link" href="GtkTreeView.html" title="GtkTreeView"><span class="type">GtkTreeView</span></a> widget. This widget is |
|
36 |
designed around a <em class="firstterm">Model/View/Controller</em> |
|
37 |
design and consists of four major parts: |
|
38 |
</p> |
|
39 |
<table border="0" summary="Simple list" class="simplelist"> |
|
40 |
<tr><td>The tree view widget (<span class="structname">GtkTreeView</span>)</td></tr> |
|
41 |
<tr><td>The view column (<span class="structname">GtkTreeViewColumn</span>)</td></tr> |
|
42 |
<tr><td>The cell renderers (<span class="structname">GtkCellRenderer</span> etc.)</td></tr> |
|
43 |
<tr><td>The model interface (<span class="structname">GtkTreeModel</span>)</td></tr> |
|
44 |
</table> |
|
45 |
<p> |
|
46 |
The <span class="emphasis"><em>View</em></span> is composed of the first three |
|
47 |
objects, while the last is the <span class="emphasis"><em>Model</em></span>. One |
|
48 |
of the prime benefits of the MVC design is that multiple views |
|
49 |
can be created of a single model. For example, a model mapping |
|
50 |
the file system could be created for a file manager. Many views |
|
51 |
could be created to display various parts of the file system, |
|
52 |
but only one copy need be kept in memory. |
|
53 |
</p> |
|
54 |
<p> |
|
55 |
The purpose of the cell renderers is to provide extensibility to the |
|
56 |
widget and to allow multiple ways of rendering the same type of data. |
|
57 |
For example, consider how to render a boolean variable. Should it |
|
58 |
render it as a string of "True" or "False", "On" or "Off", or should |
|
59 |
it be rendered as a checkbox? |
|
60 |
</p> |
|
61 |
</div> |
|
62 |
<div class="refsect1"> |
|
63 |
<a name="idp39166688"></a><h2>Creating a model</h2> |
|
64 |
<p> |
|
65 |
GTK+ provides two simple models that can be used: the <a class="link" href="GtkListStore.html" title="GtkListStore"><span class="type">GtkListStore</span></a> |
|
66 |
and the <a class="link" href="GtkTreeStore.html" title="GtkTreeStore"><span class="type">GtkTreeStore</span></a>. GtkListStore is used to model list widgets, |
|
67 |
while the GtkTreeStore models trees. It is possible to develop a new |
|
68 |
type of model, but the existing models should be satisfactory for all |
|
69 |
but the most specialized of situations. Creating the model is quite |
|
70 |
simple: |
|
71 |
</p> |
|
72 |
<div class="informalexample"> |
|
73 |
<table class="listing_frame" border="0" cellpadding="0" cellspacing="0"> |
|
74 |
<tbody> |
|
75 |
<tr> |
|
76 |
<td class="listing_lines" align="right"><pre>1</pre></td> |
|
77 |
<td class="listing_code"><pre class="programlisting"><span class="usertype">GtkListStore</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">store </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="GtkListStore.html#gtk-list-store-new">gtk_list_store_new</a></span><span class="normal"> </span><span class="symbol">(</span><span class="number">2</span><span class="symbol">,</span><span class="normal"> G_TYPE_STRING</span><span class="symbol">,</span><span class="normal"> G_TYPE_BOOLEAN</span><span class="symbol">);</span></pre></td> |
|
78 |
</tr> |
|
79 |
</tbody> |
|
80 |
</table> |
|
81 |
</div> |
|
82 |
||
83 |
<p> |
|
84 |
This creates a list store with two columns: a string column and a boolean |
|
85 |
column. Typically the 2 is never passed directly like that; usually an |
|
86 |
enum is created wherein the different columns are enumerated, followed by |
|
87 |
a token that represents the total number of columns. The next example will |
|
88 |
illustrate this, only using a tree store instead of a list store. Creating |
|
89 |
a tree store operates almost exactly the same. |
|
90 |
</p> |
|
91 |
<div class="informalexample"> |
|
92 |
<table class="listing_frame" border="0" cellpadding="0" cellspacing="0"> |
|
93 |
<tbody> |
|
94 |
<tr> |
|
95 |
<td class="listing_lines" align="right"><pre>1 |
|
96 |
2 |
|
97 |
3 |
|
98 |
4 |
|
99 |
5 |
|
100 |
6 |
|
101 |
7 |
|
102 |
8 |
|
103 |
9 |
|
104 |
10 |
|
105 |
11 |
|
106 |
12</pre></td> |
|
107 |
<td class="listing_code"><pre class="programlisting"><span class="keyword">enum</span> |
|
108 |
<span class="cbracket">{</span> |
|
109 |
<span class="normal"> TITLE_COLUMN</span><span class="symbol">,</span> |
|
110 |
<span class="normal"> AUTHOR_COLUMN</span><span class="symbol">,</span> |
|
111 |
<span class="normal"> CHECKED_COLUMN</span><span class="symbol">,</span> |
|
112 |
<span class="normal"> N_COLUMNS</span> |
|
113 |
<span class="cbracket">}</span><span class="symbol">;</span> |
|
114 |
||
115 |
<span class="usertype">GtkTreeStore</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">store </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="GtkTreeStore.html#gtk-tree-store-new">gtk_tree_store_new</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">N_COLUMNS</span><span class="symbol">,</span><span class="normal"> </span><span class="comment">/* Total number of columns */</span> |
|
116 |
<span class="normal"> G_TYPE_STRING</span><span class="symbol">,</span><span class="normal"> </span><span class="comment">/* Book title */</span> |
|
117 |
<span class="normal"> G_TYPE_STRING</span><span class="symbol">,</span><span class="normal"> </span><span class="comment">/* Author */</span> |
|
118 |
<span class="normal"> G_TYPE_BOOLEAN</span><span class="symbol">);</span><span class="normal"> </span><span class="comment">/* Is checked out? */</span></pre></td> |
|
119 |
</tr> |
|
120 |
</tbody> |
|
121 |
</table> |
|
122 |
</div> |
|
123 |
||
124 |
<p> |
|
125 |
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 |
|
126 |
<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 |
|
127 |
created. To do this, a <a class="link" href="GtkTreeModel.html#GtkTreeIter"><span class="type">GtkTreeIter</span></a> must be acquired. The iterator |
|
128 |
points to the location where data will be added. |
|
129 |
</p> |
|
130 |
<p> |
|
131 |
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 |
|
132 |
apply data to the part of the model that the iterator points to. |
|
133 |
Consider the following example: |
|
134 |
</p> |
|
135 |
<div class="informalexample"> |
|
136 |
<table class="listing_frame" border="0" cellpadding="0" cellspacing="0"> |
|
137 |
<tbody> |
|
138 |
<tr> |
|
139 |
<td class="listing_lines" align="right"><pre>1 |
|
140 |
2 |
|
141 |
3 |
|
142 |
4 |
|
143 |
5 |
|
144 |
6 |
|
145 |
7 |
|
146 |
8 |
|
147 |
9</pre></td> |
|
148 |
<td class="listing_code"><pre class="programlisting"><span class="usertype">GtkTreeIter</span><span class="normal"> iter</span><span class="symbol">;</span> |
|
149 |
||
150 |
<span class="function"><a href="GtkTreeStore.html#gtk-tree-store-append">gtk_tree_store_append</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">store</span><span class="symbol">,</span><span class="normal"> </span><span class="symbol">&</span><span class="normal">iter</span><span class="symbol">,</span><span class="normal"> <a href="/usr/share/gtk-doc/html/liboil/liboil-liboiljunk.html#NULL:CAPS">NULL</a></span><span class="symbol">);</span><span class="normal"> </span><span class="comment">/* Acquire an iterator */</span> |
|
151 |
||
152 |
<span class="function"><a href="GtkTreeStore.html#gtk-tree-store-set">gtk_tree_store_set</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">store</span><span class="symbol">,</span><span class="normal"> </span><span class="symbol">&</span><span class="normal">iter</span><span class="symbol">,</span> |
|
153 |
<span class="normal"> TITLE_COLUMN</span><span class="symbol">,</span><span class="normal"> </span><span class="string">"The Principle of Reason"</span><span class="symbol">,</span> |
|
154 |
<span class="normal"> AUTHOR_COLUMN</span><span class="symbol">,</span><span class="normal"> </span><span class="string">"Martin Heidegger"</span><span class="symbol">,</span> |
|
155 |
<span class="normal"> CHECKED_COLUMN</span><span class="symbol">,</span><span class="normal"> FALSE</span><span class="symbol">,</span> |
|
156 |
<span class="normal"> </span><span class="symbol">-</span><span class="number">1</span><span class="symbol">);</span></pre></td> |
|
157 |
</tr> |
|
158 |
</tbody> |
|
159 |
</table> |
|
160 |
</div> |
|
161 |
||
162 |
<p> |
|
163 |
Notice that the last argument is -1. This is always done because |
|
164 |
this is a variable-argument function and it needs to know when to stop |
|
165 |
processing arguments. It can be used to set the data in any or all |
|
166 |
columns in a given row. |
|
167 |
</p> |
|
168 |
<p> |
|
169 |
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 |
|
170 |
is used to add a row to a GtkTreeStore as a child of an existing row. This |
|
171 |
means that the new row will only be visible when its parent is visible and |
|
172 |
in its expanded state. Consider the following example: |
|
173 |
</p> |
|
174 |
<div class="informalexample"> |
|
175 |
<table class="listing_frame" border="0" cellpadding="0" cellspacing="0"> |
|
176 |
<tbody> |
|
177 |
<tr> |
|
178 |
<td class="listing_lines" align="right"><pre>1 |
|
179 |
2 |
|
180 |
3 |
|
181 |
4 |
|
182 |
5 |
|
183 |
6 |
|
184 |
7 |
|
185 |
8 |
|
186 |
9 |
|
187 |
10 |
|
188 |
11 |
|
189 |
12 |
|
190 |
13 |
|
191 |
14 |
|
192 |
15 |
|
193 |
16 |
|
194 |
17 |
|
195 |
18 |
|
196 |
19 |
|
197 |
20 |
|
198 |
21 |
|
199 |
22 |
|
200 |
23 |
|
201 |
24</pre></td> |
|
202 |
<td class="listing_code"><pre class="programlisting"><span class="usertype">GtkTreeIter</span><span class="normal"> iter1</span><span class="symbol">;</span><span class="normal"> </span><span class="comment">/* Parent iter */</span> |
|
203 |
<span class="usertype">GtkTreeIter</span><span class="normal"> iter2</span><span class="symbol">;</span><span class="normal"> </span><span class="comment">/* Child iter */</span> |
|
204 |
||
205 |
<span class="function"><a href="GtkTreeStore.html#gtk-tree-store-append">gtk_tree_store_append</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">store</span><span class="symbol">,</span><span class="normal"> </span><span class="symbol">&</span><span class="normal">iter1</span><span class="symbol">,</span><span class="normal"> <a href="/usr/share/gtk-doc/html/liboil/liboil-liboiljunk.html#NULL:CAPS">NULL</a></span><span class="symbol">);</span><span class="normal"> </span><span class="comment">/* Acquire a top-level iterator */</span> |
|
206 |
<span class="function"><a href="GtkTreeStore.html#gtk-tree-store-set">gtk_tree_store_set</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">store</span><span class="symbol">,</span><span class="normal"> </span><span class="symbol">&</span><span class="normal">iter1</span><span class="symbol">,</span> |
|
207 |
<span class="normal"> TITLE_COLUMN</span><span class="symbol">,</span><span class="normal"> </span><span class="string">"The Art of Computer Programming"</span><span class="symbol">,</span> |
|
208 |
<span class="normal"> AUTHOR_COLUMN</span><span class="symbol">,</span><span class="normal"> </span><span class="string">"Donald E. Knuth"</span><span class="symbol">,</span> |
|
209 |
<span class="normal"> CHECKED_COLUMN</span><span class="symbol">,</span><span class="normal"> FALSE</span><span class="symbol">,</span> |
|
210 |
<span class="normal"> </span><span class="symbol">-</span><span class="number">1</span><span class="symbol">);</span> |
|
211 |
||
212 |
<span class="function"><a href="GtkTreeStore.html#gtk-tree-store-append">gtk_tree_store_append</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">store</span><span class="symbol">,</span><span class="normal"> </span><span class="symbol">&</span><span class="normal">iter2</span><span class="symbol">,</span><span class="normal"> </span><span class="symbol">&</span><span class="normal">iter1</span><span class="symbol">);</span><span class="normal"> </span><span class="comment">/* Acquire a child iterator */</span> |
|
213 |
<span class="function"><a href="GtkTreeStore.html#gtk-tree-store-set">gtk_tree_store_set</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">store</span><span class="symbol">,</span><span class="normal"> </span><span class="symbol">&</span><span class="normal">iter2</span><span class="symbol">,</span> |
|
214 |
<span class="normal"> TITLE_COLUMN</span><span class="symbol">,</span><span class="normal"> </span><span class="string">"Volume 1: Fundamental Algorithms"</span><span class="symbol">,</span> |
|
215 |
<span class="normal"> </span><span class="symbol">-</span><span class="number">1</span><span class="symbol">);</span> |
|
216 |
||
217 |
<span class="function"><a href="GtkTreeStore.html#gtk-tree-store-append">gtk_tree_store_append</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">store</span><span class="symbol">,</span><span class="normal"> </span><span class="symbol">&</span><span class="normal">iter2</span><span class="symbol">,</span><span class="normal"> </span><span class="symbol">&</span><span class="normal">iter1</span><span class="symbol">);</span> |
|
218 |
<span class="function"><a href="GtkTreeStore.html#gtk-tree-store-set">gtk_tree_store_set</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">store</span><span class="symbol">,</span><span class="normal"> </span><span class="symbol">&</span><span class="normal">iter2</span><span class="symbol">,</span> |
|
219 |
<span class="normal"> TITLE_COLUMN</span><span class="symbol">,</span><span class="normal"> </span><span class="string">"Volume 2: Seminumerical Algorithms"</span><span class="symbol">,</span> |
|
220 |
<span class="normal"> </span><span class="symbol">-</span><span class="number">1</span><span class="symbol">);</span> |
|
221 |
||
222 |
<span class="function"><a href="GtkTreeStore.html#gtk-tree-store-append">gtk_tree_store_append</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">store</span><span class="symbol">,</span><span class="normal"> </span><span class="symbol">&</span><span class="normal">iter2</span><span class="symbol">,</span><span class="normal"> </span><span class="symbol">&</span><span class="normal">iter1</span><span class="symbol">);</span> |
|
223 |
<span class="function"><a href="GtkTreeStore.html#gtk-tree-store-set">gtk_tree_store_set</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">store</span><span class="symbol">,</span><span class="normal"> </span><span class="symbol">&</span><span class="normal">iter2</span><span class="symbol">,</span> |
|
224 |
<span class="normal"> TITLE_COLUMN</span><span class="symbol">,</span><span class="normal"> </span><span class="string">"Volume 3: Sorting and Searching"</span><span class="symbol">,</span> |
|
225 |
<span class="normal"> </span><span class="symbol">-</span><span class="number">1</span><span class="symbol">);</span></pre></td> |
|
226 |
</tr> |
|
227 |
</tbody> |
|
228 |
</table> |
|
229 |
</div> |
|
230 |
||
231 |
</div> |
|
232 |
<div class="refsect1"> |
|
233 |
<a name="idp39887168"></a><h2>Creating the view component</h2> |
|
234 |
<p> |
|
235 |
While there are several different models to choose from, there is |
|
236 |
only one view widget to deal with. It works with either the list |
|
237 |
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 |
|
238 |
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 |
|
239 |
from. |
|
240 |
</p> |
|
241 |
<div class="informalexample"> |
|
242 |
<table class="listing_frame" border="0" cellpadding="0" cellspacing="0"> |
|
243 |
<tbody> |
|
244 |
<tr> |
|
245 |
<td class="listing_lines" align="right"><pre>1 |
|
246 |
2 |
|
247 |
3</pre></td> |
|
248 |
<td class="listing_code"><pre class="programlisting"><span class="usertype">GtkWidget</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">tree</span><span class="symbol">;</span> |
|
249 |
||
250 |
<span class="normal">tree </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="GtkTreeView.html#gtk-tree-view-new-with-model">gtk_tree_view_new_with_model</a></span><span class="normal"> </span><span class="symbol">(</span><span class="function">GTK_TREE_MODEL</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">store</span><span class="symbol">));</span></pre></td> |
|
251 |
</tr> |
|
252 |
</tbody> |
|
253 |
</table> |
|
254 |
</div> |
|
255 |
||
256 |
<div class="refsect2"> |
|
257 |
<a name="idp10108672"></a><h3>Columns and cell renderers</h3> |
|
258 |
<p> |
|
259 |
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 |
|
260 |
to display the model. It does this with columns and cell renderers. |
|
261 |
</p> |
|
262 |
<p> |
|
263 |
Cell renderers are used to draw the data in the tree model in a |
|
264 |
way. There are a number of cell renderers that come with GTK+ 2.x, |
|
265 |
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 |
|
266 |
the <a class="link" href="GtkCellRendererToggle.html" title="GtkCellRendererToggle"><span class="type">GtkCellRendererToggle</span></a>. |
|
267 |
It is relatively easy to write a custom renderer. |
|
268 |
</p> |
|
269 |
<p> |
|
270 |
A <a class="link" href="GtkTreeViewColumn.html" title="GtkTreeViewColumn"><span class="type">GtkTreeViewColumn</span></a> is the object that GtkTreeView uses to organize |
|
271 |
the vertical columns in the tree view. It needs to know the name of |
|
272 |
the column to label for the user, what type of cell renderer to use, |
|
273 |
and which piece of data to retrieve from the model for a given row. |
|
274 |
</p> |
|
275 |
<div class="informalexample"> |
|
276 |
<table class="listing_frame" border="0" cellpadding="0" cellspacing="0"> |
|
277 |
<tbody> |
|
278 |
<tr> |
|
279 |
<td class="listing_lines" align="right"><pre>1 |
|
280 |
2 |
|
281 |
3 |
|
282 |
4 |
|
283 |
5 |
|
284 |
6 |
|
285 |
7 |
|
286 |
8 |
|
287 |
9</pre></td> |
|
288 |
<td class="listing_code"><pre class="programlisting"><span class="usertype">GtkCellRenderer</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">renderer</span><span class="symbol">;</span> |
|
289 |
<span class="usertype">GtkTreeViewColumn</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">column</span><span class="symbol">;</span> |
|
290 |
||
291 |
<span class="normal">renderer </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="GtkCellRendererText.html#gtk-cell-renderer-text-new">gtk_cell_renderer_text_new</a></span><span class="normal"> </span><span class="symbol">();</span> |
|
292 |
<span class="normal">column </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="GtkTreeViewColumn.html#gtk-tree-view-column-new-with-attributes">gtk_tree_view_column_new_with_attributes</a></span><span class="normal"> </span><span class="symbol">(</span><span class="string">"Author"</span><span class="symbol">,</span> |
|
293 |
<span class="normal"> renderer</span><span class="symbol">,</span> |
|
294 |
<span class="normal"> </span><span class="string">"text"</span><span class="symbol">,</span><span class="normal"> AUTHOR_COLUMN</span><span class="symbol">,</span> |
|
295 |
<span class="normal"> <a href="/usr/share/gtk-doc/html/liboil/liboil-liboiljunk.html#NULL:CAPS">NULL</a></span><span class="symbol">);</span> |
|
296 |
<span class="function"><a href="GtkTreeView.html#gtk-tree-view-append-column">gtk_tree_view_append_column</a></span><span class="normal"> </span><span class="symbol">(</span><span class="function">GTK_TREE_VIEW</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">tree</span><span class="symbol">),</span><span class="normal"> column</span><span class="symbol">);</span></pre></td> |
|
297 |
</tr> |
|
298 |
</tbody> |
|
299 |
</table> |
|
300 |
</div> |
|
301 |
||
302 |
<p> |
|
303 |
At this point, all the steps in creating a displayable tree have been |
|
304 |
covered. The model is created, data is stored in it, a tree view is |
|
305 |
created and columns are added to it. |
|
306 |
</p> |
|
307 |
</div> |
|
308 |
<hr> |
|
309 |
<div class="refsect2"> |
|
310 |
<a name="idp12476528"></a><h3>Selection handling</h3> |
|
311 |
<p> |
|
312 |
Most applications will need to not only deal with displaying data, but |
|
313 |
also receiving input events from users. To do this, simply get a |
|
314 |
reference to a selection object and connect to the |
|
315 |
<a class="link" href="GtkTreeSelection.html#GtkTreeSelection-changed" title='The "changed" signal'><span class="type">"changed"</span></a> signal. |
|
316 |
</p> |
|
317 |
<div class="informalexample"> |
|
318 |
<table class="listing_frame" border="0" cellpadding="0" cellspacing="0"> |
|
319 |
<tbody> |
|
320 |
<tr> |
|
321 |
<td class="listing_lines" align="right"><pre>1 |
|
322 |
2 |
|
323 |
3 |
|
324 |
4 |
|
325 |
5 |
|
326 |
6 |
|
327 |
7 |
|
328 |
8 |
|
329 |
9 |
|
330 |
10 |
|
331 |
11</pre></td> |
|
332 |
<td class="listing_code"><pre class="programlisting"><span class="comment">/* Prototype for selection handler callback */</span> |
|
333 |
<span class="keyword">static</span><span class="normal"> </span><span class="type">void</span><span class="normal"> </span><span class="function">tree_selection_changed_cb</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">GtkTreeSelection</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">selection</span><span class="symbol">,</span><span class="normal"> </span><span class="usertype">gpointer</span><span class="normal"> data</span><span class="symbol">);</span> |
|
334 |
||
335 |
<span class="comment">/* Setup the selection handler */</span> |
|
336 |
<span class="usertype">GtkTreeSelection</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">select</span><span class="symbol">;</span> |
|
337 |
||
338 |
<span class="normal">select </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="GtkTreeView.html#gtk-tree-view-get-selection">gtk_tree_view_get_selection</a></span><span class="normal"> </span><span class="symbol">(</span><span class="function">GTK_TREE_VIEW</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">tree</span><span class="symbol">));</span> |
|
339 |
<span class="function"><a href="GtkTreeSelection.html#gtk-tree-selection-set-mode">gtk_tree_selection_set_mode</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">select</span><span class="symbol">,</span><span class="normal"> <a href="gtk2-Standard-Enumerations.html#GTK-SELECTION-SINGLE:CAPS">GTK_SELECTION_SINGLE</a></span><span class="symbol">);</span> |
|
340 |
<span class="function">g_signal_connect</span><span class="normal"> </span><span class="symbol">(</span><span class="function">G_OBJECT</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">select</span><span class="symbol">),</span><span class="normal"> </span><span class="string">"changed"</span><span class="symbol">,</span> |
|
341 |
<span class="normal"> </span><span class="function">G_CALLBACK</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">tree_selection_changed_cb</span><span class="symbol">),</span> |
|
342 |
<span class="normal"> <a href="/usr/share/gtk-doc/html/liboil/liboil-liboiljunk.html#NULL:CAPS">NULL</a></span><span class="symbol">);</span></pre></td> |
|
343 |
</tr> |
|
344 |
</tbody> |
|
345 |
</table> |
|
346 |
</div> |
|
347 |
||
348 |
<p> |
|
349 |
Then to retrieve data for the row selected: |
|
350 |
</p> |
|
351 |
<div class="informalexample"> |
|
352 |
<table class="listing_frame" border="0" cellpadding="0" cellspacing="0"> |
|
353 |
<tbody> |
|
354 |
<tr> |
|
355 |
<td class="listing_lines" align="right"><pre>1 |
|
356 |
2 |
|
357 |
3 |
|
358 |
4 |
|
359 |
5 |
|
360 |
6 |
|
361 |
7 |
|
362 |
8 |
|
363 |
9 |
|
364 |
10 |
|
365 |
11 |
|
366 |
12 |
|
367 |
13 |
|
368 |
14 |
|
369 |
15 |
|
370 |
16</pre></td> |
|
371 |
<td class="listing_code"><pre class="programlisting"><span class="keyword">static</span><span class="normal"> </span><span class="type">void</span> |
|
372 |
<span class="function">tree_selection_changed_cb</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">GtkTreeSelection</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">selection</span><span class="symbol">,</span><span class="normal"> </span><span class="usertype">gpointer</span><span class="normal"> data</span><span class="symbol">)</span> |
|
373 |
<span class="cbracket">{</span> |
|
374 |
<span class="normal"> </span><span class="usertype">GtkTreeIter</span><span class="normal"> iter</span><span class="symbol">;</span> |
|
375 |
<span class="normal"> </span><span class="usertype">GtkTreeModel</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">model</span><span class="symbol">;</span> |
|
376 |
<span class="normal"> </span><span class="usertype">gchar</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">author</span><span class="symbol">;</span> |
|
377 |
||
378 |
<span class="normal"> </span><span class="keyword">if</span><span class="normal"> </span><span class="symbol">(</span><span class="function"><a href="GtkTreeSelection.html#gtk-tree-selection-get-selected">gtk_tree_selection_get_selected</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">selection</span><span class="symbol">,</span><span class="normal"> </span><span class="symbol">&</span><span class="normal">model</span><span class="symbol">,</span><span class="normal"> </span><span class="symbol">&</span><span class="normal">iter</span><span class="symbol">))</span> |
|
379 |
<span class="normal"> </span><span class="cbracket">{</span> |
|
380 |
<span class="normal"> </span><span class="function"><a href="GtkTreeModel.html#gtk-tree-model-get">gtk_tree_model_get</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">model</span><span class="symbol">,</span><span class="normal"> </span><span class="symbol">&</span><span class="normal">iter</span><span class="symbol">,</span><span class="normal"> AUTHOR_COLUMN</span><span class="symbol">,</span><span class="normal"> </span><span class="symbol">&</span><span class="normal">author</span><span class="symbol">,</span><span class="normal"> </span><span class="symbol">-</span><span class="number">1</span><span class="symbol">);</span> |
|
381 |
||
382 |
<span class="normal"> </span><span class="function">g_print</span><span class="normal"> </span><span class="symbol">(</span><span class="string">"You selected a book by %s</span><span class="specialchar">\n</span><span class="string">"</span><span class="symbol">,</span><span class="normal"> author</span><span class="symbol">);</span> |
|
383 |
||
384 |
<span class="normal"> </span><span class="function">g_free</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">author</span><span class="symbol">);</span> |
|
385 |
<span class="normal"> </span><span class="cbracket">}</span> |
|
386 |
<span class="cbracket">}</span></pre></td> |
|
387 |
</tr> |
|
388 |
</tbody> |
|
389 |
</table> |
|
390 |
</div> |
|
391 |
||
392 |
</div> |
|
393 |
</div> |
|
394 |
<div class="refsect1"> |
|
395 |
<a name="idp38399024"></a><h2>Simple Example</h2> |
|
396 |
<p> |
|
397 |
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 |
|
398 |
of the other widgets. It simply creates a simple model and view, |
|
399 |
and puts them together. Note that the model is never populated |
|
400 |
with data — that is left as an exercise for the reader. |
|
401 |
More information can be found on this in the <a class="link" href="GtkTreeModel.html" title="GtkTreeModel"><span class="type">GtkTreeModel</span></a> section. |
|
402 |
</p> |
|
403 |
<div class="informalexample"> |
|
404 |
<table class="listing_frame" border="0" cellpadding="0" cellspacing="0"> |
|
405 |
<tbody> |
|
406 |
<tr> |
|
407 |
<td class="listing_lines" align="right"><pre>1 |
|
408 |
2 |
|
409 |
3 |
|
410 |
4 |
|
411 |
5 |
|
412 |
6 |
|
413 |
7 |
|
414 |
8 |
|
415 |
9 |
|
416 |
10 |
|
417 |
11 |
|
418 |
12 |
|
419 |
13 |
|
420 |
14 |
|
421 |
15 |
|
422 |
16 |
|
423 |
17 |
|
424 |
18 |
|
425 |
19 |
|
426 |
20 |
|
427 |
21 |
|
428 |
22 |
|
429 |
23 |
|
430 |
24 |
|
431 |
25 |
|
432 |
26 |
|
433 |
27 |
|
434 |
28 |
|
435 |
29 |
|
436 |
30 |
|
437 |
31 |
|
438 |
32 |
|
439 |
33 |
|
440 |
34 |
|
441 |
35 |
|
442 |
36 |
|
443 |
37 |
|
444 |
38 |
|
445 |
39 |
|
446 |
40 |
|
447 |
41 |
|
448 |
42 |
|
449 |
43 |
|
450 |
44 |
|
451 |
45 |
|
452 |
46 |
|
453 |
47 |
|
454 |
48 |
|
455 |
49 |
|
456 |
50 |
|
457 |
51 |
|
458 |
52 |
|
459 |
53 |
|
460 |
54 |
|
461 |
55 |
|
462 |
56 |
|
463 |
57 |
|
464 |
58 |
|
465 |
59 |
|
466 |
60 |
|
467 |
61 |
|
468 |
62 |
|
469 |
63 |
|
470 |
64 |
|
471 |
65 |
|
472 |
66 |
|
473 |
67 |
|
474 |
68</pre></td> |
|
475 |
<td class="listing_code"><pre class="programlisting"><span class="keyword">enum</span> |
|
476 |
<span class="cbracket">{</span> |
|
477 |
<span class="normal"> TITLE_COLUMN</span><span class="symbol">,</span> |
|
478 |
<span class="normal"> AUTHOR_COLUMN</span><span class="symbol">,</span> |
|
479 |
<span class="normal"> CHECKED_COLUMN</span><span class="symbol">,</span> |
|
480 |
<span class="normal"> N_COLUMNS</span> |
|
481 |
<span class="cbracket">}</span><span class="symbol">;</span> |
|
482 |
||
483 |
<span class="type">void</span> |
|
484 |
<span class="function">setup_tree</span><span class="normal"> </span><span class="symbol">(</span><span class="type">void</span><span class="symbol">)</span> |
|
485 |
<span class="cbracket">{</span> |
|
486 |
<span class="normal"> </span><span class="usertype">GtkTreeStore</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">store</span><span class="symbol">;</span> |
|
487 |
<span class="normal"> </span><span class="usertype">GtkWidget</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">tree</span><span class="symbol">;</span> |
|
488 |
<span class="normal"> </span><span class="usertype">GtkTreeViewColumn</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">column</span><span class="symbol">;</span> |
|
489 |
<span class="normal"> </span><span class="usertype">GtkCellRenderer</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">renderer</span><span class="symbol">;</span> |
|
490 |
||
491 |
<span class="normal"> </span><span class="comment">/* Create a model. We are using the store model for now, though we</span> |
|
492 |
<span class="comment"> * could use any other GtkTreeModel */</span> |
|
493 |
<span class="normal"> store </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="GtkTreeStore.html#gtk-tree-store-new">gtk_tree_store_new</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">N_COLUMNS</span><span class="symbol">,</span> |
|
494 |
<span class="normal"> G_TYPE_STRING</span><span class="symbol">,</span> |
|
495 |
<span class="normal"> G_TYPE_STRING</span><span class="symbol">,</span> |
|
496 |
<span class="normal"> G_TYPE_BOOLEAN</span><span class="symbol">);</span> |
|
497 |
||
498 |
<span class="normal"> </span><span class="comment">/* custom function to fill the model with data */</span> |
|
499 |
<span class="normal"> </span><span class="function">populate_tree_model</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">store</span><span class="symbol">);</span> |
|
500 |
||
501 |
<span class="normal"> </span><span class="comment">/* Create a view */</span> |
|
502 |
<span class="normal"> tree </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="GtkTreeView.html#gtk-tree-view-new-with-model">gtk_tree_view_new_with_model</a></span><span class="normal"> </span><span class="symbol">(</span><span class="function">GTK_TREE_MODEL</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">store</span><span class="symbol">));</span> |
|
503 |
||
504 |
<span class="normal"> </span><span class="comment">/* The view now holds a reference. We can get rid of our own</span> |
|
505 |
<span class="comment"> * reference */</span> |
|
506 |
<span class="normal"> </span><span class="function">g_object_unref</span><span class="normal"> </span><span class="symbol">(</span><span class="function">G_OBJECT</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">store</span><span class="symbol">));</span> |
|
507 |
||
508 |
<span class="normal"> </span><span class="comment">/* Create a cell render and arbitrarily make it red for demonstration</span> |
|
509 |
<span class="comment"> * purposes */</span> |
|
510 |
<span class="normal"> renderer </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="GtkCellRendererText.html#gtk-cell-renderer-text-new">gtk_cell_renderer_text_new</a></span><span class="normal"> </span><span class="symbol">();</span> |
|
511 |
<span class="normal"> </span><span class="function">g_object_set</span><span class="normal"> </span><span class="symbol">(</span><span class="function">G_OBJECT</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">renderer</span><span class="symbol">),</span> |
|
512 |
<span class="normal"> </span><span class="string">"foreground"</span><span class="symbol">,</span><span class="normal"> </span><span class="string">"red"</span><span class="symbol">,</span> |
|
513 |
<span class="normal"> <a href="/usr/share/gtk-doc/html/liboil/liboil-liboiljunk.html#NULL:CAPS">NULL</a></span><span class="symbol">);</span> |
|
514 |
||
515 |
<span class="normal"> </span><span class="comment">/* Create a column, associating the "text" attribute of the</span> |
|
516 |
<span class="comment"> * cell_renderer to the first column of the model */</span> |
|
517 |
<span class="normal"> column </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="GtkTreeViewColumn.html#gtk-tree-view-column-new-with-attributes">gtk_tree_view_column_new_with_attributes</a></span><span class="normal"> </span><span class="symbol">(</span><span class="string">"Author"</span><span class="symbol">,</span><span class="normal"> renderer</span><span class="symbol">,</span> |
|
518 |
<span class="normal"> </span><span class="string">"text"</span><span class="symbol">,</span><span class="normal"> AUTHOR_COLUMN</span><span class="symbol">,</span> |
|
519 |
<span class="normal"> <a href="/usr/share/gtk-doc/html/liboil/liboil-liboiljunk.html#NULL:CAPS">NULL</a></span><span class="symbol">);</span> |
|
520 |
||
521 |
<span class="normal"> </span><span class="comment">/* Add the column to the view. */</span> |
|
522 |
<span class="normal"> </span><span class="function"><a href="GtkTreeView.html#gtk-tree-view-append-column">gtk_tree_view_append_column</a></span><span class="normal"> </span><span class="symbol">(</span><span class="function">GTK_TREE_VIEW</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">tree</span><span class="symbol">),</span><span class="normal"> column</span><span class="symbol">);</span> |
|
523 |
||
524 |
<span class="normal"> </span><span class="comment">/* Second column.. title of the book. */</span> |
|
525 |
<span class="normal"> renderer </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="GtkCellRendererText.html#gtk-cell-renderer-text-new">gtk_cell_renderer_text_new</a></span><span class="normal"> </span><span class="symbol">();</span> |
|
526 |
<span class="normal"> column </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="GtkTreeViewColumn.html#gtk-tree-view-column-new-with-attributes">gtk_tree_view_column_new_with_attributes</a></span><span class="normal"> </span><span class="symbol">(</span><span class="string">"Title"</span><span class="symbol">,</span> |
|
527 |
<span class="normal"> renderer</span><span class="symbol">,</span> |
|
528 |
<span class="normal"> </span><span class="string">"text"</span><span class="symbol">,</span><span class="normal"> TITLE_COLUMN</span><span class="symbol">,</span> |
|
529 |
<span class="normal"> <a href="/usr/share/gtk-doc/html/liboil/liboil-liboiljunk.html#NULL:CAPS">NULL</a></span><span class="symbol">);</span> |
|
530 |
<span class="normal"> </span><span class="function"><a href="GtkTreeView.html#gtk-tree-view-append-column">gtk_tree_view_append_column</a></span><span class="normal"> </span><span class="symbol">(</span><span class="function">GTK_TREE_VIEW</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">tree</span><span class="symbol">),</span><span class="normal"> column</span><span class="symbol">);</span> |
|
531 |
||
532 |
<span class="normal"> </span><span class="comment">/* Last column.. whether a book is checked out. */</span> |
|
533 |
<span class="normal"> renderer </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="GtkCellRendererToggle.html#gtk-cell-renderer-toggle-new">gtk_cell_renderer_toggle_new</a></span><span class="normal"> </span><span class="symbol">();</span> |
|
534 |
<span class="normal"> column </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="GtkTreeViewColumn.html#gtk-tree-view-column-new-with-attributes">gtk_tree_view_column_new_with_attributes</a></span><span class="normal"> </span><span class="symbol">(</span><span class="string">"Checked out"</span><span class="symbol">,</span> |
|
535 |
<span class="normal"> renderer</span><span class="symbol">,</span> |
|
536 |
<span class="normal"> </span><span class="string">"active"</span><span class="symbol">,</span><span class="normal"> CHECKED_COLUMN</span><span class="symbol">,</span> |
|
537 |
<span class="normal"> <a href="/usr/share/gtk-doc/html/liboil/liboil-liboiljunk.html#NULL:CAPS">NULL</a></span><span class="symbol">);</span> |
|
538 |
<span class="normal"> </span><span class="function"><a href="GtkTreeView.html#gtk-tree-view-append-column">gtk_tree_view_append_column</a></span><span class="normal"> </span><span class="symbol">(</span><span class="function">GTK_TREE_VIEW</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">tree</span><span class="symbol">),</span><span class="normal"> column</span><span class="symbol">);</span> |
|
539 |
||
540 |
<span class="normal"> </span><span class="comment">/* Now we can manipulate the view just like any other GTK widget */</span> |
|
541 |
<span class="normal"> </span><span class="symbol">...</span> |
|
542 |
<span class="cbracket">}</span></pre></td> |
|
543 |
</tr> |
|
544 |
</tbody> |
|
545 |
</table> |
|
546 |
</div> |
|
547 |
||
548 |
<p> |
|
549 |
</p> |
|
550 |
</div> |
|
551 |
</div> |
|
552 |
<div class="footer"> |
|
553 |
<hr> |
|
554 |
Generated by GTK-Doc V1.18</div> |
|
555 |
</body> |
|
556 |
</html> |