From cfdc3708182bc09411965b0a627e2572c8afeead Mon Sep 17 00:00:00 2001 From: Gergely Polonkai Date: Thu, 24 Jul 2014 00:07:40 +0200 Subject: [PATCH] Convert class names from to --- treeview-tutorial.xml | 322 +++++++++++++++++++++--------------------- 1 file changed, 162 insertions(+), 160 deletions(-) diff --git a/treeview-tutorial.xml b/treeview-tutorial.xml index 98ff62a..a8c2e94 100644 --- a/treeview-tutorial.xml +++ b/treeview-tutorial.xml @@ -48,39 +48,41 @@ Lists and Trees: the GtkTreeView Widget - GtkTreeView is a widget that displays single- or - multi-columned lists and trees. It replaces the old Gtk+-1.2 GtkCList and - GtkCTree widgets. Even though GtkTreeView is slightly - harder to master than its predecessors, it is so much more powerful and - flexible that most application developers will not want to miss it once - they have come to know it. + GtkTreeView is a widget that displays single- + or multi-columned lists and trees. It replaces the old Gtk+-1.2 + GtkCList and GtkCTree + widgets. Even though GtkTreeView is slightly harder + to master than its predecessors, it is so much more powerful and flexible + that most application developers will not want to miss it once they have + come to know it. The purpose of this chapter is not to provide an exhaustive - documentation of GtkTreeView - that is what the API + documentation of GtkTreeView – that is what the + API documentation is for, which should be read alongside with this tutorial. The goal is rather to present an introduction to the most - commonly-used aspects of GtkTreeView, and to - demonstrate how the various GtkTreeView components and + commonly-used aspects of GtkTreeView, and to + demonstrate how the various GtkTreeView components and 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 often-mentioned, but rarely explained. Developers looking for a quick and dirty introduction that teaches 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 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 more condensed form anyway. Those who disagree may jump straight to the working example code of course. Please note that the code examples in the following sections do not - necessarily demonstrate how GtkTreeView is used best in - a particular situation. There are different ways to achieve the same - result, and the examples merely show those different ways, so that + necessarily demonstrate how GtkTreeView is used + best in a particular situation. There are different ways to achieve the + 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 hand. @@ -213,31 +215,31 @@ main (int argc, char **argv) Components: Model, Renderer, Column, View - The most important concept underlying GtkTreeView - is that of complete separation between data and how that data is displayed - on the screen. This is commonly known as Model/View/Controller-design - (MVC). Data of various type (strings, numbers, images, etc.) is stored in - a 'model'. The 'view' is then told which data to display, where to display - it, and how to display it. One of the advantages of this approach is that - you can have multiple views that display the same data (a directory tree - for example) in different ways, or in the same way multiple times, with - only one copy of the underlying data. This avoids duplication of data and - programming effort if the same data is re-used in different contexts. - Also, when the data in the model is updated, all views automatically get - updated as well. + The most important concept underlying + GtkTreeView is that of complete separation between + data and how that data is displayed on the screen. This is commonly known + as Model/View/Controller design (MVC). Data of various type (strings, + numbers, images, etc.) is stored in a 'model'. The 'view' is then told + which data to display, where to display it, and how to display it. One of + the advantages of this approach is that you can have multiple views that + display the same data (a directory tree for example) in different ways, or + in the same way multiple times, with only one copy of the underlying data. + This avoids duplication of data and programming effort if the same data is + re-used in different contexts. Also, when the data in the model is + updated, all views automatically get updated as well. - So, while GtkTreeModel is used to store data, + So, while GtkTreeModel is used to store data, there are other components that determine which data is displayed in the - GtkTreeView and how it is displayed. These components - are GtkTreeViewColumn and - GtkCellRenderer. A GtkTreeView is + GtkTreeView and how it is displayed. These + components are GtkTreeViewColumn and + GtkCellRenderer. A GtkTreeView is 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 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 tree view (sorting etc.) and serve as packing widgets for the components that do the actual rendering of data onto the screen, namely the - GtkCellRenderer family of objects (I call them + GtkCellRenderer family of objects (I call them 'objects' because they are not GtkWidgets). There are a number of different cell renderers that specialise in rendering certain data like strings, pixbufs, or toggle buttons. More on this GtkCellRendererPixbuf and a - GtkCellRendererText into one tree view column. Packing + GtkCellRendererPixbuf and a + GtkCellRendererText into one tree view column. Packing renderers into a tree view column is similar to packing widgets into a - GtkHBox. + GtkHBox. @@ -259,57 +261,57 @@ main (int argc, char **argv) GtkTreeStore It is important to realise what GtkTreeModel - is and what it is not. GtkTreeModel is basically just + url="http://developer.gnome.org/doc/API/2.0/gtk/GtkTreeModel.html">GtkTreeModel + is and what it is not. GtkTreeModel is basically just an 'interface' to the data store, meaning that it is a standardised set of - functions that allows a GtkTreeView widget (and the + functions that allows a GtkTreeView widget (and the application programmer) to query certain characteristics of a data store, 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 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 - GtkTreeModel interface and provide these functions, + GtkTreeModel interface and provide these functions, which you can use by casting a store to a tree model with - GTK_TREE_MODEL(store). GtkTreeModel + GTK_TREE_MODEL(store). GtkTreeModel 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 the store or put data into the store. This is done using the specific store's functions. Gtk+ comes with two built-in data stores (models): GtkListStore + url="http://developer.gnome.org/doc/API/2.0/gtk/GtkListStore.html">GtkListStore and GtkTreeStore. - As the names imply, GtkListStore is used for simple + url="http://developer.gnome.org/doc/API/2.0/gtk/GtkTreeStore.html">GtkTreeStore. + As the names imply, GtkListStore is used for simple lists of data items where items have no hierarchical parent-child - relationships, and GtkTreeStore is used for tree-like + relationships, and GtkTreeStore is used for tree-like 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, 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 children, so one could use a tree store to maintain a simple list of items - as well. The only reason GtkListStore exists is in + as well. The only reason GtkListStore exists is in order to provide an easier interface that does not need to cater for child-parent relationships, and because a simple list model can be optimised for the special case where no children exist, which makes it faster and more efficient. - GtkListStore and GtkTreeStore + GtkListStore and GtkTreeStore should cater for most types of data an application developer might want to - display in a GtkTreeView. However, it should be noted - that GtkListStore and GtkTreeStore + display in a GtkTreeView. However, it should be noted + that GtkListStore and GtkTreeStore 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 your own custom model that stores and manipulates data your own way and - implements the GtkTreeModel interface. This will not + implements the GtkTreeModel interface. This will not only be more efficient, but probably also lead to saner code in the long run, and give you more control over your data. See below for more details on how to implement custom models. - Tree model implementations like GtkListStore and - GtkTreeStore will take care of the view side for you - once you have configured the GtkTreeView to display + Tree model implementations like GtkListStore and + GtkTreeStore will take care of the view side for you + once you have configured the GtkTreeView to display 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 rows, the model will also notify the store, and your row will appear in or @@ -391,7 +393,7 @@ main (int argc, char **argv) G_TYPE_POINTER will often do as well, you will just need to take care of memory allocation and freeing yourself then. - Storing GObject-derived types (most + Storing GObject-derived types (most GDK_TYPE_FOO and GTK_TYPE_FOO) is a special case that is dealt with further below. @@ -416,17 +418,17 @@ main (int argc, char **argv) GtkTreeRowReference There are different ways to refer to a specific row. The two you - will have to deal with are GtkTreeIter and - GtkTreePath. + will have to deal with are GtkTreeIter and + GtkTreePath. GtkTreePath Describing a row 'geographically' - A GtkTreePath is a comparatively + A GtkTreePath is a comparatively straight-forward way to describe the logical position of a row in the - model. As a GtkTreeView always displays + model. As a GtkTreeView always displays all rows in a model, a tree path always describes the same row in both model and view. @@ -475,7 +477,7 @@ main (int argc, char **argv) row than it refered to before the insertion/deletion/resorting. This is important to keep in mind. (See the section on - GtkTreeRowReferences below for a tree path + GtkTreeRowReferences below for a tree path that keeps updating itself to make sure it always refers to the same row when the model changes). @@ -485,14 +487,14 @@ main (int argc, char **argv) and only child of 'clips', and be described by the tree path that formerly belonged to 'funny clips', ie. "1:0:0". - You can get a new GtkTreePath from a path in + You can get a new GtkTreePath from a path in string form using gtk_tree_path_new_from_string, - and you can convert a given GtkTreePath into its + and you can convert a given GtkTreePath into its string notation with gtk_tree_path_to_string. Usually you will rarely have to handle the string notation, it is described here merely to demonstrate the concept of tree paths. - Instead of the string notation, GtkTreePath + Instead of the string notation, GtkTreePath uses an integer array internally. You can get the depth (ie. the nesting level) of a tree path with @@ -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"> gtk_tree_model_get_iter. - GtkTreePath is an opaque structure, with its + GtkTreePath is an opaque structure, with its details hidden from the compiler. If you need to make a copy of a tree path, use @@ -540,7 +542,7 @@ main (int argc, char **argv) Refering to a row in model-speak Another way to refer to a row in a list or tree is - GtkTreeIter. A tree iter is just a structure that + GtkTreeIter. A tree iter is just a structure that contains a couple of pointers that mean something to the model you are using. Tree iters are used internally by models, and they often 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. All tree models (and therefore also - GtkListStore and GtkTreeStore) + GtkListStore and GtkTreeStore) must support the - GtkTreeModel functions that operate on tree + GtkTreeModel functions that operate on tree 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 child of a given iter etc.). Some of these functions are: @@ -617,7 +619,7 @@ main (int argc, char **argv) otherwise. There are more functions that operate on iters. Check out the - GtkTreeModel API reference for + GtkTreeModel API reference for details. 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 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: - GtkTreeRowReference + GtkTreeRowReference @@ -648,7 +650,7 @@ main (int argc, char **argv) Keeping track of rows even when the model changes - A GtkTreeRowReference is basically an object + A GtkTreeRowReference is basically an object that takes a tree path, and watches a model for changes. If anything changes, like rows getting inserted or removed, or rows getting re-ordered, the tree row reference object will keep the given tree @@ -703,7 +705,7 @@ main (int argc, char **argv) In practice, a programmer can either use tree row references to keep track of rows over time, or store tree iters directly (if, and only if, the model has persistent iters). Both - GtkListStore and GtkTreeStore + GtkListStore and GtkTreeStore have persistent iters, so storing iters is possible. However, using tree row references is definitively the Right Way(tm) to do things, 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). Especially beginners might find it easier to handle and store tree row references than iters, because tree row references are handled by - pointer value, which you can easily add to a GList + pointer value, which you can easily add to a GList or pointer array, while it is easy to store tree iters in a wrong way. @@ -772,7 +774,7 @@ onTreeViewRowActivated (GtkTreeView *view, GtkTreePath *path, 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 - GtkTreeIter is just a structure that contains data + GtkTreeIter is just a structure that contains data fields you do not need to know anything about): @@ -1063,7 +1065,7 @@ onTreeViewRowActivated (GtkTreeView *view, GtkTreePath *path, Here is the previous example extended to traverse the list store and print out the data stored. As an extra, we use gtk_tree_model_foreach to traverse the store and - retrieve the row number from the GtkTreePath passed + retrieve the row number from the GtkTreePath passed to us in the foreach callback function: @@ -1186,8 +1188,8 @@ onTreeViewRowActivated (GtkTreeView *view, GtkTreePath *path, g_free the string returned when you don't need it any longer, as in the example above. - If you retrieve a GObject such as a - GdkPixbuf from the store, + If you retrieve a GObject such as a + GdkPixbuf from the store, gtk_tree_model_get will automatically add a reference to it, so you need to call g_object_unref on the retrieved object once you are done with it: @@ -1210,10 +1212,10 @@ onTreeViewRowActivated (GtkTreeView *view, GtkTreePath *path, ... - Similarly, GBoxed-derived types retrieved + Similarly, GBoxed-derived types retrieved from a model need to be freed with g_boxed_free when done with them (don't worry if you have never heard of - GBoxed). + GBoxed). If the model column is of type G_TYPE_POINTER, @@ -1298,7 +1300,7 @@ onTreeViewRowActivated (GtkTreeView *view, GtkTreePath *path, 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 - GtkTreePath that describes that row and then turn it + GtkTreePath that describes that row and then turn it into an iter and remove it; or you take the iter of the parent node and use @@ -1459,7 +1461,7 @@ onTreeViewRowActivated (GtkTreeView *view, GtkTreePath *path, Storing GObjects (Pixbufs etc.) - A special case are GObject types, like + A special case are GObject types, like GDK_TYPE_PIXBUF, that get stored in a list or tree 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 @@ -1514,7 +1516,7 @@ onTreeViewRowActivated (GtkTreeView *view, GtkTreePath *path, Having learned how to add, manipulate, and retrieve data from a store, the next step is to get that data displayed in a - GtkTreeView widget. + GtkTreeView widget. @@ -1838,8 +1840,8 @@ yourself. Some code snippets: Reference counting - Tree models like GtkListStore and - GtkTreeStore are GObjects and + Tree models like GtkListStore and + GtkTreeStore are GObjects and have a reference count of 1 after creation. The tree view will add its own reference to the model when you add the model with gtk_tree_view_set_model, and will unref it again @@ -1931,9 +1933,9 @@ yourself. Some code snippets: 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 tree view. Tree view columns, however, do not display anything by - themselves, this is done by specialised GtkCellRenderer + themselves, this is done by specialised GtkCellRenderer objects. Cell renderers are packed into tree view columns much like - widgets are packed into GtkHBoxes. + widgets are packed into GtkHBoxes. Here is a diagram (courtesy of Owen Taylor) that pictures the relationship between tree view columns and cell renderers: @@ -1965,7 +1967,7 @@ yourself. Some code snippets: Cell Renderers Cell renderers are objects that are responsible for the actual - rendering of data within a GtkTreeViewColumn. They + rendering of data within a GtkTreeViewColumn. They are basically just GObjects (ie. not widgets) that have certain properties, and those properties determine how a single cell is drawn. @@ -1993,14 +1995,14 @@ yourself. Some code snippets: - GtkCellRendererText renders strings or + GtkCellRendererText renders strings or numbers or boolean values as text ("Joe", "99.32", "true") - GtkCellRendererPixbuf is used to display + GtkCellRendererPixbuf is used to display images; either user-defined images, or one of the stock icons that come with Gtk+. @@ -2008,18 +2010,18 @@ yourself. Some code snippets: - GtkCellRendererToggle displays a boolean + GtkCellRendererToggle displays a boolean value in form of a check box or as a radio button. - GtkCellEditable is a special cell that + GtkCellEditable is a special cell that implements editable cells (ie. GtkEntry or GtkSpinbutton in a treeview). This is not a cell renderer! If you want to have editable - text cells, use GtkCellRendererText and make sure - the "editable" property is set. GtkCellEditable + text cells, use GtkCellRendererText and make sure + the "editable" property is set. GtkCellEditable is only used by implementations of editable cells and widgets that can be inside of editable cells. You are unlikely to ever need it. @@ -2081,7 +2083,7 @@ yourself. Some code snippets: Here is a silly and utterly useless little example that demonstrates this behaviour, and introduces some of the most commonly - used properties of GtkCellRendererText: + used properties of GtkCellRendererText: #include <gtk/gtk.h> @@ -2286,11 +2288,11 @@ main (int argc, char **argv) example a bit further above, you might have noticed that we set the "cell-background" property of a - GtkCellRendererText, even though the API + GtkCellRendererText, even though the API documentation does not list such a property. We can do this, because - GtkCellRendererText is derived from GtkCellRendererText is derived from - GtkCellRenderer, which does in fact GtkCellRenderer, which does in fact have such a property. Derived classes inherit the properties of 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. There are two more noteworthy things about - GtkCellRenderer properties: one is that sometimes + GtkCellRenderer properties: one is that sometimes there are different properties which do the same, but take different arguments, such as the "foreground" and "foreground-gdk" properties of - GtkCellRendererText (which specify the text colour). + GtkCellRendererText (which specify the text colour). The "foreground" property take a colour in string form, such as "Orange" or "CornflowerBlue", whereas "foreground-gdk" takes a gtk_tree_view_column_add_attribute or one of the convenience functions that do the same thing), and then - pass on the GValue retrieved to + pass on the GValue retrieved to g_object_set_property. . @@ -2883,7 +2885,7 @@ main (int argc, char **argv) So far we have only put text in the tree view. While everything you need to know to display icons (in the form of - GdkPixbufs) has been introduced in the previous + GdkPixbufs) has been introduced in the previous 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 column: @@ -2963,11 +2965,11 @@ main (int argc, char **argv) Note that the tree view will not resize icons for you, but displays them in their original size. If you want to display - stock icons instead of GdkPixbufs loaded from + stock icons instead of GdkPixbufs loaded from file, you should have a look at the "stock-id" property of - GtkCellRendererPixbuf (and your model column + GtkCellRendererPixbuf (and your model column should be of type G_TYPE_STRING, as all stock IDs are just strings by which to identify the stock icon). @@ -2982,8 +2984,8 @@ main (int argc, char **argv) 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 - GtkTreeSelection object of a tree view. Every - tree view automatically has a GtkTreeSelection + GtkTreeSelection object of a tree view. Every + tree view automatically has a GtkTreeSelection associated with it, and you can get it using gtk_tree_view_get_selection. Selections are @@ -2992,7 +2994,7 @@ main (int argc, char **argv) particular reason why selection handling could not have been implemented with functions that access the tree view widget directly, but for reasons of API cleanliness and code clarity the Gtk+ developers decided - to create this special GtkTreeSelection object that + to create this special GtkTreeSelection object that 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 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 gtk_tree_selection_selected_foreach or get - a GList of tree paths of the selected rows using + a GList of tree paths of the selected rows using gtk_tree_selection_get_selected_rows. Note @@ -3538,14 +3540,14 @@ main (int argc, char **argv) Lists and trees are meant to be sorted. This is done using the - GtkTreeSortable interface that can be + GtkTreeSortable interface that can be implemented by tree models. 'Interface' means that you can just cast a - GtkTreeModel into a GtkTreeSortable + GtkTreeModel into a GtkTreeSortable with GTK_TREE_SORTABLE(model) and use the documented tree sortable functions on it, just like we did before when we cast a list store to a tree model and used the gtk_tree_model_foo - family of functions. Both GtkListStore and - GtkTreeStore implement the tree sortable + family of functions. Both GtkListStore and + GtkTreeStore implement the tree sortable interface. 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 - GtkTreeModelSort comes in, which is a special + GtkTreeModelSort comes in, which is a special 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. @@ -3747,7 +3749,7 @@ main (int argc, char **argv) - GtkTreeModelSort is a wrapper tree model. It + GtkTreeModelSort is a wrapper tree model. It 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 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 store again at some point. - GtkTreeModelSort implements the - GtkTreeSortable interface, so you can treat it just + GtkTreeModelSort implements the + GtkTreeSortable interface, so you can treat it just as if it was your data store for sorting purposes. Here is the basic setup with a tree view: @@ -3901,7 +3903,7 @@ main (int argc, char **argv) Editable Text Cells - With GtkCellRendererText you can not only + With GtkCellRendererText you can not only 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. @@ -4033,9 +4035,9 @@ void cell_edited_callback (GtkCellRendererText *cell, Editable Toggle and Radio Button Cells - Just like you can set a GtkCellRendererText + Just like you can set a GtkCellRendererText editable, you can specify whether a - GtkCellRendererToggle should change its state when + GtkCellRendererToggle should change its state when clicked by setting the "activatable" property - 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 @@ -4063,7 +4065,7 @@ void cell_toggled_callback (GtkCellRendererToggle *cell, Just like with the "edited" signal of the text cell renderer, the tree path is passed to the "toggled" signal callback in string form. You can - convert this into a GtkTreePath with GtkTreePath with gtk_tree_path_new_from_string, or convert it into an iter with Editable Spin Button Cells - Even though GtkSpinButton implements the - GtkCellEditable interface (as does - GtkEntry), there is no easy way to get a cell + Even though GtkSpinButton implements the + GtkCellEditable interface (as does + GtkEntry), there is no easy way to get a cell renderer that uses a spin button instead of a normal entry when in editing mode. To get this functionality, you need to either write a new cell renderer that works very similar to - GtkCellRendererText, or you need to write a new cell + GtkCellRendererText, or you need to write a new cell renderer class that derives from the text cell renderer and changes the behaviour in editing mode. @@ -4096,7 +4098,7 @@ void cell_toggled_callback (GtkCellRendererToggle *cell, Among this tutorial's code examples there is a hackish CellRendererSpin implementation which is based on - GtkCellRendererText and shows spin buttons in editing + GtkCellRendererText and shows spin buttons in editing mode. The implementation is not very refined though, so you need to make sure it works in your particular context, and modify it as needed. @@ -4115,7 +4117,7 @@ void cell_toggled_callback (GtkCellRendererToggle *cell, Getting the Column Number from a Tree View Column Widget Signal callbacks often only get passed a pointer to a - GtkTreeViewColumn when the application programmer + GtkTreeViewColumn when the application programmer really just wants to know which column number was 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 @@ -4356,7 +4358,7 @@ onButtonPress (GtkWidget *view, GdkEventButton *bevent, gpointer data) Glade and Tree Views A frequently asked question is how you can add columns to a - GtkTreeView in GtkTreeView in Glade. Do not use Glade to generate code for 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. 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 - GtkTreeView for you with nothing in it. You will need + GtkTreeView for you with nothing in it. You will need 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 or tree store to it. Then you will need to add - GtkTreeViewColumns and cell renderers to display the + GtkTreeViewColumns and cell renderers to display the information from the model as you want it to be displayed. You will need to do all that from within your application. An alternative approach is to derive your own special widget from - GtkTreeView that sets up everything as you want it + GtkTreeView that sets up everything as you want it 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 and cell renderers and to create the model yourself. @@ -4616,10 +4618,10 @@ view_onDragMotion (GtkWidget *widget, GdkDragContext *context, gint x, ****** TODO - Both GtkListStore and - GtkTreeStore implement the - GtkTreeDragDest and - GtkTreeDragSource interfaces, which means that they + Both GtkListStore and + GtkTreeStore implement the + GtkTreeDragDest and + GtkTreeDragSource interfaces, which means that they have in-built support for row reordering. You need to call gtk_tree_view_set_reorderable to activate this, and 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, Using a custom model you could also implement a filter model that only displays certain rows according to some filter criterion instead of - displaying all rows (Gtk+-2.4 has a filter model, - GtkTreeModelFilter, that does exactly that and much + GtkTreeModelFilter, that does exactly that and much 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 examples of this tutorial - there is GuiTreeModelFilter, which is @@ -4685,8 +4687,8 @@ view_onDragMotion (GtkWidget *widget, GdkDragContext *context, gint x, What Does Writing a Custom Model Involve? Basically, all you need to do is to write a new GObject that - implements the GtkTreeModel interface, - GtkTreeModelIface. Intimate knowledge about the GLib + implements the GtkTreeModel interface, + GtkTreeModelIface. Intimate knowledge about the GLib 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 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. Our list model is represented by a simple list of records, where - each row corresponds to a CustomRecord structure + each row corresponds to a CustomRecord structure 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 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 - fields in the CustomRecord structure. + fields in the CustomRecord structure. Within the model, more precisely: the - CustomList structure, the list is stored as a pointer + CustomList structure, the list is stored as a pointer 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 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.). Each row in our list is represented by a - CustomRecord structure. You can store whatever other + CustomRecord structure. You can store whatever other 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 Some thought should go into how exactly you fill the - GtkTreeIter fields of the tree iters used by + GtkTreeIter fields of the tree iters used by 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 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). In our specific example, we simply store a pointer to a row's - CustomRecord structure in our model's tree iters, + CustomRecord structure in our model's tree iters, which is valid as long as the row exists. Additionally we store the - position of a row within the list in the CustomRecord + position of a row within the list in the CustomRecord as well, which is not only intuitive, but is also useful later on when we resort the list. @@ -4850,12 +4852,12 @@ view_onDragMotion (GtkWidget *widget, GdkDragContext *context, gint x, The header file for our custom list model defines some standard type casts - and type check macros, our CustomRecord structure, - our CustomList structure, and some enums for the + and type check macros, our CustomRecord structure, + our CustomList structure, and some enums for the model columns we are exporting. - The CustomRecord structure represents one - row, while the CustomList structure contains all + The CustomRecord structure represents one + row, while the CustomList structure contains all list-specific data. You can add additional fields to both structures without problems. For example, you might need a function that quickly 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, custom_list_init we define what data type our exported model columns have, and how many columns we export. Towards the end of custom_list_get_type we register the - GtkTreeModel interface with our custom model + GtkTreeModel interface with our custom model object. This is where we can also register additional interfaces (e.g. - GtkTreeSortable or one of the Drag'n'Drop + GtkTreeSortable or one of the Drag'n'Drop interfaces) that we want to implement. In custom_list_tree_model_init 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 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 - CustomList structure, using GLib N-ary trees for + CustomList structure, using GLib N-ary trees for example, or you could do this by keeping track of each row's children - within the row's CustomRecord structure, keeping only + within the row's CustomRecord structure, keeping only a pointer to the (invisible) root record in the - CustomList structure. + CustomList structure. TODO: do we need anything else here? @@ -5156,7 +5158,7 @@ custom_list_tree_model_init (GtkTreeModelIface *iface) Here, we will show how to implement additional interfaces at the - example of the GtkTreeSortable interface, which we + example of the GtkTreeSortable interface, which we will implement only partially (enough to make it functional and useful though). @@ -5204,7 +5206,7 @@ custom_list_tree_model_init (GtkTreeModelIface *iface) ... - Next, let's extend our CustomList structure + Next, let's extend our CustomList structure 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: @@ -6472,7 +6474,7 @@ main (int argc, char **argv) extend its functionality. You can do this by writing a new object that derives from - GtkCellRenderer (or even one of the other cell + GtkCellRenderer (or even one of the other cell renderers if you just want to extend an existing one). Three things you need to do in the course of that: @@ -6488,7 +6490,7 @@ main (int argc, char **argv) Write your own cell_renderer_get_size function and override the parent object's function (usually the parent - is of type GtkCellRenderer. Note that you should + is of type GtkCellRenderer. Note that you should honour the standard properties for padding and cell alignment of the parent object here. @@ -6506,8 +6508,8 @@ main (int argc, char **argv) according to your own needs. Good examples of cell renderer code to look at or even modify are - GtkCellRendererPixbuf and - GtkCellRendererToggle in the Gtk+ source code tree. + GtkCellRendererPixbuf and + GtkCellRendererToggle in the Gtk+ source code tree. Both cases are less than five hundred lines of code to look at and thus should be fairly easy to digest. @@ -6539,14 +6541,14 @@ main (int argc, char **argv) custom-cell-renderer-progressbar.h The header file consists of the usual GObject type cast and type - check defines and our CustomCellRendererProgress + check defines and our CustomCellRendererProgress structure. As the type of the parent indicates, we derive from - GtkCellRenderer. The parent object must always be + GtkCellRenderer. The parent object must always be 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 structure). - Our CustomCellRendererProgress structure is + Our CustomCellRendererProgress structure is fairly uneventful and contains only a double precision float variable in which we store our new "percentage" property (which will determine how long the progressbar is going to be). @@ -6952,7 +6954,7 @@ custom_cell_renderer_progress_render (GtkCellRenderer *cell, main.c And here is a little test that makes use of our new - CustomCellRendererProgress: + CustomCellRendererProgress: #include "custom-cell-renderer-progressbar.h"