GTK+ 2.0 Tree View Tutorial using Ocaml | ||
---|---|---|
Prev | Chapter 5. Mapping Data to the Screen: GTree.view_column and GTree.cell_renderer_* | Next |
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:
... let renderer_text = GTree.cell_renderer_text [] in let col = GTree.view_column ~renderer:(renderer_text, ["text", col_first_name]) () in ...
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. (The property "text" is called as `TEXT property in Ocaml-style.) Cell properties can be set using one of GTree.cell_renderer_*, GTree.cell_renderer_*#set_properties, GTree.view_column, or GTree.view_column#add_attribute (gtk_tree_view_column_add_attribute). These functions set properties to whatever is in the specified _model column_ at the time of rendering.
GTree.cell_renderer_* are types of:
val GTree.cell_renderer_pixbuf : cell_properties_pixbuf list -> cell_renderer_pixbuf val GTree.cell_renderer_text : cell_properties_text list -> cell_renderer_text val GTree.cell_renderer_toggle : cell_properties_toggle list -> cell_renderer_toggle
so you can give the list of properties as their argument. After creating GTree.cell_renderer_*, you can use:
method GTree.cell_renderer_xxx#set_properties : 'b list -> unit
(cell_renderer_xxx is one of cell_renderer_text, cell_renderer_toggle or cell_renderer_pixbuf.)
GTree.view_column is type of:
val GTree.view_column : ?title:string -> ?renderer:#cell_renderer * (string * 'a column) list -> unit -> view_column
Internally, this function uses:
method GTree.view_column#add_attribute : 'b 'c. (#cell_renderer as 'b) -> string -> 'c column -> unit
Note that the name of property is given as string type and the value of the property is given as 'a column type. 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.
This method adds an attribute mapping to the list in view_column. The string parameter is the C-style name of attribute on cell_renderer to be set from the value, and the column is the column of the model to get a value from. So for example if column col_first_name of the model contains strings, you could have the "text" attribute of a GTree.cell_renderer_text get its values from column col_first_name.
As for the name of properties, GTree.cell_renderer_* use Ocaml-style name such as `TEXT, while GTree.view_column or GTree.view_column#add_attribute uses C-style name like "text", which indicate the same property.
For cell properties, please refer GTree.cell_properties (GtkCellRenderer), GTree.cell_properties_text (GtkCellRendererText), GTree.cell_properties_toggle (GtkCellRendererToggle) and GTree.cell_properties_pixbuf (GtkCellRendererPixbuf).
There are two more noteworthy things about GTree.cell_renderer_* 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 GTree.cell_renderer_text (which specify the text colour). The `FOREGROUND property take a colour in string form, such as "Orange" or "CornflowerBlue", whereas `FOREGROUND_GDK takes a Gdk.color (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 bool with the functions explained previously).
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.