It is important to realise what GTree.model (GtkTreeModel) is and what it is not. GTree.model is basically just an 'interface' to the data store, meaning that it is a standardised set of functions that allows a GTree.view 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 inherit the GTree.model class and provide these functions. GTree.model 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.
GTree module comes with two built-in data stores (models): GTree.list_store (GtkListStore) and GTree.tree_store (GtkTreeStore). As the names imply, GTree.list_store is used for simple lists of data items where items have no hierarchical parent-child relationships, and GTree.tree_store 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 GTree.list_store 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.
GTree.list_store and GTree.tree_store should cater for most types of data an application developer might want to display in a GTree.view. However, it should be noted that GTree.list_store and GTree.tree_store 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 inherited class from GTree.model class. 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 GTree.list_store and GTree.tree_store will take care of the view side for you once you have configured the GTree.view 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 disappear from the view as well.
A model (data store) has model columns and rows. While a tree view will display each row in the model as a row in the view, the model's columns are not to be confused with a view's columns. A model column represents a certain data field of an item that has a fixed data type. You need to know what kind of data you want to store when you create a list store or a tree store, as you can not add new fields later on.
For example, we might want to display a list of files. We would create a list store with two fields: a field that stores the filename (ie. a string) and a field that stores the file size (ie. an unsigned integer). The filename would be stored in column 0 of the model, and the file size would be stored in column 1 of the model. For each file we would add a row to the list store, and set the row's fields to the filename and the file size.
The Gobject.Data(GLib type system (GType)) is used to indicate what type of data is stored in a model column. These are the most commonly used types:
Gobject.Data.boolean
Gobject.Data.int, Gobject.Data.uint
Gobject.Data.long, Gobject.Data.ulong, Gobject.Data.int64, Gobject.Data.uint64 (these are not supported in early gtk+-2.0.x versions)
Gobject.Data.float, Gobject.Data.double
Gobject.Data.string - stores a string in the store (makes a copy of the original string)
Gobject.Data.pointer - stores a pointer value (does not copy any data into the store, just stores the pointer value!)
Gobject.Data.gobject - stores gobject in the store. For example, the type GdkPixbuf.pixbuf is gobject.
You do not need to understand the type system, it will usually suffice to know the above types, so you can tell a list store or tree store what kind of data you want to store.
Here is an example of how to create a list store:
let cols = new GTree.column_list in let str_col = cols#add Gobject.Data.string in let uint_col = cols#add Gobject.Data.uint in let list_store = GTree.list_store cols in ...
This creates a new list store with two columns. Column 0 stores a string and column 1 stores an unsigned integer for each row. At this point the model has no rows yet of course. Before we start to add rows, let's have a look at the different ways used to refer to a particular row.