Tutorial

« Tree Selections  Creating the View Component »

Inti provides two types of models that can be used: ListStore and TreeStore. ListStore is used to model columned list widgets, while TreeStore models columned tree widgets. It is possible to develop a new type of model, but the existing models should be satisfactory for all but the most specialized of situations.

To create a new model call one of the following constructors:

The first constructor creates a liststore of n_columns, each of the types passed in the variable argument list. For example:

The second constructor does the same thing except you pass a vector of types. Since the number of types is known the n_columns argument is not required. For example:

Both examples create a list store with three columns: an integer column, a string column and a boolean column. The columns appear in the view in the order of declaration. Typically the 3 is never passed directly like that; usually an enum is created wherein the different columns are enumerated, followed by a token that represents the total number of columns. The next example will illustrate this, only using a tree store instead of a list store. Creating a tree store operates almost exactly the same.

Adding data to the model is done using one of the Gtk::ListStore or Gtk::TreeStore set_() methods, depending upon which sort of model was created. To do this, a TreeIter must be acquired. The iterator points to the location where data will be added. Once an iterator has been acquired, Gtk::TreeStore::set_() is used to apply data to the part of the model that the iterator points to.

All these methods add a new row to the model and return an iterator set to the new row. The first method inserts the row at the specified position. The next two methods insert the row before and after the row identified by sibling. The fourth method prepends the row to the beginning of the list and the the last method appends the row to the end of the list.

As with ListStore, these methods add a new row to the model and return an iterator set to this new row, except there is an extra argument: a pointer to a parent iterator. Remember, a TreeStore implements a tree-like hierachical structure so you can can have toplevel rows, parent rows and child rows. A Child row itself can be a parent to a list of child rows which get displayed when the user clicks on the row's arrow indicator.

In the TreeStore methods above, if parent is null the row is added to the toplevel, otherwise the row is added to the list of child rows for the parent. By default, rows are added to the toplevel.

The first two methods are ordinary functions. The iter argument is a valid iterator for the row being modified and column is the column number to modify. In the first method value is a G::Value that holds the new value for a cell. The second method lets you easily set string literals without using a template. The other four methods are template functions. They let you set cell values directly without using a G::Value. As you can see from the inline definitions these methods supply the G::Value for you.

Before going any further, just a word about G::Values and why there are four template functions. The G::Value class is declared in <inti/glib/value.h>. G:Value has 16 overloaded get() and set() methods. Most of these methods handle unique data types, like bool, gchar, gint, glong and gfloat without any trouble. However, enums and flags fall victim to compiler conversions and require special handling to prevent compiler errors. Rather than duplicate code, G::Value handles theses two types internally. All you are required to do is call the right method. For enums, you must cast the enum to an integer before calling the G::Value get() or set() methods. For flags, you must cast the flag to an unsigned integer before calling get() or set().

That brings us back to the four template functions.  All the template functions require a typename DataType. DataType is the actual data type you are passing. For the set_value() template it must be one of the standard data types, such as bool, int, float, double,  or an Inti::String. For set_enum() it can be any enumeration type. From the code you can see the enum is cast to an int. That's because G::Value handles enums internally as an int. For get_object() DataType must be a pointer to an object derived from G::Object. For get_pointer() DataType can be a pointer to any object. Such pointers are handled internally as a generic (void*) pointer, without any interpretation.

The argument to Gtk::TreeStore::append() is the parent iterator. It is used to add a row to a TreeStore as a child of an existing row. This means that the new row will only be visible when its parent is visible and in its expanded state. Consider the following example: