47 ClutterModel

A generic model implementation

47.1 Overview

<clutter-model> is a generic list model API which can be used to implement the model-view-controller architectural pattern in Clutter.

The <clutter-model> class is a list model which can accept most GObject types as a column type.

Creating a simple clutter model:

     
     enum
     {
       COLUMN_INT,
       COLUMN_STRING,
     
       N_COLUMNS
     };
     
     {
       ClutterModel *model;
       gint i;
     
       model = clutter_model_default_new (N_COLUMNS,
                                          /* column type, column title */
                                          G_TYPE_INT,     "my integers",
                                          G_TYPE_STRING,  "my strings");
       for (i = 0; i < 10; i++)
         {
           gchar *string = g_strdup_printf ("String %d", i);
           clutter_model_append (model,
                                 COLUMN_INT, i,
                                 COLUMN_STRING, string,
                                 -1);
           g_free (string);
         }
     
     
     }

Iterating through the model consists of retrieving a new <clutter-model-iter> pointing to the starting row, and calling clutter-model-iter-next or clutter-model-iter-prev to move forward or backwards, repectively.

A valid <clutter-model-iter> represents the position between two rows in the model. For example, the "first" iterator represents the gap immediately before the first row, and the "last" iterator represents the gap immediately after the last row. In an empty sequence, the first and last iterators are the same.

Iterating a <clutter-model>:

     
     enum
     {
       COLUMN_INT,
       COLUMN_STRING.
     
       N_COLUMNS
     };
     
     {
       ClutterModel *model;
       ClutterModelIter *iter = NULL;
     
       /*  Fill the model */
       model = populate_model ();
     
       /* Get the first iter */
       iter = clutter_model_get_first_iter (model);
       while (!clutter_model_iter_is_last (iter))
         {
           print_row (iter);
     
           iter = clutter_model_iter_next (iter);
         }
     
       /* Make sure to unref the iter */
       g_object_unref (iter);
     }

<clutter-model> is an abstract class. Clutter provides a list model implementation called <clutter-list-model> which has been optimised for insertion and look up in sorted lists.

47.2 ClutterModel custom properties for <clutter-script>

<clutter-model> defines a custom property "columns" for <clutter-script> which allows defining the column names and types. It also defines a custom "rows" property which allows filling the <clutter-model> with some data.

The definition below will create a <clutter-list-model> with three columns: the first one with name "Name" and containing strings; the second one with name "Score" and containing integers; the third one with name "Icon" and containing <clutter-texture>s. The model is filled with three rows. A row can be defined either with an array that holds all columns of a row, or an object that holds "column-name" : "column-value" pairs.

     
      {
        "type" : "ClutterListModel",
        "id" : "teams-model",
        "columns" : [
          [ "Name", "gchararray" ],
          [ "Score", "gint" ],
          [ "Icon", "ClutterTexture" ]
        ],
        "rows" : [
          [ "Team 1", 42, { "type" : "ClutterTexture", "filename" : "team1.png" } ],
          [ "Team 2", 23, "team2-icon-script-id" ],
          { "Name" : "Team 3", "Icon" : "team3-icon-script-id" }
        ]
      }
     

<clutter-model> is available since Clutter 0.6

47.3 Usage