
@c %start of fragment

@node ClutterModel
@chapter ClutterModel
A generic model implementation

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

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

Creating a simple clutter model:

@example 

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);
    @}

  
@}
@end example

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

A valid @code{<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 @code{<clutter-model>}:

@example 

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);
@}
@end example

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

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

@c (example (@ (id "ClutterModel-script-example")))
@c (title "Example of the \"columns\" and \"rows\" custom properties")
The definition below will create a @code{<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 @code{<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.

@example 

 @{
   "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" @}
   ]
 @}
    
@end example

@code{<clutter-model>} is available since Clutter 0.6

@section Usage
@include defuns-clutter-model.xml.texi

@c %end of fragment
