treeview-tutorial

Description

GTK+2.0TreeViewTutorialTim PhilippMüllerGTK+2.0TreeViewTutorialbyTim PhilippMüllerThisisatutorialonhowtousetheGTK(theGIMPToolkit)GtkTreeViewwidgetthroughitsCinterface.PleasemailallcommentsandsuggestionstoA tarball of the tutorial for off line reading including the example source codes is available here:treeview tutorial.tar.gz.ThereisalsoaversioninPDFformat(foreasierprinting)andtherawdocbookXMLsourcedocument.Thistutorialiswork in progress.Thelatestversioncanbefoundat http://scentric.net/tutorial/.Somesectionsareabitoutdated(e.g.GtkTreeModelFilterhasbeeninGtksince2.4),justhaven’tgottenaroundtorewritethemorupdatethem.Sorry!Lastupdated:September29th,2006TableofContents1.ListsandTrees:theGtkTreeViewWidget......................................................................................................................11.1.HelloWorld..............................................................................................................................................................12.Components:Model,Renderer,Column,View............................................................................................................43.GtkTreeModelsforDataStorage:GtkListStoreandGtkTreeStore..........................................................................53.1.HowDataisOrganisedinaStore.........................................................................................................................53.2 ...

Informations

• Publié par: Nizur
• Nombre de lectures: 30
• Langue: English

Extrait

GTK+ 2.0 Tree View Tutorial

Tim-Philipp Müller

GTK+ 2.0 Tree View Tutorial by Tim-Philipp Müller

This is a tutorial on how to use the GTK (the GIMP Toolkit) GtkTreeView widget through its C interface. Please mail all comments and suggestions to < tim at centricular dot net > A tarball of the tutorial for off-line reading including the example source codes is available here: treeview-tutorial.tar.gz. There is also a version in PDF format (for easier printing) and the raw docbook XML source document. This tutorial is work-in-progress. The latest version can be found at http://scentric.net/tutorial/. Some sections are a bit outdated (e.g. GtkTreeModelFilter has been in Gtk since 2.4), just haven’t gotten around to rewrite them or update them. Sorry! Last updated: September 29th, 2006

Table of Contents

1. Lists and Trees: the GtkTreeView Widget ...................................................................................................................... 1 1.1.HelloWorld..............................................................................................................................................................1 2. Components: Model, Renderer, Column, View ............................................................................................................ 4 3. GtkTreeModels for Data Storage: GtkListStore and GtkTreeStore .......................................................................... 5 3.1. How Data is Organised in a Store ......................................................................................................................... 5 3.2. Refering to Rows: GtkTreeIter, GtkTreePath, GtkTreeRowReference .............................................................. 6 3.2.1.GtkTreePath.................................................................................................................................................6 3.2.2.GtkTreeIter...................................................................................................................................................7 3.2.3. GtkTreeRowReference ................................................................................................................................ 8 3.2.4. Usage ............................................................................................................................................................ 8 3.3. Adding Rows to a Store .......................................................................................................................................... 9 3.3.1. Adding Rows to a List Store...................................................................................................................... 9 3.3.2.AddingRowstoaTreeStore...................................................................................................................10 3.3.3. Speed Issues when Adding a Lot of Rows ............................................................................................ 10 3.4. Manipulating Row Data ....................................................................................................................................... 11 3.5. Retrieving Row Data ............................................................................................................................................. 12 3.5.1. Freeing Retrieved Row Data ................................................................................................................... 13 3.6. Removing Rows..................................................................................................................................................... 14 3.7. Removing Multiple Rows .................................................................................................................................... 15 3.8. Storing GObjects (Pixbufs etc.) ............................................................................................................................ 16 3.9. Storing Data Structures: of Pointers, GBoxed Types, and GObject (TODO)................................................. 17 4.CreatingaTreeView........................................................................................................................................................18 4.1.ConnectingTreeViewandModel.......................................................................................................................18 4.1.1. Reference counting ................................................................................................................................... 18 4.2.TreeViewLookandFeel......................................................................................................................................18 5. Mapping Data to the Screen: GtkTreeViewColumn and GtkCellRenderer.......................................................... 20 5.1. Cell Renderers ........................................................................................................................................................ 20 5.2. Attributes ................................................................................................................................................................ 24 5.3. Cell Data Functions ............................................................................................................................................... 25 5.4. GtkCellRendererText and Integer, Boolean and Float Types .......................................................................... 26 5.5. GtkCellRendererText, UTF8, and pango markup ............................................................................................. 26 5.6. A Working Example .............................................................................................................................................. 28 5.7. How to Make a Whole Row Bold or Coloured ................................................................................................. 30 5.8. How to Pack Icons into the Tree View ................................................................................................................ 31 6. Selections, Double-Clicks and Context Menus .......................................................................................................... 33 6.1. Handling Selections .............................................................................................................................................. 33 6.1.1. Selection Modes ........................................................................................................................................ 33 6.1.2. Getting the Currently Selected Rows ..................................................................................................... 33 6.1.3. Using Selection Functions........................................................................................................................ 34 6.1.4. Checking Whether a Row is Selected..................................................................................................... 36 6.1.5. Selecting and Unselecting Rows ............................................................................................................. 36 6.1.6. Getting the Number of Selected Rows................................................................................................... 36 6.2. Double-Clicks on a Row ....................................................................................................................................... 36 6.3. Context Menus on Right Click ............................................................................................................................ 37 7. Sorting ................................................................................................................................................................................. 40 7.1.GtkTreeSortable.....................................................................................................................................................40 7.2.GtkTreeModelSort.................................................................................................................................................42 7.3.SortingandTreeViewColumnHeaders...........................................................................................................43 7.4. Case-insensitive String Comparing .................................................................................................................... 43 8. Editable Cells ..................................................................................................................................................................... 45 8.1.EditableTextCells.................................................................................................................................................45 8.1.1. Setting the cursor to a specific cell.......................................................................................................... 45 8.2.EditableToggleandRadioButtonCells............................................................................................................46 8.3. Editable Spin Button Cells.................................................................................................................................... 46

iii

9. Miscellaneous .................................................................................................................................................................... 47 9.1. Getting the Column Number from a Tree View Column Widget .................................................................. 47 9.2.ColumnExpanderVisibility................................................................................................................................48 9.2.1. Hiding the Column Expander ................................................................................................................ 48 9.2.2. Forcing Column Expander Visibility ..................................................................................................... 48 9.3. Getting the Cell Renderer a Click Event Happened On .................................................................................. 48 9.4.GladeandTreeViews...........................................................................................................................................49 10. Drag’n’Drop (DnD) **** needs revision *** .............................................................................................................. 51 10.1. Drag’n’Dropping Row-Unrelated Data to and from a Tree View from other Windows or Widgets ...... 51 10.2. Dragging Rows Around Within a Tree **** TODO *** ................................................................................... 53 10.3. Dragging Rows from One Tree to Another **** TODO *** ............................................................................ 54 11. Writing Custom Models................................................................................................................................................. 55 11.1. When is a Custom Model Useful?..................................................................................................................... 55 11.2. What Does Writing a Custom Model Involve? ............................................................................................... 55 11.3. Example: A Simple Custom List Model ........................................................................................................... 55 11.3.1. custom-list.h ............................................................................................................................................ 56 11.3.2. custom-list.c ............................................................................................................................................. 56 11.4. From a List to a Tree ............................................................................................................................................ 58 11.5. Additional interfaces, here: the GtkTreeSortable interface............................................................................ 59 11.6. Working Example: Custom List Model Source Code..................................................................................... 64 11.6.1. custom-list.h ............................................................................................................................................ 64 11.6.2. custom-list.c ............................................................................................................................................. 65 11.6.3. main.c........................................................................................................................................................ 75 12.WritingCustomCellRenderers...................................................................................................................................77 12.1. Working Example: a Progress Bar Cell Renderer............................................................................................ 77 12.1.1. custom-cell-renderer-progressbar.h ..................................................................................................... 77 12.1.2. custom-cell-renderer-progressbar.c ...................................................................................................... 78 12.1.3. main.c........................................................................................................................................................ 83 12.2.CellRenderersOthersHaveWritten................................................................................................................84 13. Other Resources .............................................................................................................................................................. 86 14. Copyright, License, Credits, and Revision History .................................................................................................. 87 14.1. Copyright and License........................................................................................................................................ 87 14.2. Credits ................................................................................................................................................................... 87 14.3. Revision History .................................................................................................................................................. 87

iv

Chapter 1. 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 Gtk- CList 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 is for, which should be read alongside with this tutorial. The goal is rather to present an intro- duction to the most 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 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 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 developers are able to decide which one is most suitable for the task at hand.

1.1. Hello World For the impatient, here is a small treeview ’Hello World’ program (which can also be found in the examples section of the treeview-tutorial.tar.gz tarball).

/ * * Compile with: * gcc -o helloworld * */

#include <gtk/gtk.h>

enum { _ COL NAME COL_AGE, NUM COLS _ } ;

= 0,

helloworld.c

staticGtkTreeModel * create and fill model (void) _ _ _ { GtkListStore *store; GtkTreeIter iter;

store = gtk list store_new _ _

‘pkg-config

(NUM COLS, _

--cflags

_ _ , G TYPE STRING

/* Append a row and fill in some data */ gtk_list_store_append (store, &iter); gtk_list_store_set (store, &iter, COL_NAME, "Heinz El-Mann", COL_AGE, 51, -1);

/* append another row and fill in some data */ gtk_list_store_append (store, &iter); gtk list store set (store, &iter, _ _ _ COL_NAME, "Jane Doe", COL_AGE, 23, -1);

/ *

...

and

a

third

row */

--libs gtk+-2.0‘

G_TYPE_UINT);

1

}

gtk_list_store_append (store, &iter); gtk_list_store_set (store, &iter, COL_NAME, "Joe Bungop , " COL_AGE, 91, -1);

return GTK_TREE_MODEL (store);

staticGtkWidget * _ _and_model (void) create view { GtkCellRenderer *renderer; GtkTreeModel *model; GtkWidget *view;

view = gtk_tree_view_new ();

/* --- Column #1 --- */

Chapter 1. Lists and Trees: the GtkTreeView Widget

renderer = gtk_cell_renderer_text_new (); gtk_tree view insert column with attributes (GTK_TREE_VIEW (view), _ _ _ _ _ -1 , "Name" , renderer, "text", COL_NAME, NULL);

/* --- Column #2 --- */

renderer = gtk_cell_renderer_text_new (); gtk_tree_view_insert_column_with_attributes

model = create_ _ _ de (); and fill mo l

(GTK_TREE_VIEW (view), -1, "Age" , renderer, "text , COL_AGE, " NULL);

gtk_tree_view_set model (GTK_TREE_VIEW (view), model); _

/* The tree view has acquired its own reference to the * model, so we can drop ours. That way the model will * be freed automatically when the tree view is destroyed

g_object_unref

return view; }

(model);

**argv)

int main (int argc, char { GtkWidget *window; GtkWidget *view;

gtk_init (&argc, &argv);

window = gtk_window_new (GTK_WINDOW_TOPLEVEL); g_signal_connect (window, "delete_event", gtk_main_quit,

iew = create_view_ _ l (); v and mode

gtk_container_add (GT _ (window), K CONTAINER

gtk_widget show_all _

gtk_main ();

(window);

view);

*/

NULL);

/ *

dirty

*/

2