5.2. Attributes

An attribute is a connection between a cell renderer property and a field/column in the model. Whenever a cell is to be rendered, a cell renderer property will be set to the values of the specified model column of the row that is to be rendered. It is very important that the column's data type is the same type that a property takes according to the API reference manual. Here is some code to look at:

   ...

   col = gtk_tree_view_column_new();

   renderer = gtk_cell_renderer_text_new();

   gtk_tree_view_column_pack_start(col, renderer, TRUE);

   gtk_tree_view_column_add_attribute(col, renderer, "text", COL_FIRST_NAME);

   ...

This means that the text cell renderer property "text" will be set to the string in model column COL_FIRST_NAME of each row to be drawn. It is important to internalise the difference between gtk_tree_view_column_add_attribute and g_object_set: g_object_set sets a property to a certain value, while gtk_tree_view_column_add_attribute sets a property to whatever is in the specified _model column_ at the time of rendering.

Again, when setting attributes it is very important that the data type stored in a model column is the same as the data type that a property requires as argument. Check the API reference manual to see the data type that is required for each property. When reading through the example a bit further above, you might have noticed that we set the "cell-background" property of a GtkCellRendererText, even though the API documentation does not list such a property. We can do this, because GtkCellRendererText is derived from 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 one of their ancestor classes. The API reference has an object hierarchy that shows you which classes a widget or some other object is derived from.

There are two more noteworthy things about 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). The "foreground" property take a colour in string form, such as "Orange" or "CornflowerBlue", whereas "foreground-gdk" takes a GdkColor argument. It is up to you to decide which one to use - the effect will be the same. The other thing worth mentioning is that most properties have a "foo-set" property taking a boolean value as argument, such as "foreground-set". This is useful when you want to have a certain setting have an effect or not. If you set the "foreground" property, but set "foreground-set" to FALSE, then your foreground color setting will be disregarded. This is useful in cell data functions (see below), or, for example, if you want set the foreground colour to a certain value at start-up, but only want this to be in effect in some columns, but not in others (in which case you could just connect the "foreground-set" property to a model column of type G_TYPE_BOOLEAN with gtk_tree_view_column_add_attribute.

Setting column attributes is the most straight-forward way to get your model data to be displayed. This is usually used whenever you want the data in the model to be displayed exactly as it is in the model.

Another way to get your model data displayed on the screen is to set up cell data functions.