gergely/treeview-tutorial-xml
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Convert class names from <literal> to <classname>

Browse Source
This commit is contained in:
Gergely Polonkai 2014-07-24 00:07:40 +02:00
parent f9c50818c0
commit cfdc370818
1 changed files with 162 additions and 160 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

322
treeview-tutorial.xml
View File

@ -48,39 +48,41 @@
<chapter id="ch-TreeView"> <chapter id="ch-TreeView">
<title>Lists and Trees: the GtkTreeView Widget</title> <title>Lists and Trees: the GtkTreeView Widget</title>
<para><literal>GtkTreeView</literal> is a widget that displays single- or <para><classname>GtkTreeView</classname> is a widget that displays single-
multi-columned lists and trees. It replaces the old Gtk+-1.2 GtkCList and or multi-columned lists and trees. It replaces the old Gtk+-1.2
GtkCTree widgets. Even though <literal>GtkTreeView</literal> is slightly <classname>GtkCList</classname> and <classname>GtkCTree</classname>
harder to master than its predecessors, it is so much more powerful and widgets. Even though <classname>GtkTreeView</classname> is slightly harder
flexible that most application developers will not want to miss it once to master than its predecessors, it is so much more powerful and flexible
they have come to know it.</para> that most application developers will not want to miss it once they have
come to know it.</para>
<para>The purpose of this chapter is not to provide an exhaustive <para>The purpose of this chapter is not to provide an exhaustive
documentation of <literal>GtkTreeView</literal> - that is what the <ulink documentation of <classname>GtkTreeView</classname> – that is what the
url="http://developer.gnome.org/doc/API/2.0/gtk/TreeWidgetObjects.html">API <ulink
url="https://developer.gnome.org/gtk3/stable/TreeWidgetObjects.html">API
documentation</ulink> is for, which should be read alongside with this documentation</ulink> is for, which should be read alongside with this
tutorial. The goal is rather to present an introduction to the most tutorial. The goal is rather to present an introduction to the most
commonly-used aspects of <literal>GtkTreeView</literal>, and to commonly-used aspects of <classname>GtkTreeView</classname>, and to
demonstrate how the various <literal>GtkTreeView</literal> components and demonstrate how the various <classname>GtkTreeView</classname> components and
concepts work together. Furthermore, an attempt has been made to shed some concepts work together. Furthermore, an attempt has been made to shed some
light on custom tree models and custom cell renderers, which seem to be light on custom tree models and custom cell renderers, which seem to be
often-mentioned, but rarely explained.</para> often-mentioned, but rarely explained.</para>
<para>Developers looking for a quick and dirty introduction that teaches <para>Developers looking for a quick and dirty introduction that teaches
them everything they need to know in less than five paragraphs will not them everything they need to know in less than five paragraphs will not
find it here. In the author's experience, developers who do not understand find it here. In the authors’ experience, developers who do not understand
how the tree view and the models work together will run into problems once how the tree view and the models work together will run into problems once
they try to modify the given examples, whereas developers who have worked they try to modify the given examples, whereas developers who have worked
with other toolkits that employ the Model/View/Controller-design will find with other toolkits that employ the Model/View/Controller design will find
that the API reference provides all the information they need to know in that the API reference provides all the information they need to know in
more condensed form anyway. Those who disagree may jump straight to the more condensed form anyway. Those who disagree may jump straight to the
<link linkend="sec-treeview-col-example">working example code</link> of <link linkend="sec-treeview-col-example">working example code</link> of
course.</para> course.</para>
<para>Please note that the code examples in the following sections do not <para>Please note that the code examples in the following sections do not
necessarily demonstrate how <literal>GtkTreeView</literal> is used best in necessarily demonstrate how <classname>GtkTreeView</classname> is used
a particular situation. There are different ways to achieve the same best in a particular situation. There are different ways to achieve the
result, and the examples merely show those different ways, so that same result, and the examples merely show those different ways, so that
developers are able to decide which one is most suitable for the task at developers are able to decide which one is most suitable for the task at
hand.</para> hand.</para>
@ -213,31 +215,31 @@ main (int argc, char **argv)
<chapter id="sec-treeview-components"> <chapter id="sec-treeview-components">
<title>Components: Model, Renderer, Column, View</title> <title>Components: Model, Renderer, Column, View</title>
<para>The most important concept underlying <literal>GtkTreeView</literal> <para>The most important concept underlying
is that of complete separation between data and how that data is displayed <classname>GtkTreeView</classname> is that of complete separation between
on the screen. This is commonly known as Model/View/Controller-design data and how that data is displayed on the screen. This is commonly known
(MVC). Data of various type (strings, numbers, images, etc.) is stored in as Model/View/Controller design (MVC). Data of various type (strings,
a 'model'. The 'view' is then told which data to display, where to display numbers, images, etc.) is stored in a 'model'. The 'view' is then told
it, and how to display it. One of the advantages of this approach is that which data to display, where to display it, and how to display it. One of
you can have multiple views that display the same data (a directory tree the advantages of this approach is that you can have multiple views that
for example) in different ways, or in the same way multiple times, with display the same data (a directory tree for example) in different ways, or
only one copy of the underlying data. This avoids duplication of data and in the same way multiple times, with only one copy of the underlying data.
programming effort if the same data is re-used in different contexts. This avoids duplication of data and programming effort if the same data is
Also, when the data in the model is updated, all views automatically get re-used in different contexts. Also, when the data in the model is
updated as well.</para> updated, all views automatically get updated as well.</para>
<para>So, while <literal>GtkTreeModel</literal> is used to store data, <para>So, while <classname>GtkTreeModel</classname> is used to store data,
there are other components that determine which data is displayed in the there are other components that determine which data is displayed in the
<literal>GtkTreeView</literal> and how it is displayed. These components <classname>GtkTreeView</classname> and how it is displayed. These
are <literal>GtkTreeViewColumn</literal> and components are <classname>GtkTreeViewColumn</classname> and
<literal>GtkCellRenderer</literal>. A <literal>GtkTreeView</literal> is <classname>GtkCellRenderer</classname>. A <classname>GtkTreeView</classname> is
made up of tree view columns. These are the columns that users perceive as made up of tree view columns. These are the columns that users perceive as
columns. They have a clickable column header with a column title that can columns. They have a clickable column header with a column title that can
be hidden, and can be resized and sorted. Tree view columns do not display be hidden, and can be resized and sorted. Tree view columns do not display
any data, they are only used as a device to represent the user-side of the any data, they are only used as a device to represent the user-side of the
tree view (sorting etc.) and serve as packing widgets for the components tree view (sorting etc.) and serve as packing widgets for the components
that do the actual rendering of data onto the screen, namely the that do the actual rendering of data onto the screen, namely the
<literal>GtkCellRenderer</literal> family of objects (I call them <classname>GtkCellRenderer</classname> family of objects (I call them
'objects' because they are not GtkWidgets). There are a number of 'objects' because they are not GtkWidgets). There are a number of
different cell renderers that specialise in rendering certain data like different cell renderers that specialise in rendering certain data like
strings, pixbufs, or toggle buttons. More on this <link strings, pixbufs, or toggle buttons. More on this <link
@ -248,10 +250,10 @@ main (int argc, char **argv)
contain multiple cell renderers. For example, if one wanted to display a contain multiple cell renderers. For example, if one wanted to display a
'Filename' column where each filename has a little icon on the left 'Filename' column where each filename has a little icon on the left
indicating the file type, one would pack a indicating the file type, one would pack a
<literal>GtkCellRendererPixbuf</literal> and a <classname>GtkCellRendererPixbuf</classname> and a
<literal>GtkCellRendererText</literal> into one tree view column. Packing <classname>GtkCellRendererText</classname> into one tree view column. Packing
renderers into a tree view column is similar to packing widgets into a renderers into a tree view column is similar to packing widgets into a
<literal>GtkHBox</literal>.</para> <classname>GtkHBox</classname>.</para>
</chapter> </chapter>
<chapter id="sec-treemodels"> <chapter id="sec-treemodels">
@ -259,57 +261,57 @@ main (int argc, char **argv)
GtkTreeStore</title> GtkTreeStore</title>
<para>It is important to realise what <ulink <para>It is important to realise what <ulink
url="http://developer.gnome.org/doc/API/2.0/gtk/GtkTreeModel.html"><literal>GtkTreeModel</literal></ulink> url="http://developer.gnome.org/doc/API/2.0/gtk/GtkTreeModel.html"><classname>GtkTreeModel</classname></ulink>
is and what it is not. <literal>GtkTreeModel</literal> is basically just is and what it is not. <classname>GtkTreeModel</classname> is basically just
an 'interface' to the data store, meaning that it is a standardised set of an 'interface' to the data store, meaning that it is a standardised set of
functions that allows a <literal>GtkTreeView</literal> widget (and the functions that allows a <classname>GtkTreeView</classname> widget (and the
application programmer) to query certain characteristics of a data store, application programmer) to query certain characteristics of a data store,
for example how many rows there are, which rows have children, and how for example how many rows there are, which rows have children, and how
many children a particular row has. It also provides functions to retrieve many children a particular row has. It also provides functions to retrieve
data from the data store, and tell the tree view what type of data is data from the data store, and tell the tree view what type of data is
stored in the model. Every data store must implement the stored in the model. Every data store must implement the
<literal>GtkTreeModel</literal> interface and provide these functions, <classname>GtkTreeModel</classname> interface and provide these functions,
which you can use by casting a store to a tree model with which you can use by casting a store to a tree model with
<literal>GTK_TREE_MODEL(store)</literal>. <literal>GtkTreeModel</literal> <literal>GTK_TREE_MODEL(store)</literal>. <classname>GtkTreeModel</classname>
itself only provides a way to query a data store's characteristics and to itself only provides a way to query a data store's characteristics and to
retrieve existing data, it does not provide a way to remove or add rows to retrieve existing data, it does not provide a way to remove or add rows to
the store or put data into the store. This is done using the specific the store or put data into the store. This is done using the specific
store's functions.</para> store's functions.</para>
<para>Gtk+ comes with two built-in data stores (models): <ulink <para>Gtk+ comes with two built-in data stores (models): <ulink
url="http://developer.gnome.org/doc/API/2.0/gtk/GtkListStore.html"><literal>GtkListStore</literal></ulink> url="http://developer.gnome.org/doc/API/2.0/gtk/GtkListStore.html"><classname>GtkListStore</classname></ulink>
and <ulink and <ulink
url="http://developer.gnome.org/doc/API/2.0/gtk/GtkTreeStore.html"><literal>GtkTreeStore</literal></ulink>. url="http://developer.gnome.org/doc/API/2.0/gtk/GtkTreeStore.html"><classname>GtkTreeStore</classname></ulink>.
As the names imply, <literal>GtkListStore</literal> is used for simple As the names imply, <classname>GtkListStore</classname> is used for simple
lists of data items where items have no hierarchical parent-child lists of data items where items have no hierarchical parent-child
relationships, and <literal>GtkTreeStore</literal> is used for tree-like relationships, and <classname>GtkTreeStore</classname> is used for tree-like
data structures, where items can have parent-child relationships. A list data structures, where items can have parent-child relationships. A list
of files in a directory would be an example of a simple list structure, of files in a directory would be an example of a simple list structure,
whereas a directory tree is an example for a tree structure. A list is whereas a directory tree is an example for a tree structure. A list is
basically just a special case of a tree with none of the items having any basically just a special case of a tree with none of the items having any
children, so one could use a tree store to maintain a simple list of items children, so one could use a tree store to maintain a simple list of items
as well. The only reason <literal>GtkListStore</literal> exists is in as well. The only reason <classname>GtkListStore</classname> exists is in
order to provide an easier interface that does not need to cater for order to provide an easier interface that does not need to cater for
child-parent relationships, and because a simple list model can be child-parent relationships, and because a simple list model can be
optimised for the special case where no children exist, which makes it optimised for the special case where no children exist, which makes it
faster and more efficient.</para> faster and more efficient.</para>
<para><literal>GtkListStore</literal> and <literal>GtkTreeStore</literal> <para><classname>GtkListStore</classname> and <classname>GtkTreeStore</classname>
should cater for most types of data an application developer might want to should cater for most types of data an application developer might want to
display in a <literal>GtkTreeView</literal>. However, it should be noted display in a <classname>GtkTreeView</classname>. However, it should be noted
that <literal>GtkListStore</literal> and <literal>GtkTreeStore</literal> that <classname>GtkListStore</classname> and <classname>GtkTreeStore</classname>
have been designed with flexibility in mind. If you plan to store a lot of have been designed with flexibility in mind. If you plan to store a lot of
data, or have a large number of rows, you should consider implementing data, or have a large number of rows, you should consider implementing
your own custom model that stores and manipulates data your own way and your own custom model that stores and manipulates data your own way and
implements the <literal>GtkTreeModel</literal> interface. This will not implements the <classname>GtkTreeModel</classname> interface. This will not
only be more efficient, but probably also lead to saner code in the long only be more efficient, but probably also lead to saner code in the long
run, and give you more control over your data. See <link run, and give you more control over your data. See <link
linkend="sec-custom-models">below</link> for more details on how to linkend="sec-custom-models">below</link> for more details on how to
implement custom models.</para> implement custom models.</para>
<para>Tree model implementations like <literal>GtkListStore</literal> and <para>Tree model implementations like <classname>GtkListStore</classname> and
<literal>GtkTreeStore</literal> will take care of the view side for you <classname>GtkTreeStore</classname> will take care of the view side for you
once you have configured the <literal>GtkTreeView</literal> to display once you have configured the <classname>GtkTreeView</classname> to display
what you want. If you change data in the store, the model will notify the what you want. If you change data in the store, the model will notify the
tree view and your data display will be updated. If you add or remove tree view and your data display will be updated. If you add or remove
rows, the model will also notify the store, and your row will appear in or rows, the model will also notify the store, and your row will appear in or
@ -391,7 +393,7 @@ main (int argc, char **argv)
<literal>G_TYPE_POINTER</literal> will often do as well, you will just <literal>G_TYPE_POINTER</literal> will often do as well, you will just
need to take care of memory allocation and freeing yourself then.</para> need to take care of memory allocation and freeing yourself then.</para>
<para>Storing <literal>GObject</literal>-derived types (most <para>Storing <classname>GObject</classname>-derived types (most
<literal>GDK_TYPE_FOO</literal> and <literal>GTK_TYPE_FOO</literal>) is <literal>GDK_TYPE_FOO</literal> and <literal>GTK_TYPE_FOO</literal>) is
a special case that is dealt with <link a special case that is dealt with <link
linkend="sec-treemodel-storing-gobjects">further below</link>.</para> linkend="sec-treemodel-storing-gobjects">further below</link>.</para>
@ -416,17 +418,17 @@ main (int argc, char **argv)
GtkTreeRowReference</title> GtkTreeRowReference</title>
<para>There are different ways to refer to a specific row. The two you <para>There are different ways to refer to a specific row. The two you
will have to deal with are <literal>GtkTreeIter</literal> and will have to deal with are <classname>GtkTreeIter</classname> and
<literal>GtkTreePath</literal>.</para> <classname>GtkTreePath</classname>.</para>
<sect2 id="sec-treemodel-rowref-path"> <sect2 id="sec-treemodel-rowref-path">
<title>GtkTreePath</title> <title>GtkTreePath</title>
<subtitle>Describing a row 'geographically'</subtitle> <subtitle>Describing a row 'geographically'</subtitle>
<para>A <literal>GtkTreePath</literal> is a comparatively <para>A <classname>GtkTreePath</classname> is a comparatively
straight-forward way to describe the logical position of a row in the straight-forward way to describe the logical position of a row in the
model. As a <literal>GtkTreeView</literal> always displays model. As a <classname>GtkTreeView</classname> always displays
<emphasis>all</emphasis> rows in a model, a tree path always describes <emphasis>all</emphasis> rows in a model, a tree path always describes
the same row in both model and view.</para> the same row in both model and view.</para>
@ -475,7 +477,7 @@ main (int argc, char **argv)
row than it refered to before the insertion/deletion/resorting. This row than it refered to before the insertion/deletion/resorting. This
is important to keep in mind. (See the <link is important to keep in mind. (See the <link
linkend="sec-treemodel-rowref-rowref">section on linkend="sec-treemodel-rowref-rowref">section on
<literal>GtkTreeRowReference</literal>s below</link> for a tree path <classname>GtkTreeRowReference</classname>s below</link> for a tree path
that keeps updating itself to make sure it always refers to the same that keeps updating itself to make sure it always refers to the same
row when the model changes).</para> row when the model changes).</para>
@ -485,14 +487,14 @@ main (int argc, char **argv)
and only child of 'clips', and be described by the tree path that and only child of 'clips', and be described by the tree path that
formerly belonged to 'funny clips', ie. "1:0:0".</para> formerly belonged to 'funny clips', ie. "1:0:0".</para>
<para>You can get a new <literal>GtkTreePath</literal> from a path in <para>You can get a new <classname>GtkTreePath</classname> from a path in
string form using <literal>gtk_tree_path_new_from_string</literal>, string form using <literal>gtk_tree_path_new_from_string</literal>,
and you can convert a given <literal>GtkTreePath</literal> into its and you can convert a given <classname>GtkTreePath</classname> into its
string notation with <literal>gtk_tree_path_to_string</literal>. string notation with <literal>gtk_tree_path_to_string</literal>.
Usually you will rarely have to handle the string notation, it is Usually you will rarely have to handle the string notation, it is
described here merely to demonstrate the concept of tree paths.</para> described here merely to demonstrate the concept of tree paths.</para>
<para>Instead of the string notation, <literal>GtkTreePath</literal> <para>Instead of the string notation, <classname>GtkTreePath</classname>
uses an integer array internally. You can get the depth (ie. the uses an integer array internally. You can get the depth (ie. the
nesting level) of a tree path with <ulink nesting level) of a tree path with <ulink
url="http://developer.gnome.org/doc/API/2.0/gtk/GtkTreeModel.html#gtk-tree-path-get-depth"> url="http://developer.gnome.org/doc/API/2.0/gtk/GtkTreeModel.html#gtk-tree-path-get-depth">
@ -527,7 +529,7 @@ main (int argc, char **argv)
url="http://developer.gnome.org/doc/API/2.0/gtk/GtkTreeModel.html#gtk-tree-model-get-iter"> url="http://developer.gnome.org/doc/API/2.0/gtk/GtkTreeModel.html#gtk-tree-model-get-iter">
<literal>gtk_tree_model_get_iter</literal></ulink>.</para> <literal>gtk_tree_model_get_iter</literal></ulink>.</para>
<para><literal>GtkTreePath</literal> is an opaque structure, with its <para><classname>GtkTreePath</classname> is an opaque structure, with its
details hidden from the compiler. If you need to make a copy of a tree details hidden from the compiler. If you need to make a copy of a tree
path, use <ulink path, use <ulink
url="http://developer.gnome.org/doc/API/2.0/gtk/GtkTreeModel.html#gtk-tree-path-copy"> url="http://developer.gnome.org/doc/API/2.0/gtk/GtkTreeModel.html#gtk-tree-path-copy">
@ -540,7 +542,7 @@ main (int argc, char **argv)
<subtitle>Refering to a row in model-speak</subtitle> <subtitle>Refering to a row in model-speak</subtitle>
<para>Another way to refer to a row in a list or tree is <para>Another way to refer to a row in a list or tree is
<literal>GtkTreeIter</literal>. A tree iter is just a structure that <classname>GtkTreeIter</classname>. A tree iter is just a structure that
contains a couple of pointers that mean something to the model you are contains a couple of pointers that mean something to the model you are
using. Tree iters are used internally by models, and they often using. Tree iters are used internally by models, and they often
contain a direct pointer to the internal data of the row in question. contain a direct pointer to the internal data of the row in question.
@ -548,10 +550,10 @@ main (int argc, char **argv)
modify it directly either.</para> modify it directly either.</para>
<para>All tree models (and therefore also <para>All tree models (and therefore also
<literal>GtkListStore</literal> and <literal>GtkTreeStore</literal>) <classname>GtkListStore</classname> and <classname>GtkTreeStore</classname>)
must support the <ulink must support the <ulink
url="http://developer.gnome.org/doc/API/2.0/gtk/GtkTreeModel.html"> url="http://developer.gnome.org/doc/API/2.0/gtk/GtkTreeModel.html">
<literal>GtkTreeModel</literal></ulink> functions that operate on tree <classname>GtkTreeModel</classname></ulink> functions that operate on tree
iters (e.g. get the tree iter for the first child of the row specified iters (e.g. get the tree iter for the first child of the row specified
by a given tree iter, get the first row in the list/tree, get the n-th by a given tree iter, get the first row in the list/tree, get the n-th
child of a given iter etc.). Some of these functions are:</para> child of a given iter etc.). Some of these functions are:</para>
@ -617,7 +619,7 @@ main (int argc, char **argv)
otherwise. There are more functions that operate on iters. Check out otherwise. There are more functions that operate on iters. Check out
the <ulink the <ulink
url="http://developer.gnome.org/doc/API/2.0/gtk/GtkTreeModel.html"> url="http://developer.gnome.org/doc/API/2.0/gtk/GtkTreeModel.html">
<literal>GtkTreeModel</literal> API reference</ulink> for <classname>GtkTreeModel</classname> API reference</ulink> for
details.</para> details.</para>
<para>You might notice that there is no <para>You might notice that there is no
@ -640,7 +642,7 @@ main (int argc, char **argv)
case a tree iter will be valid as long as a row exists), yet still it case a tree iter will be valid as long as a row exists), yet still it
is not advisable to store iter structures unless you really mean to do is not advisable to store iter structures unless you really mean to do
that. There is a better way to keep track of a row over time: that. There is a better way to keep track of a row over time:
<literal>GtkTreeRowReference</literal></para> <classname>GtkTreeRowReference</classname></para>
</sect2> </sect2>
<sect2 id="sec-treemodel-rowref-rowref"> <sect2 id="sec-treemodel-rowref-rowref">
@ -648,7 +650,7 @@ main (int argc, char **argv)
<subtitle>Keeping track of rows even when the model changes</subtitle> <subtitle>Keeping track of rows even when the model changes</subtitle>
<para>A <literal>GtkTreeRowReference</literal> is basically an object <para>A <classname>GtkTreeRowReference</classname> is basically an object
that takes a tree path, and watches a model for changes. If anything that takes a tree path, and watches a model for changes. If anything
changes, like rows getting inserted or removed, or rows getting changes, like rows getting inserted or removed, or rows getting
re-ordered, the tree row reference object will keep the given tree re-ordered, the tree row reference object will keep the given tree
@ -703,7 +705,7 @@ main (int argc, char **argv)
<para>In practice, a programmer can either use tree row references to <para>In practice, a programmer can either use tree row references to
keep track of rows over time, or store tree iters directly (if, and keep track of rows over time, or store tree iters directly (if, and
only if, the model has persistent iters). Both only if, the model has persistent iters). Both
<literal>GtkListStore</literal> and <literal>GtkTreeStore</literal> <classname>GtkListStore</classname> and <classname>GtkTreeStore</classname>
have persistent iters, so storing iters is possible. However, using have persistent iters, so storing iters is possible. However, using
tree row references is definitively the Right Way(tm) to do things, tree row references is definitively the Right Way(tm) to do things,
even though it comes with some overhead that might impact performance even though it comes with some overhead that might impact performance
@ -711,7 +713,7 @@ main (int argc, char **argv)
it might be preferable to write a custom model anyway though). it might be preferable to write a custom model anyway though).
Especially beginners might find it easier to handle and store tree row Especially beginners might find it easier to handle and store tree row
references than iters, because tree row references are handled by references than iters, because tree row references are handled by
pointer value, which you can easily add to a <literal>GList</literal> pointer value, which you can easily add to a <classname>GList</classname>
or pointer array, while it is easy to store tree iters in a wrong or pointer array, while it is easy to store tree iters in a wrong
way.</para> way.</para>
</sect2> </sect2>
@ -772,7 +774,7 @@ onTreeViewRowActivated (GtkTreeView *view, GtkTreePath *path,
<para>As tree iters are only valid for a short time, they are usually <para>As tree iters are only valid for a short time, they are usually
allocated on the stack, as in the following example (keep in mind that allocated on the stack, as in the following example (keep in mind that
<literal>GtkTreeIter</literal> is just a structure that contains data <classname>GtkTreeIter</classname> is just a structure that contains data
fields you do not need to know anything about):</para> fields you do not need to know anything about):</para>
<programlisting role="C"> <programlisting role="C">
@ -1063,7 +1065,7 @@ onTreeViewRowActivated (GtkTreeView *view, GtkTreePath *path,
<para>Here is the previous example extended to traverse the list store <para>Here is the previous example extended to traverse the list store
and print out the data stored. As an extra, we use and print out the data stored. As an extra, we use
<literal>gtk_tree_model_foreach</literal> to traverse the store and <literal>gtk_tree_model_foreach</literal> to traverse the store and
retrieve the row number from the <literal>GtkTreePath</literal> passed retrieve the row number from the <classname>GtkTreePath</classname> passed
to us in the foreach callback function:</para> to us in the foreach callback function:</para>
<programlisting role="C"> <programlisting role="C">
@ -1186,8 +1188,8 @@ onTreeViewRowActivated (GtkTreeView *view, GtkTreePath *path,
<literal>g_free</literal> the string returned when you don't need it <literal>g_free</literal> the string returned when you don't need it
any longer, as in the example above.</para> any longer, as in the example above.</para>
<para>If you retrieve a <literal>GObject</literal> such as a <para>If you retrieve a <classname>GObject</classname> such as a
<literal>GdkPixbuf</literal> from the store, <classname>GdkPixbuf</classname> from the store,
<literal>gtk_tree_model_get</literal> will automatically add a <literal>gtk_tree_model_get</literal> will automatically add a
reference to it, so you need to call <literal>g_object_unref</literal> reference to it, so you need to call <literal>g_object_unref</literal>
on the retrieved object once you are done with it:</para> on the retrieved object once you are done with it:</para>
@ -1210,10 +1212,10 @@ onTreeViewRowActivated (GtkTreeView *view, GtkTreePath *path,
... ...
</programlisting> </programlisting>
<para>Similarly, <literal>GBoxed</literal>-derived types retrieved <para>Similarly, <classname>GBoxed</classname>-derived types retrieved
from a model need to be freed with <literal>g_boxed_free</literal> from a model need to be freed with <literal>g_boxed_free</literal>
when done with them (don't worry if you have never heard of when done with them (don't worry if you have never heard of
<literal>GBoxed</literal>).</para> <classname>GBoxed</classname>).</para>
<para>If the model column is of type <para>If the model column is of type
<literal>G_TYPE_POINTER</literal>, <literal>G_TYPE_POINTER</literal>,
@ -1298,7 +1300,7 @@ onTreeViewRowActivated (GtkTreeView *view, GtkTreePath *path,
<para>If you want to remove the n-th row from a list (or the n-th child <para>If you want to remove the n-th row from a list (or the n-th child
of a tree node), you have two approaches: either you first create a of a tree node), you have two approaches: either you first create a
<literal>GtkTreePath</literal> that describes that row and then turn it <classname>GtkTreePath</classname> that describes that row and then turn it
into an iter and remove it; or you take the iter of the parent node and into an iter and remove it; or you take the iter of the parent node and
use <ulink use <ulink
url="http://developer.gnome.org/doc/API/2.0/gtk/GtkTreeModel.html#gtk-tree-model-iter-nth-child"> url="http://developer.gnome.org/doc/API/2.0/gtk/GtkTreeModel.html#gtk-tree-model-iter-nth-child">
@ -1459,7 +1461,7 @@ onTreeViewRowActivated (GtkTreeView *view, GtkTreePath *path,
<sect1 id="sec-treemodel-storing-gobjects"> <sect1 id="sec-treemodel-storing-gobjects">
<title>Storing GObjects (Pixbufs etc.)</title> <title>Storing GObjects (Pixbufs etc.)</title>
<para>A special case are <literal>GObject</literal> types, like <para>A special case are <classname>GObject</classname> types, like
<literal>GDK_TYPE_PIXBUF</literal>, that get stored in a list or tree <literal>GDK_TYPE_PIXBUF</literal>, that get stored in a list or tree
store. The store will not make a copy of the object, rather it will store. The store will not make a copy of the object, rather it will
increase the object's refcount. The store will then unref the object increase the object's refcount. The store will then unref the object
@ -1514,7 +1516,7 @@ onTreeViewRowActivated (GtkTreeView *view, GtkTreePath *path,
<para>Having learned how to add, manipulate, and retrieve data from a <para>Having learned how to add, manipulate, and retrieve data from a
store, the next step is to get that data displayed in a store, the next step is to get that data displayed in a
<literal>GtkTreeView</literal> widget.</para> <classname>GtkTreeView</classname> widget.</para>
</sect1> </sect1>
<sect1 id="sec-treemodel-storing-structs"> <sect1 id="sec-treemodel-storing-structs">
@ -1838,8 +1840,8 @@ yourself. Some code snippets:
<sect2 id="sec-treeview-connect-model-refcounting"> <sect2 id="sec-treeview-connect-model-refcounting">
<title>Reference counting</title> <title>Reference counting</title>
<para>Tree models like <literal>GtkListStore</literal> and <para>Tree models like <classname>GtkListStore</classname> and
<literal>GtkTreeStore</literal> are <literal>GObjects</literal> and <classname>GtkTreeStore</classname> are <classname>GObjects</classname> and
have a reference count of 1 after creation. The tree view will add its 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 own reference to the model when you add the model with
<literal>gtk_tree_view_set_model</literal>, and will unref it again <literal>gtk_tree_view_set_model</literal>, and will unref it again
@ -1931,9 +1933,9 @@ yourself. Some code snippets:
resized or sorted. A tree view is made up of tree view columns, and you resized or sorted. A tree view is made up of tree view columns, and you
need at least one tree view column in order to display something in the need at least one tree view column in order to display something in the
tree view. Tree view columns, however, do not display anything by tree view. Tree view columns, however, do not display anything by
themselves, this is done by specialised <literal>GtkCellRenderer</literal> themselves, this is done by specialised <classname>GtkCellRenderer</classname>
objects. Cell renderers are packed into tree view columns much like objects. Cell renderers are packed into tree view columns much like
widgets are packed into <literal>GtkHBoxes</literal>.</para> widgets are packed into <classname>GtkHBox</classname>es.</para>
<para>Here is a diagram (courtesy of Owen Taylor) that pictures the <para>Here is a diagram (courtesy of Owen Taylor) that pictures the
relationship between tree view columns and cell renderers:</para> relationship between tree view columns and cell renderers:</para>
@ -1965,7 +1967,7 @@ yourself. Some code snippets:
<title>Cell Renderers</title> <title>Cell Renderers</title>
<para>Cell renderers are objects that are responsible for the actual <para>Cell renderers are objects that are responsible for the actual
rendering of data within a <literal>GtkTreeViewColumn</literal>. They rendering of data within a <classname>GtkTreeViewColumn</classname>. They
are basically just GObjects (ie. not widgets) that have certain are basically just GObjects (ie. not widgets) that have certain
properties, and those properties determine how a single cell is properties, and those properties determine how a single cell is
drawn.</para> drawn.</para>
@ -1993,14 +1995,14 @@ yourself. Some code snippets:
<listitem> <listitem>
<simpara><ulink <simpara><ulink
url="http://developer.gnome.org/doc/API/2.0/gtk/GtkCellRendererText.html"> url="http://developer.gnome.org/doc/API/2.0/gtk/GtkCellRendererText.html">
<literal>GtkCellRendererText</literal></ulink> renders strings or <classname>GtkCellRendererText</classname></ulink> renders strings or
numbers or boolean values as text ("Joe", "99.32", "true")</simpara> numbers or boolean values as text ("Joe", "99.32", "true")</simpara>
</listitem> </listitem>
<listitem> <listitem>
<simpara><ulink <simpara><ulink
url="http://developer.gnome.org/doc/API/2.0/gtk/GtkCellRendererPixbuf.html"> url="http://developer.gnome.org/doc/API/2.0/gtk/GtkCellRendererPixbuf.html">
<literal>GtkCellRendererPixbuf</literal></ulink> is used to display <classname>GtkCellRendererPixbuf</classname></ulink> is used to display
images; either user-defined images, or one of the stock icons that images; either user-defined images, or one of the stock icons that
come with Gtk+.</simpara> come with Gtk+.</simpara>
</listitem> </listitem>
@ -2008,18 +2010,18 @@ yourself. Some code snippets:
<listitem> <listitem>
<simpara><ulink <simpara><ulink
url="http://developer.gnome.org/doc/API/2.0/gtk/GtkCellRendererToggle.html"> url="http://developer.gnome.org/doc/API/2.0/gtk/GtkCellRendererToggle.html">
<literal>GtkCellRendererToggle</literal></ulink> displays a boolean <classname>GtkCellRendererToggle</classname></ulink> displays a boolean
value in form of a check box or as a radio button.</simpara> value in form of a check box or as a radio button.</simpara>
</listitem> </listitem>
<listitem> <listitem>
<simpara><ulink <simpara><ulink
url="http://developer.gnome.org/doc/API/2.0/gtk/GtkCellEditable.html"> url="http://developer.gnome.org/doc/API/2.0/gtk/GtkCellEditable.html">
<literal>GtkCellEditable</literal></ulink> is a special cell that <classname>GtkCellEditable</classname></ulink> is a special cell that
implements editable cells (ie. GtkEntry or GtkSpinbutton in a implements editable cells (ie. GtkEntry or GtkSpinbutton in a
treeview). This is not a cell renderer! If you want to have editable treeview). This is not a cell renderer! If you want to have editable
text cells, use <literal>GtkCellRendererText</literal> and make sure text cells, use <classname>GtkCellRendererText</classname> and make sure
the "editable" property is set. <literal>GtkCellEditable</literal> the "editable" property is set. <classname>GtkCellEditable</classname>
is only used by implementations of editable cells and widgets that is only used by implementations of editable cells and widgets that
can be inside of editable cells. You are unlikely to ever need can be inside of editable cells. You are unlikely to ever need
it.</simpara> it.</simpara>
@ -2081,7 +2083,7 @@ yourself. Some code snippets:
<para>Here is a silly and utterly useless little example that <para>Here is a silly and utterly useless little example that
demonstrates this behaviour, and introduces some of the most commonly demonstrates this behaviour, and introduces some of the most commonly
used properties of <literal>GtkCellRendererText</literal>:</para> used properties of <classname>GtkCellRendererText</classname>:</para>
<programlisting role="C"> <programlisting role="C">
#include &lt;gtk/gtk.h&gt; #include &lt;gtk/gtk.h&gt;
@ -2286,11 +2288,11 @@ main (int argc, char **argv)
example a bit further above, you might have noticed that we set the example a bit further above, you might have noticed that we set the
<literal>"cell-background"</literal> property of a <ulink <literal>"cell-background"</literal> property of a <ulink
url="http://developer.gnome.org/doc/API/2.0/gtk/GtkCellRendererText.html"> url="http://developer.gnome.org/doc/API/2.0/gtk/GtkCellRendererText.html">
<literal>GtkCellRendererText</literal></ulink>, even though the API <classname>GtkCellRendererText</classname></ulink>, even though the API
documentation does not list such a property. We can do this, because documentation does not list such a property. We can do this, because
<literal>GtkCellRendererText</literal> is derived from <ulink <classname>GtkCellRendererText</classname> is derived from <ulink
url="http://developer.gnome.org/doc/API/2.0/gtk/GtkCellRenderer.html"> url="http://developer.gnome.org/doc/API/2.0/gtk/GtkCellRenderer.html">
<literal>GtkCellRenderer</literal></ulink>, which does in fact <ulink <classname>GtkCellRenderer</classname></ulink>, which does in fact <ulink
url="http://developer.gnome.org/doc/API/2.0/gtk/GtkCellRenderer.html#GtkCellRenderer--cell-background"> url="http://developer.gnome.org/doc/API/2.0/gtk/GtkCellRenderer.html#GtkCellRenderer--cell-background">
have</ulink> such a property. Derived classes inherit the properties of have</ulink> such a property. Derived classes inherit the properties of
their parents. This is the same as with widgets that you can cast into their parents. This is the same as with widgets that you can cast into
@ -2300,11 +2302,11 @@ main (int argc, char **argv)
object is derived from.</para> object is derived from.</para>
<para>There are two more noteworthy things about <para>There are two more noteworthy things about
<literal>GtkCellRenderer</literal> properties: one is that sometimes <classname>GtkCellRenderer</classname> properties: one is that sometimes
there are different properties which do the same, but take different there are different properties which do the same, but take different
arguments, such as the <literal>"foreground"</literal> and arguments, such as the <literal>"foreground"</literal> and
<literal>"foreground-gdk"</literal> properties of <literal>"foreground-gdk"</literal> properties of
<literal>GtkCellRendererText</literal> (which specify the text colour). <classname>GtkCellRendererText</classname> (which specify the text colour).
The <literal>"foreground"</literal> property take a colour in string The <literal>"foreground"</literal> property take a colour in string
form, such as "Orange" or "CornflowerBlue", whereas form, such as "Orange" or "CornflowerBlue", whereas
<literal>"foreground-gdk"</literal> takes a <ulink <literal>"foreground-gdk"</literal> takes a <ulink
@ -2485,7 +2487,7 @@ main (int argc, char **argv)
properties according to values stored in the tree model (if any are properties according to values stored in the tree model (if any are
mapped via <literal>gtk_tree_view_column_add_attribute</literal> or mapped via <literal>gtk_tree_view_column_add_attribute</literal> or
one of the convenience functions that do the same thing), and then one of the convenience functions that do the same thing), and then
pass on the <literal>GValue</literal> retrieved to pass on the <classname>GValue</classname> retrieved to
<literal>g_object_set_property</literal>.</para> <literal>g_object_set_property</literal>.</para>
</footnote>.</para> </footnote>.</para>
@ -2883,7 +2885,7 @@ main (int argc, char **argv)
<para>So far we have only put text in the tree view. While everything <para>So far we have only put text in the tree view. While everything
you need to know to display icons (in the form of you need to know to display icons (in the form of
<literal>GdkPixbuf</literal>s) has been introduced in the previous <classname>GdkPixbuf</classname>s) has been introduced in the previous
sections, a short example might help to make things clearer. The sections, a short example might help to make things clearer. The
following code will pack an icon and some text into the same tree view following code will pack an icon and some text into the same tree view
column:</para> column:</para>
@ -2963,11 +2965,11 @@ main (int argc, char **argv)
<para>Note that the tree view will not resize icons for you, but <para>Note that the tree view will not resize icons for you, but
displays them in their original size. If you want to display <ulink displays them in their original size. If you want to display <ulink
url="http://developer.gnome.org/doc/API/2.0/gtk/gtk-Stock-Items.html"> url="http://developer.gnome.org/doc/API/2.0/gtk/gtk-Stock-Items.html">
stock icons</ulink> instead of <literal>GdkPixbuf</literal>s loaded from stock icons</ulink> instead of <classname>GdkPixbuf</classname>s loaded from
file, you should have a look at the <literal>"stock-id"</literal> file, you should have a look at the <literal>"stock-id"</literal>
property of <ulink property of <ulink
url="http://developer.gnome.org/doc/API/2.0/gtk/GtkCellRendererPixbuf.html"> url="http://developer.gnome.org/doc/API/2.0/gtk/GtkCellRendererPixbuf.html">
<literal>GtkCellRendererPixbuf</literal></ulink> (and your model column <classname>GtkCellRendererPixbuf</classname></ulink> (and your model column
should be of type <literal>G_TYPE_STRING</literal>, as all stock IDs are should be of type <literal>G_TYPE_STRING</literal>, as all stock IDs are
just strings by which to identify the stock icon).</para> just strings by which to identify the stock icon).</para>
</sect1> </sect1>
@ -2982,8 +2984,8 @@ main (int argc, char **argv)
<para>One of the most basic features of a list or tree view is that rows <para>One of the most basic features of a list or tree view is that rows
can be selected or unselected. Selections are handled using the <ulink can be selected or unselected. Selections are handled using the <ulink
url="http://developer.gnome.org/doc/API/2.0/gtk/GtkTreeSelection.html"> url="http://developer.gnome.org/doc/API/2.0/gtk/GtkTreeSelection.html">
<literal>GtkTreeSelection</literal></ulink> object of a tree view. Every <classname>GtkTreeSelection</classname></ulink> object of a tree view. Every
tree view automatically has a <literal>GtkTreeSelection</literal> tree view automatically has a <classname>GtkTreeSelection</classname>
associated with it, and you can get it using <ulink associated with it, and you can get it using <ulink
url="http://developer.gnome.org/doc/API/2.0/gtk/GtkTreeView.html#gtk-tree-view-get-selection"> url="http://developer.gnome.org/doc/API/2.0/gtk/GtkTreeView.html#gtk-tree-view-get-selection">
<literal>gtk_tree_view_get_selection</literal></ulink>. Selections are <literal>gtk_tree_view_get_selection</literal></ulink>. Selections are
@ -2992,7 +2994,7 @@ main (int argc, char **argv)
particular reason why selection handling could not have been implemented particular reason why selection handling could not have been implemented
with functions that access the tree view widget directly, but for with functions that access the tree view widget directly, but for
reasons of API cleanliness and code clarity the Gtk+ developers decided reasons of API cleanliness and code clarity the Gtk+ developers decided
to create this special <literal>GtkTreeSelection</literal> object that to create this special <classname>GtkTreeSelection</classname> object that
then internally deals with the tree view widget. You will never need to then internally deals with the tree view widget. You will never need to
create a tree selection object, it will be created for you automatically create a tree selection object, it will be created for you automatically
when you create a new tree view. You only need to use said when you create a new tree view. You only need to use said
@ -3045,7 +3047,7 @@ main (int argc, char **argv)
all selected rows using <ulink all selected rows using <ulink
url="http://developer.gnome.org/doc/API/2.0/gtk/GtkTreeSelection.html#gtk-tree-selection-selected-foreach"> url="http://developer.gnome.org/doc/API/2.0/gtk/GtkTreeSelection.html#gtk-tree-selection-selected-foreach">
<literal>gtk_tree_selection_selected_foreach</literal></ulink> or get <literal>gtk_tree_selection_selected_foreach</literal></ulink> or get
a <literal>GList</literal> of tree paths of the selected rows using a <classname>GList</classname> of tree paths of the selected rows using
<ulink <ulink
url="http://developer.gnome.org/doc/API/2.0/gtk/GtkTreeSelection.html#gtk-tree-selection-get-selected-rows"> url="http://developer.gnome.org/doc/API/2.0/gtk/GtkTreeSelection.html#gtk-tree-selection-get-selected-rows">
<literal>gtk_tree_selection_get_selected_rows</literal></ulink>. Note <literal>gtk_tree_selection_get_selected_rows</literal></ulink>. Note
@ -3538,14 +3540,14 @@ main (int argc, char **argv)
<para>Lists and trees are meant to be sorted. This is done using the <para>Lists and trees are meant to be sorted. This is done using the
<ulink <ulink
url="http://developer.gnome.org/doc/API/2.0/gtk/GtkTreeSortable.html"> url="http://developer.gnome.org/doc/API/2.0/gtk/GtkTreeSortable.html">
<literal>GtkTreeSortable</literal></ulink> interface that can be <classname>GtkTreeSortable</classname></ulink> interface that can be
implemented by tree models. 'Interface' means that you can just cast a implemented by tree models. 'Interface' means that you can just cast a
<literal>GtkTreeModel</literal> into a <literal>GtkTreeSortable</literal> <classname>GtkTreeModel</classname> into a <classname>GtkTreeSortable</classname>
with <literal>GTK_TREE_SORTABLE(model)</literal> and use the documented with <literal>GTK_TREE_SORTABLE(model)</literal> and use the documented
tree sortable functions on it, just like we did before when we cast a list tree sortable functions on it, just like we did before when we cast a list
store to a tree model and used the <literal>gtk_tree_model_foo</literal> store to a tree model and used the <literal>gtk_tree_model_foo</literal>
family of functions. Both <literal>GtkListStore</literal> and family of functions. Both <classname>GtkListStore</classname> and
<literal>GtkTreeStore</literal> implement the tree sortable <classname>GtkTreeStore</classname> implement the tree sortable
interface.</para> interface.</para>
<para>The most straight forward way to sort a list store or tree store is <para>The most straight forward way to sort a list store or tree store is
@ -3565,7 +3567,7 @@ main (int argc, char **argv)
special meaning and needs to be restored at some point. This is where special meaning and needs to be restored at some point. This is where
<ulink <ulink
url="http://developer.gnome.org/doc/API/2.0/gtk/GtkTreeModelSort.html"> url="http://developer.gnome.org/doc/API/2.0/gtk/GtkTreeModelSort.html">
<literal>GtkTreeModelSort</literal></ulink> comes in, which is a special <classname>GtkTreeModelSort</classname></ulink> comes in, which is a special
model that maps the unsorted rows of a child model (e.g. a list store or model that maps the unsorted rows of a child model (e.g. a list store or
tree store) into a sorted state without changing the child model.</para> tree store) into a sorted state without changing the child model.</para>
@ -3747,7 +3749,7 @@ main (int argc, char **argv)
<para><ulink <para><ulink
url="http://developer.gnome.org/doc/API/2.0/gtk/GtkTreeModelSort.html"> url="http://developer.gnome.org/doc/API/2.0/gtk/GtkTreeModelSort.html">
<literal>GtkTreeModelSort</literal></ulink> is a wrapper tree model. It <classname>GtkTreeModelSort</classname></ulink> is a wrapper tree model. It
takes another tree model such as a list store or a tree store as child takes another tree model such as a list store or a tree store as child
model, and presents the child model to the 'outside' (ie. a tree view or model, and presents the child model to the 'outside' (ie. a tree view or
whoever else is accessing it via the tree model interface) in a sorted whoever else is accessing it via the tree model interface) in a sorted
@ -3757,8 +3759,8 @@ main (int argc, char **argv)
example, or if you need to restore the original unsorted state of your example, or if you need to restore the original unsorted state of your
store again at some point.</para> store again at some point.</para>
<para><literal>GtkTreeModelSort</literal> implements the <para><classname>GtkTreeModelSort</classname> implements the
<literal>GtkTreeSortable</literal> interface, so you can treat it just <classname>GtkTreeSortable</classname> interface, so you can treat it just
as if it was your data store for sorting purposes. Here is the basic as if it was your data store for sorting purposes. Here is the basic
setup with a tree view:</para> setup with a tree view:</para>
@ -3901,7 +3903,7 @@ main (int argc, char **argv)
<sect1 id="sec-editable-cells-text"> <sect1 id="sec-editable-cells-text">
<title>Editable Text Cells</title> <title>Editable Text Cells</title>
<para>With <literal>GtkCellRendererText</literal> you can not only <para>With <classname>GtkCellRendererText</classname> you can not only
display text, but you can also allow the user to edit a single cell's display text, but you can also allow the user to edit a single cell's
text right in the tree view by double-clicking on a cell.</para> text right in the tree view by double-clicking on a cell.</para>
@ -4033,9 +4035,9 @@ void cell_edited_callback (GtkCellRendererText *cell,
<sect1 id="sec-editable-cells-toggle"> <sect1 id="sec-editable-cells-toggle">
<title>Editable Toggle and Radio Button Cells</title> <title>Editable Toggle and Radio Button Cells</title>
<para>Just like you can set a <literal>GtkCellRendererText</literal> <para>Just like you can set a <classname>GtkCellRendererText</classname>
editable, you can specify whether a editable, you can specify whether a
<literal>GtkCellRendererToggle</literal> should change its state when <classname>GtkCellRendererToggle</classname> should change its state when
clicked by setting the <literal>"activatable"</literal> property - clicked by setting the <literal>"activatable"</literal> property -
either when you create the renderer (in which case all cells in that either when you create the renderer (in which case all cells in that
column will be clickable) or by connecting the renderer property to a column will be clickable) or by connecting the renderer property to a
@ -4063,7 +4065,7 @@ void cell_toggled_callback (GtkCellRendererToggle *cell,
<para>Just like with the <literal>"edited"</literal> signal of the text <para>Just like with the <literal>"edited"</literal> signal of the text
cell renderer, the tree path is passed to the cell renderer, the tree path is passed to the
<literal>"toggled"</literal> signal callback in string form. You can <literal>"toggled"</literal> signal callback in string form. You can
convert this into a <literal>GtkTreePath</literal> with <ulink convert this into a <classname>GtkTreePath</classname> with <ulink
url="http://developer.gnome.org/doc/API/2.0/gtk/GtkTreeModel.html#gtk-tree-path-new-from-string"> url="http://developer.gnome.org/doc/API/2.0/gtk/GtkTreeModel.html#gtk-tree-path-new-from-string">
<literal>gtk_tree_path_new_from_string</literal></ulink>, or convert it <literal>gtk_tree_path_new_from_string</literal></ulink>, or convert it
into an iter with <ulink into an iter with <ulink
@ -4074,15 +4076,15 @@ void cell_toggled_callback (GtkCellRendererToggle *cell,
<sect1 id="sec-editable-cells-spin"> <sect1 id="sec-editable-cells-spin">
<title>Editable Spin Button Cells</title> <title>Editable Spin Button Cells</title>
<para>Even though <literal>GtkSpinButton</literal> implements the <para>Even though <classname>GtkSpinButton</classname> implements the
<literal>GtkCellEditable</literal> interface (as does <classname>GtkCellEditable</classname> interface (as does
<literal>GtkEntry</literal>), there is no easy way to get a cell <classname>GtkEntry</classname>), there is no easy way to get a cell
renderer that uses a spin button instead of a normal entry when in renderer that uses a spin button instead of a normal entry when in
editing mode.</para> editing mode.</para>
<para>To get this functionality, you need to either write a new cell <para>To get this functionality, you need to either write a new cell
renderer that works very similar to renderer that works very similar to
<literal>GtkCellRendererText</literal>, or you need to write a new cell <classname>GtkCellRendererText</classname>, or you need to write a new cell
renderer class that derives from the text cell renderer and changes the renderer class that derives from the text cell renderer and changes the
behaviour in editing mode.</para> behaviour in editing mode.</para>
@ -4096,7 +4098,7 @@ void cell_toggled_callback (GtkCellRendererToggle *cell,
<para>Among this tutorial's code examples there is a hackish <para>Among this tutorial's code examples there is a hackish
CellRendererSpin implementation which is based on CellRendererSpin implementation which is based on
<literal>GtkCellRendererText</literal> and shows spin buttons in editing <classname>GtkCellRendererText</classname> and shows spin buttons in editing
mode. The implementation is not very refined though, so you need to make mode. The implementation is not very refined though, so you need to make
sure it works in your particular context, and modify it as sure it works in your particular context, and modify it as
needed.</para> needed.</para>
@ -4115,7 +4117,7 @@ void cell_toggled_callback (GtkCellRendererToggle *cell,
<title>Getting the Column Number from a Tree View Column Widget</title> <title>Getting the Column Number from a Tree View Column Widget</title>
<para>Signal callbacks often only get passed a pointer to a <para>Signal callbacks often only get passed a pointer to a
<literal>GtkTreeViewColumn</literal> when the application programmer <classname>GtkTreeViewColumn</classname> when the application programmer
really just wants to know which column <emphasis>number</emphasis> was really just wants to know which column <emphasis>number</emphasis> was
affected. There are two ways to find out the position of a column within affected. There are two ways to find out the position of a column within
the tree view. One way is to write a small helper function that looks up the tree view. One way is to write a small helper function that looks up
@ -4356,7 +4358,7 @@ onButtonPress (GtkWidget *view, GdkEventButton *bevent, gpointer data)
<title>Glade and Tree Views</title> <title>Glade and Tree Views</title>
<para>A frequently asked question is how you can add columns to a <para>A frequently asked question is how you can add columns to a
<literal>GtkTreeView</literal> in <ulink <classname>GtkTreeView</classname> in <ulink
url="http://glade.gnome.org">Glade</ulink>. <footnote> url="http://glade.gnome.org">Glade</ulink>. <footnote>
<para>Do <emphasis>not</emphasis> use Glade to generate code for <para>Do <emphasis>not</emphasis> use Glade to generate code for
you. Use Glade to create the interface. It will save the interface you. Use Glade to create the interface. It will save the interface
@ -4368,16 +4370,16 @@ onButtonPress (GtkWidget *view, GdkEventButton *bevent, gpointer data)
should avoid Glade code generation</ulink>.</para> should avoid Glade code generation</ulink>.</para>
</footnote> The answer is basically that you don't, and that you </footnote> The answer is basically that you don't, and that you
can't. The only thing glade/libglade can do for you is to create the can't. The only thing glade/libglade can do for you is to create the
<literal>GtkTreeView</literal> for you with nothing in it. You will need <classname>GtkTreeView</classname> for you with nothing in it. You will need
to look up the tree view widget at the start of your application (after to look up the tree view widget at the start of your application (after
the interface has been created of course), and connect your list store the interface has been created of course), and connect your list store
or tree store to it. Then you will need to add or tree store to it. Then you will need to add
<literal>GtkTreeViewColumn</literal>s and cell renderers to display the <classname>GtkTreeViewColumn</classname>s and cell renderers to display the
information from the model as you want it to be displayed. You will need information from the model as you want it to be displayed. You will need
to do all that from within your application.</para> to do all that from within your application.</para>
<para>An alternative approach is to derive your own special widget from <para>An alternative approach is to derive your own special widget from
<literal>GtkTreeView</literal> that sets up everything as you want it <classname>GtkTreeView</classname> that sets up everything as you want it
to, and then use the 'custom widget' function in glade. Of course this to, and then use the 'custom widget' function in glade. Of course this
still means that you have to write all the code to fill in the columns still means that you have to write all the code to fill in the columns
and cell renderers and to create the model yourself.</para> and cell renderers and to create the model yourself.</para>
@ -4616,10 +4618,10 @@ view_onDragMotion (GtkWidget *widget, GdkDragContext *context, gint x,
<para>****** TODO</para> <para>****** TODO</para>
<para>Both <literal>GtkListStore</literal> and <para>Both <classname>GtkListStore</classname> and
<literal>GtkTreeStore</literal> implement the <classname>GtkTreeStore</classname> implement the
<literal>GtkTreeDragDest</literal> and <classname>GtkTreeDragDest</classname> and
<literal>GtkTreeDragSource</literal> interfaces, which means that they <classname>GtkTreeDragSource</classname> interfaces, which means that they
have in-built support for row reordering. You need to call have in-built support for row reordering. You need to call
<literal>gtk_tree_view_set_reorderable</literal> to activate this, and <literal>gtk_tree_view_set_reorderable</literal> to activate this, and
then connect to the tree model's signals to catch the reorderings that then connect to the tree model's signals to catch the reorderings that
@ -4663,9 +4665,9 @@ view_onDragMotion (GtkWidget *widget, GdkDragContext *context, gint x,
<para>Using a custom model you could also implement a filter model that <para>Using a custom model you could also implement a filter model that
only displays certain rows according to some filter criterion instead of only displays certain rows according to some filter criterion instead of
displaying all rows (Gtk+-2.4 has a filter model, <literal> <ulink displaying all rows (Gtk+-2.4 has a filter model, <classname> <ulink
url="http://developer.gnome.org/doc/API/2.0/gtk/GtkTreeModelFilter.html"> url="http://developer.gnome.org/doc/API/2.0/gtk/GtkTreeModelFilter.html">
GtkTreeModelFilter</ulink></literal>, that does exactly that and much GtkTreeModelFilter</ulink></classname>, that does exactly that and much
more, but you might want to implement this yourself anyway. If you need more, but you might want to implement this yourself anyway. If you need
to use GtkTreeModelFilter in Gtk-2.0 or Gtk-2.2, check out the code to use GtkTreeModelFilter in Gtk-2.0 or Gtk-2.2, check out the code
examples of this tutorial - there is GuiTreeModelFilter, which is examples of this tutorial - there is GuiTreeModelFilter, which is
@ -4685,8 +4687,8 @@ view_onDragMotion (GtkWidget *widget, GdkDragContext *context, gint x,
<title>What Does Writing a Custom Model Involve?</title> <title>What Does Writing a Custom Model Involve?</title>
<para>Basically, all you need to do is to write a new GObject that <para>Basically, all you need to do is to write a new GObject that
implements the <literal>GtkTreeModel</literal> interface, implements the <classname>GtkTreeModel</classname> interface,
<literal>GtkTreeModelIface</literal>. Intimate knowledge about the GLib <classname>GtkTreeModelIface</classname>. Intimate knowledge about the GLib
GObject system is not a requirement - you just need to copy some GObject system is not a requirement - you just need to copy some
boilerplate code and modify it a bit. The core of your custom tree model boilerplate code and modify it a bit. The core of your custom tree model
is your own implementation of a couple of is your own implementation of a couple of
@ -4781,15 +4783,15 @@ view_onDragMotion (GtkWidget *widget, GdkDragContext *context, gint x,
implementation of the tree model functions.</para> implementation of the tree model functions.</para>
<para>Our list model is represented by a simple list of records, where <para>Our list model is represented by a simple list of records, where
each row corresponds to a <literal>CustomRecord</literal> structure each row corresponds to a <classname>CustomRecord</classname> structure
which keeps track of the data we are interested in. For now, we only which keeps track of the data we are interested in. For now, we only
want to keep track of persons' names and years of birth (usually this want to keep track of persons' names and years of birth (usually this
would not really justify a custom model, but this is still just an would not really justify a custom model, but this is still just an
example). It is trivial to extend the model to deal with additional example). It is trivial to extend the model to deal with additional
fields in the <literal>CustomRecord</literal> structure.</para> fields in the <classname>CustomRecord</classname> structure.</para>
<para>Within the model, more precisely: the <para>Within the model, more precisely: the
<literal>CustomList</literal> structure, the list is stored as a pointer <classname>CustomList</classname> structure, the list is stored as a pointer
array, which not only provides fast access to the n-th record in the array, which not only provides fast access to the n-th record in the
list, but also comes in handy later on when we add sorting. Apart from list, but also comes in handy later on when we add sorting. Apart from
that, any other kind of list-specific data would go in this structure as that, any other kind of list-specific data would go in this structure as
@ -4797,7 +4799,7 @@ view_onDragMotion (GtkWidget *widget, GdkDragContext *context, gint x,
searching for a specific row, etc.).</para> searching for a specific row, etc.).</para>
<para>Each row in our list is represented by a <para>Each row in our list is represented by a
<literal>CustomRecord</literal> structure. You can store whatever other <classname>CustomRecord</classname> structure. You can store whatever other
data you need in that structure. How you make row data available is up data you need in that structure. How you make row data available is up
to you. Either you export it via the tree model interface using the to you. Either you export it via the tree model interface using the
<ulink <ulink
@ -4816,7 +4818,7 @@ view_onDragMotion (GtkWidget *widget, GdkDragContext *context, gint x,
<para>Some thought should go into how exactly you fill the <ulink <para>Some thought should go into how exactly you fill the <ulink
url="http://developer.gnome.org/doc/API/2.0/gtk/GtkTreeModel.html#GtkTreeIter"> url="http://developer.gnome.org/doc/API/2.0/gtk/GtkTreeModel.html#GtkTreeIter">
<literal>GtkTreeIter</literal> fields</ulink> of the tree iters used by <classname>GtkTreeIter</classname> fields</ulink> of the tree iters used by
your model. You have three pointer fields at your disposal. These should your model. You have three pointer fields at your disposal. These should
be filled so that you can easily identify the row given the iter, and be filled so that you can easily identify the row given the iter, and
should also facilitate access to the next row and the parent row (if should also facilitate access to the next row and the parent row (if
@ -4833,9 +4835,9 @@ view_onDragMotion (GtkWidget *widget, GdkDragContext *context, gint x,
of lines of code to print here).</para> of lines of code to print here).</para>
<para>In our specific example, we simply store a pointer to a row's <para>In our specific example, we simply store a pointer to a row's
<literal>CustomRecord</literal> structure in our model's tree iters, <classname>CustomRecord</classname> structure in our model's tree iters,
which is valid as long as the row exists. Additionally we store the which is valid as long as the row exists. Additionally we store the
position of a row within the list in the <literal>CustomRecord</literal> position of a row within the list in the <classname>CustomRecord</classname>
as well, which is not only intuitive, but is also useful later on when as well, which is not only intuitive, but is also useful later on when
we resort the list.</para> we resort the list.</para>
@ -4850,12 +4852,12 @@ view_onDragMotion (GtkWidget *widget, GdkDragContext *context, gint x,
<para>The <link linkend="sec-custom-model-code-header">header <para>The <link linkend="sec-custom-model-code-header">header
file</link> for our custom list model defines some standard type casts file</link> for our custom list model defines some standard type casts
and type check macros, our <literal>CustomRecord</literal> structure, and type check macros, our <classname>CustomRecord</classname> structure,
our <literal>CustomList</literal> structure, and some enums for the our <classname>CustomList</classname> structure, and some enums for the
model columns we are exporting.</para> model columns we are exporting.</para>
<para>The <literal>CustomRecord</literal> structure represents one <para>The <classname>CustomRecord</classname> structure represents one
row, while the <literal>CustomList</literal> structure contains all row, while the <classname>CustomList</classname> structure contains all
list-specific data. You can add additional fields to both structures list-specific data. You can add additional fields to both structures
without problems. For example, you might need a function that quickly without problems. For example, you might need a function that quickly
looks up rows given the name or year of birth, for which additional looks up rows given the name or year of birth, for which additional
@ -4884,9 +4886,9 @@ view_onDragMotion (GtkWidget *widget, GdkDragContext *context, gint x,
<literal>custom_list_init</literal> we define what data type our <literal>custom_list_init</literal> we define what data type our
exported model columns have, and how many columns we export. Towards exported model columns have, and how many columns we export. Towards
the end of <literal>custom_list_get_type</literal> we register the the end of <literal>custom_list_get_type</literal> we register the
<literal>GtkTreeModel</literal> interface with our custom model <classname>GtkTreeModel</classname> interface with our custom model
object. This is where we can also register additional interfaces (e.g. object. This is where we can also register additional interfaces (e.g.
<literal>GtkTreeSortable</literal> or one of the Drag'n'Drop <classname>GtkTreeSortable</classname> or one of the Drag'n'Drop
interfaces) that we want to implement.</para> interfaces) that we want to implement.</para>
<para>In <literal>custom_list_tree_model_init</literal> we override <para>In <literal>custom_list_tree_model_init</literal> we override
@ -5122,11 +5124,11 @@ custom_list_tree_model_init (GtkTreeModelIface *iface)
list model, but follows the same pattern. Basically you just need to list model, but follows the same pattern. Basically you just need to
extend the above model to cater for the case of children. You could do extend the above model to cater for the case of children. You could do
this by keeping track of the whole tree hierarchy in the this by keeping track of the whole tree hierarchy in the
<literal>CustomList</literal> structure, using GLib N-ary trees for <classname>CustomList</classname> structure, using GLib N-ary trees for
example, or you could do this by keeping track of each row's children example, or you could do this by keeping track of each row's children
within the row's <literal>CustomRecord</literal> structure, keeping only within the row's <classname>CustomRecord</classname> structure, keeping only
a pointer to the (invisible) root record in the a pointer to the (invisible) root record in the
<literal>CustomList</literal> structure.</para> <classname>CustomList</classname> structure.</para>
<para>TODO: do we need anything else here?</para> <para>TODO: do we need anything else here?</para>
</sect1> </sect1>
@ -5156,7 +5158,7 @@ custom_list_tree_model_init (GtkTreeModelIface *iface)
</itemizedlist> </itemizedlist>
<para>Here, we will show how to implement additional interfaces at the <para>Here, we will show how to implement additional interfaces at the
example of the <literal>GtkTreeSortable</literal> interface, which we example of the <classname>GtkTreeSortable</classname> interface, which we
will implement only partially (enough to make it functional and useful will implement only partially (enough to make it functional and useful
though).</para> though).</para>
@ -5204,7 +5206,7 @@ custom_list_tree_model_init (GtkTreeModelIface *iface)
... ...
</programlisting> </programlisting>
<para>Next, let's extend our <literal>CustomList</literal> structure <para>Next, let's extend our <classname>CustomList</classname> structure
with a field for the currently active sort column ID and one for the with a field for the currently active sort column ID and one for the
sort order, and add an enum for the sort column IDs:</para> sort order, and add an enum for the sort column IDs:</para>
@ -6472,7 +6474,7 @@ main (int argc, char **argv)
extend its functionality.</para> extend its functionality.</para>
<para>You can do this by writing a new object that derives from <para>You can do this by writing a new object that derives from
<literal>GtkCellRenderer</literal> (or even one of the other cell <classname>GtkCellRenderer</classname> (or even one of the other cell
renderers if you just want to extend an existing one).</para> renderers if you just want to extend an existing one).</para>
<para>Three things you need to do in the course of that:</para> <para>Three things you need to do in the course of that:</para>
@ -6488,7 +6490,7 @@ main (int argc, char **argv)
<listitem> <listitem>
<para>Write your own <literal>cell_renderer_get_size</literal> <para>Write your own <literal>cell_renderer_get_size</literal>
function and override the parent object's function (usually the parent function and override the parent object's function (usually the parent
is of type <literal>GtkCellRenderer</literal>. Note that you should is of type <classname>GtkCellRenderer</classname>. Note that you should
honour the standard properties for padding and cell alignment of the honour the standard properties for padding and cell alignment of the
parent object here.</para> parent object here.</para>
</listitem> </listitem>
@ -6506,8 +6508,8 @@ main (int argc, char **argv)
according to your own needs.</para> according to your own needs.</para>
<para>Good examples of cell renderer code to look at or even modify are <para>Good examples of cell renderer code to look at or even modify are
<literal>GtkCellRendererPixbuf</literal> and <classname>GtkCellRendererPixbuf</classname> and
<literal>GtkCellRendererToggle</literal> in the Gtk+ source code tree. <classname>GtkCellRendererToggle</classname> in the Gtk+ source code tree.
Both cases are less than five hundred lines of code to look at and thus Both cases are less than five hundred lines of code to look at and thus
should be fairly easy to digest.</para> should be fairly easy to digest.</para>
@ -6539,14 +6541,14 @@ main (int argc, char **argv)
<title>custom-cell-renderer-progressbar.h</title> <title>custom-cell-renderer-progressbar.h</title>
<para>The header file consists of the usual GObject type cast and type <para>The header file consists of the usual GObject type cast and type
check defines and our <literal>CustomCellRendererProgress</literal> check defines and our <classname>CustomCellRendererProgress</classname>
structure. As the type of the parent indicates, we derive from structure. As the type of the parent indicates, we derive from
<literal>GtkCellRenderer</literal>. The parent object must always be <classname>GtkCellRenderer</classname>. The parent object must always be
the first item in the structure (note also that it is not a pointer to the first item in the structure (note also that it is not a pointer to
an object, but the parent object structure itself embedded in our an object, but the parent object structure itself embedded in our
structure).</para> structure).</para>
<para>Our <literal>CustomCellRendererProgress</literal> structure is <para>Our <classname>CustomCellRendererProgress</classname> structure is
fairly uneventful and contains only a double precision float variable fairly uneventful and contains only a double precision float variable
in which we store our new <literal>"percentage"</literal> property in which we store our new <literal>"percentage"</literal> property
(which will determine how long the progressbar is going to be).</para> (which will determine how long the progressbar is going to be).</para>
@ -6952,7 +6954,7 @@ custom_cell_renderer_progress_render (GtkCellRenderer *cell,
<title>main.c</title> <title>main.c</title>
<para>And here is a little test that makes use of our new <para>And here is a little test that makes use of our new
<literal>CustomCellRendererProgress</literal>:</para> <classname>CustomCellRendererProgress</classname>:</para>
<programlisting role="C"> <programlisting role="C">
#include "custom-cell-renderer-progressbar.h" #include "custom-cell-renderer-progressbar.h"