ClutterModel

## ClutterModel ClutterModel — A generic model implementation |

## Synopsis

    struct              ClutterModel;
    struct              ClutterModelClass;
    void                clutter_model_set_names             (ClutterModel *model,
                                                             guint n_columns,
                                                             const gchar * const names[]);
    void                clutter_model_set_types             (ClutterModel *model,
                                                             guint n_columns,
                                                             GType *types);
    const gchar *       clutter_model_get_column_name       (ClutterModel *model,
                                                             guint column);
    GType               clutter_model_get_column_type       (ClutterModel *model,
                                                             guint column);
    guint               clutter_model_get_n_columns         (ClutterModel *model);
    guint               clutter_model_get_n_rows            (ClutterModel *model);

    void                clutter_model_append                (ClutterModel *model,
                                                             ...);
    void                clutter_model_appendv               (ClutterModel *model,
                                                             guint n_columns,
                                                             guint *columns,
                                                             GValue *values);
    void                clutter_model_prepend               (ClutterModel *model,
                                                             ...);
    void                clutter_model_prependv              (ClutterModel *model,
                                                             guint n_columns,
                                                             guint *columns,
                                                             GValue *values);
    void                clutter_model_insert                (ClutterModel *model,
                                                             guint row,
                                                             ...);
    void                clutter_model_insertv               (ClutterModel *model,
                                                             guint row,
                                                             guint n_columns,
                                                             guint *columns,
                                                             GValue *values);
    void                clutter_model_insert_value          (ClutterModel *model,
                                                             guint row,
                                                             guint column,
                                                             const GValue *value);
    void                clutter_model_remove                (ClutterModel *model,
                                                             guint row);

    gboolean            (*ClutterModelForeachFunc)          (ClutterModel *model,
                                                             ClutterModelIter *iter,
                                                             gpointer user_data);
    void                clutter_model_foreach               (ClutterModel *model,
                                                             ClutterModelForeachFunc func,
                                                             gpointer user_data);
    void                clutter_model_set_sorting_column    (ClutterModel *model,
                                                             gint column);
    gint                clutter_model_get_sorting_column    (ClutterModel *model);
    gint                (*ClutterModelSortFunc)             (ClutterModel *model,
                                                             const GValue *a,
                                                             const GValue *b,
                                                             gpointer user_data);
    void                clutter_model_set_sort              (ClutterModel *model,
                                                             gint column,
                                                             ClutterModelSortFunc func,
                                                             gpointer user_data,
                                                             GDestroyNotify notify);
    void                clutter_model_resort                (ClutterModel *model);
    gboolean            (*ClutterModelFilterFunc)           (ClutterModel *model,
                                                             ClutterModelIter *iter,
                                                             gpointer user_data);
    void                clutter_model_set_filter            (ClutterModel *model,
                                                             ClutterModelFilterFunc func,
                                                             gpointer user_data,
                                                             GDestroyNotify notify);
    gboolean            clutter_model_get_filter_set        (ClutterModel *model);
    gboolean            clutter_model_filter_iter           (ClutterModel *model,
                                                             ClutterModelIter *iter);
    gboolean            clutter_model_filter_row            (ClutterModel *model,
                                                             guint row);

    ClutterModelIter *  clutter_model_get_first_iter        (ClutterModel *model);
    ClutterModelIter *  clutter_model_get_last_iter         (ClutterModel *model);
    ClutterModelIter *  clutter_model_get_iter_at_row       (ClutterModel *model,
                                                             guint row);

## Object Hierarchy

      GObject
       +----ClutterModel
             +----ClutterListModel

## Implemented Interfaces

ClutterModel implements ClutterScriptable.

## Properties

      "filter-set"               gboolean              : Read

## Signals

      "filter-changed"                                 : Run Last
      "row-added"                                      : Run Last
      "row-changed"                                    : Run Last
      "row-removed"                                    : Run Last
      "sort-changed"                                   : Run Last

## Description

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

The ClutterModel class is a list model which can accept most GObject types as a column type.

Creating a simple clutter model:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    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 ClutterModelIter pointing to the starting row, and calling `clutter_model_iter_next()` or `clutter_model_iter_prev()` to move forward or backwards, repectively.

A valid ClutterModelIter 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 ClutterModel:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    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);
    }

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

### ClutterModel custom properties for ClutterScript

ClutterModel defines a custom property "columns" for ClutterScript which allows defining the column names and types. It also defines a custom "rows" property which allows filling the ClutterModel with some data.

Example 17. Example of the "columns" and "rows" custom properties

The definition below will create a ClutterListModel 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 ClutterTextures. 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" }
       ]
     }

ClutterModel is available since Clutter 0.6

## Details

### struct ClutterModel

    struct ClutterModel;

Base class for list models. The ClutterModel structure contains only private data and should be manipulated using the provided API.

Since 0.6

### struct ClutterModelClass

    struct ClutterModelClass {
      /* vtable */
      guint             (* get_n_rows)      (ClutterModel         *model);
      guint             (* get_n_columns)   (ClutterModel         *model);
      const gchar *     (* get_column_name) (ClutterModel         *model,
                                             guint                 column);
      GType             (* get_column_type) (ClutterModel         *model,
                                             guint                 column);
      ClutterModelIter *(* insert_row)      (ClutterModel         *model,
                                             gint                  index_);
      void              (* remove_row)      (ClutterModel         *model,
                                             guint                 row);
      ClutterModelIter *(* get_iter_at_row) (ClutterModel         *model,
                                             guint                 row);
      void              (* resort)          (ClutterModel         *model,
                                             ClutterModelSortFunc  func,
                                             gpointer              data);

      /* signals */
      void              (* row_added)       (ClutterModel     *model,
                                             ClutterModelIter *iter);
      void              (* row_removed)     (ClutterModel     *model,
                                             ClutterModelIter *iter);
      void              (* row_changed)     (ClutterModel     *model,
                                             ClutterModelIter *iter);
      void              (* sort_changed)    (ClutterModel     *model);
      void              (* filter_changed)  (ClutterModel     *model);
    };

Class for ClutterModel instances.

`get_n_rows` () | virtual function for returning the number of rows of the model
`get_n_columns` () | virtual function for retuning the number of columns of the model
`get_column_name` () | virtual function for returning the name of a column
`get_column_type` () | virtual function for returning the type of a column
`insert_row` () | virtual function for inserting a row at the given index and returning an iterator pointing to it; if the index is a negative integer, the row should be appended to the model
`remove_row` () | virtual function for removing a row at the given index
`get_iter_at_row` () | virtual function for returning an iterator for the given row
`resort` () | virtual function for sorting the model using the passed sorting function
`row_added` () | signal class handler for ClutterModel::row-added
`row_removed` () | signal class handler for ClutterModel::row-removed
`row_changed` () | signal class handler for ClutterModel::row-changed
`sort_changed` () | signal class handler for ClutterModel::sort-changed
`filter_changed` () | signal class handler for ClutterModel::filter-changed

Since 0.6

### clutter_model_set_names ()

    void                clutter_model_set_names             (ClutterModel *model,
                                                             guint n_columns,
                                                             const gchar * const names[]);

Assigns a name to the columns of a ClutterModel.

This function is meant primarily for GObjects that inherit from ClutterModel, and should only be used when contructing a ClutterModel. It will not work after the initial creation of the ClutterModel.

`model` : | a ClutterModel
`n_columns` : | the number of column names
`names` : | an array of strings. [array length=n_columns]

Since 0.6

### clutter_model_set_types ()

    void                clutter_model_set_types             (ClutterModel *model,
                                                             guint n_columns,
                                                             GType *types);

Sets the types of the columns inside a ClutterModel.

This function is meant primarily for GObjects that inherit from ClutterModel, and should only be used when contructing a ClutterModel. It will not work after the initial creation of the ClutterModel.

`model` : | a ClutterModel
`n_columns` : | number of columns for the model
`types` : | an array of GType types. [array length=n_columns]

Since 0.6

### clutter_model_get_column_name ()

    const gchar *       clutter_model_get_column_name       (ClutterModel *model,
                                                             guint column);

Retrieves the name of the `column`

`model` : | ClutterModel
`column` : | the column number
Returns : | the name of the column. The model holds the returned string, and it should not be modified or freed

Since 0.6

### clutter_model_get_column_type ()

    GType               clutter_model_get_column_type       (ClutterModel *model,
                                                             guint column);

Retrieves the type of the `column`.

`model` : | ClutterModel
`column` : | the column number
Returns : | the type of the column.

Since 0.6

### clutter_model_get_n_columns ()

    guint               clutter_model_get_n_columns         (ClutterModel *model);

Retrieves the number of columns inside `model`.

`model` : | a ClutterModel
Returns : | the number of columns

Since 0.6

### clutter_model_get_n_rows ()

    guint               clutter_model_get_n_rows            (ClutterModel *model);

Retrieves the number of rows inside `model`, eventually taking into account any filtering function set using `clutter_model_set_filter()`.

`model` : | a ClutterModel
Returns : | The length of the `model`. If there is a filter set, then the length of the filtered `model` is returned.

Since 0.6

### clutter_model_append ()

    void                clutter_model_append                (ClutterModel *model,
                                                             ...);

Creates and appends a new row to the ClutterModel, setting the row values upon creation. For example, to append a new row where column 0 is type `G_TYPE_INT` and column 1 is of type `G_TYPE_STRING`:

    1
    2
    3
    4
    5
    ClutterModel *model;
    model = clutter_model_default_new (2,
                                       G_TYPE_INT,    "Score",
                                       G_TYPE_STRING, "Team");
    clutter_model_append (model, 0, 42, 1, "Team <GTKDOCLINK HREF="1:CAPS">1</GTKDOCLINK>", -1);

`model` : | a ClutterModel
`...` : | pairs of column number and value, terminated with -1

Since 0.6

### clutter_model_appendv ()

    void                clutter_model_appendv               (ClutterModel *model,
                                                             guint n_columns,
                                                             guint *columns,
                                                             GValue *values);

Creates and appends a new row to the ClutterModel, setting the row values for the given `columns` upon creation.

`model` : | a ClutterModel
`n_columns` : | the number of columns and values
`columns` : | a vector with the columns to set. [array length=n_columns]
`values` : | a vector with the values. [array length=n_columns]

Since 0.6

### clutter_model_prepend ()

    void                clutter_model_prepend               (ClutterModel *model,
                                                             ...);

Creates and prepends a new row to the ClutterModel, setting the row values upon creation. For example, to prepend a new row where column 0 is type `G_TYPE_INT` and column 1 is of type `G_TYPE_STRING`:

    1
    2
    3
    4
    5
    ClutterModel *model;
    model = clutter_model_default_new (2,
                                       G_TYPE_INT,    "Score",
                                       G_TYPE_STRING, "Team");
    clutter_model_prepend (model, 0, 42, 1, "Team <GTKDOCLINK HREF="1:CAPS">1</GTKDOCLINK>", -1);

`model` : | a ClutterModel
`...` : | pairs of column number and value, terminated with -1

Since 0.6

### clutter_model_prependv ()

    void                clutter_model_prependv              (ClutterModel *model,
                                                             guint n_columns,
                                                             guint *columns,
                                                             GValue *values);

Creates and prepends a new row to the ClutterModel, setting the row values for the given `columns` upon creation.

`model` : | a ClutterModel
`n_columns` : | the number of columns and values to set
`columns` : | a vector containing the columns to set. [array length=n_columns]
`values` : | a vector containing the values for the cells. [array length=n_columns]

Since 0.6

### clutter_model_insert ()

    void                clutter_model_insert                (ClutterModel *model,
                                                             guint row,
                                                             ...);

Inserts a new row to the ClutterModel at `row`, setting the row values upon creation. For example, to insert a new row at index 100, where column 0 is type `G_TYPE_INT` and column 1 is of type `G_TYPE_STRING`:

    1
    2
    3
    4
    5
    ClutterModel *model;
    model = clutter_model_default_new (2,
                                       G_TYPE_INT,    "Score",
                                       G_TYPE_STRING, "Team");
    clutter_model_insert (model, 3, 0, 42, 1, "Team <GTKDOCLINK HREF="1:CAPS">1</GTKDOCLINK>", -1);

`model` : | a ClutterModel
`row` : | the position to insert the new row
`...` : | pairs of column number and value, terminated with -1

Since 0.6

### clutter_model_insertv ()

    void                clutter_model_insertv               (ClutterModel *model,
                                                             guint row,
                                                             guint n_columns,
                                                             guint *columns,
                                                             GValue *values);

Inserts data at `row` into the ClutterModel, setting the row values for the given `columns` upon creation.

`model` : | a ClutterModel
`row` : | row index
`n_columns` : | the number of columns and values to set
`columns` : | a vector containing the columns to set. [array length=n_columns]
`values` : | a vector containing the values for the cells. [array length=n_columns]

Since 0.6

### clutter_model_insert_value ()

    void                clutter_model_insert_value          (ClutterModel *model,
                                                             guint row,
                                                             guint column,
                                                             const GValue *value);

Sets the data in the cell specified by `iter` and `column`. The type of `value` must be convertable to the type of the column. If the row does not exist then it is created.

`model` : | a ClutterModel
`row` : | position of the row to modify
`column` : | column to modify
`value` : | new value for the cell

Since 0.6

### clutter_model_remove ()

    void                clutter_model_remove                (ClutterModel *model,
                                                             guint row);

Removes the row at the given position from the model.

`model` : | a ClutterModel
`row` : | position of row to remove

Since 0.6

### ClutterModelForeachFunc ()

    gboolean            (*ClutterModelForeachFunc)          (ClutterModel *model,
                                                             ClutterModelIter *iter,
                                                             gpointer user_data);

Iterates on the content of a row in the model

`model` : | a ClutterModel
`iter` : | the iterator for the row
`user_data` : | data passed to `clutter_model_foreach()`
Returns : | `TRUE` if the iteration should continue, `FALSE` otherwise

Since 0.6

### clutter_model_foreach ()

    void                clutter_model_foreach               (ClutterModel *model,
                                                             ClutterModelForeachFunc func,
                                                             gpointer user_data);

Calls `func` for each row in the model.

`model` : | a ClutterModel
`func` : | a ClutterModelForeachFunc. [scope call]
`user_data` : | user data to pass to `func`

Since 0.6

### clutter_model_set_sorting_column ()

    void                clutter_model_set_sorting_column    (ClutterModel *model,
                                                             gint column);

Sets the model to sort by `column`. If `column` is a negative value the sorting column will be unset.

`model` : | a ClutterModel
`column` : | the column of the `model` to sort, or -1

Since 0.6

### clutter_model_get_sorting_column ()

    gint                clutter_model_get_sorting_column    (ClutterModel *model);

Retrieves the number of column used for sorting the `model`.

`model` : | a ClutterModel
Returns : | a column number, or -1 if the model is not sorted

Since 0.6

### ClutterModelSortFunc ()

    gint                (*ClutterModelSortFunc)             (ClutterModel *model,
                                                             const GValue *a,
                                                             const GValue *b,
                                                             gpointer user_data);

Compares the content of two rows in the model.

`model` : | a ClutterModel
`a` : | a GValue representing the contents of the row
`b` : | a GValue representing the contents of the second row
`user_data` : | data passed to `clutter_model_set_sort()`
Returns : | a positive integer if `a` is after `b`, a negative integer if `a` is before `b`, or 0 if the rows are the same

Since 0.6

### clutter_model_set_sort ()

    void                clutter_model_set_sort              (ClutterModel *model,
                                                             gint column,
                                                             ClutterModelSortFunc func,
                                                             gpointer user_data,
                                                             GDestroyNotify notify);

Sorts `model` using the given sorting function.

`model` : | a ClutterModel
`column` : | the column to sort on
`func` : | a ClutterModelSortFunc, or NULL. [allow-none]
`user_data` : | user data to pass to `func`, or NULL
`notify` : | destroy notifier of `user_data`, or NULL

Since 0.6

### clutter_model_resort ()

    void                clutter_model_resort                (ClutterModel *model);

Force a resort on the `model`. This function should only be used by subclasses of ClutterModel.

`model` : | a ClutterModel

Since 0.6

### ClutterModelFilterFunc ()

    gboolean            (*ClutterModelFilterFunc)           (ClutterModel *model,
                                                             ClutterModelIter *iter,
                                                             gpointer user_data);

Filters the content of a row in the model.

`model` : | a ClutterModel
`iter` : | the iterator for the row
`user_data` : | data passed to `clutter_model_set_filter()`
Returns : | If the row should be displayed, return `TRUE`

Since 0.6

### clutter_model_set_filter ()

    void                clutter_model_set_filter            (ClutterModel *model,
                                                             ClutterModelFilterFunc func,
                                                             gpointer user_data,
                                                             GDestroyNotify notify);

Filters the `model` using the given filtering function.

`model` : | a ClutterModel
`func` : | a ClutterModelFilterFunc, or NULL. [allow-none]
`user_data` : | user data to pass to `func`, or NULL
`notify` : | destroy notifier of `user_data`, or NULL

Since 0.6

### clutter_model_get_filter_set ()

    gboolean            clutter_model_get_filter_set        (ClutterModel *model);

Returns whether the `model` has a filter in place, set using `clutter_model_set_filter()`

`model` : | a ClutterModel
Returns : | `TRUE` if a filter is set

Since 1.0

### clutter_model_filter_iter ()

    gboolean            clutter_model_filter_iter           (ClutterModel *model,
                                                             ClutterModelIter *iter);

Checks whether the row pointer by `iter` should be filtered or not using the filtering function set on `model`.

This function should be used only by subclasses of ClutterModel.

`model` : | a ClutterModel
`iter` : | the row to filter
Returns : | `TRUE` if the row should be displayed, `FALSE` otherwise

Since 0.6

### clutter_model_filter_row ()

    gboolean            clutter_model_filter_row            (ClutterModel *model,
                                                             guint row);

Checks whether `row` should be filtered or not using the filtering function set on `model`.

This function should be used only by subclasses of ClutterModel.

`model` : | a ClutterModel
`row` : | the row to filter
Returns : | `TRUE` if the row should be displayed, `FALSE` otherwise

Since 0.6

### clutter_model_get_first_iter ()

    ClutterModelIter *  clutter_model_get_first_iter        (ClutterModel *model);

Retrieves a ClutterModelIter representing the first non-filtered row in `model`.

`model` : | a ClutterModel
Returns : | A new ClutterModelIter. Call `g_object_unref()` when done using it. [transfer full]

Since 0.6

### clutter_model_get_last_iter ()

    ClutterModelIter *  clutter_model_get_last_iter         (ClutterModel *model);

Retrieves a ClutterModelIter representing the last non-filtered row in `model`.

`model` : | a ClutterModel
Returns : | A new ClutterModelIter. Call `g_object_unref()` when done using it. [transfer full]

Since 0.6

### clutter_model_get_iter_at_row ()

    ClutterModelIter *  clutter_model_get_iter_at_row       (ClutterModel *model,
                                                             guint row);

Retrieves a ClutterModelIter representing the row at the given index.

If a filter function has been set using `clutter_model_set_filter()` then the `model` implementation will return the first non filtered row.

`model` : | a ClutterModel
`row` : | position of the row to retrieve
Returns : | A new ClutterModelIter, or `NULL` if `row` was out of bounds. When done using the iterator object, call `g_object_unref()` to deallocate its resources. [transfer full]

Since 0.6

## Property Details

### The `"filter-set"` property

      "filter-set"               gboolean              : Read

Whether the ClutterModel has a filter set

This property is set to `TRUE` if a filter function has been set using `clutter_model_set_filter()`

Default value: FALSE

Since 1.0

## Signal Details

### The `"filter-changed"` signal

    void                user_function                      (ClutterModel *model,
                                                            gpointer      user_data)      : Run Last

The ::filter-changed signal is emitted when a new filter has been applied

`model` : | the ClutterModel on which the signal is emitted
`user_data` : | user data set when the signal handler was connected.

Since 0.6

### The `"row-added"` signal

    void                user_function                      (ClutterModel     *model,
                                                            ClutterModelIter *iter,
                                                            gpointer          user_data)      : Run Last

The ::row-added signal is emitted when a new row has been added. The data on the row has already been set when the ::row-added signal has been emitted.

`model` : | the ClutterModel on which the signal is emitted
`iter` : | a ClutterModelIter pointing to the new row
`user_data` : | user data set when the signal handler was connected.

Since 0.6

### The `"row-changed"` signal

    void                user_function                      (ClutterModel     *model,
                                                            ClutterModelIter *iter,
                                                            gpointer          user_data)      : Run Last

The ::row-removed signal is emitted when a row has been changed. The data on the row has already been updated when the ::row-changed signal has been emitted.

`model` : | the ClutterModel on which the signal is emitted
`iter` : | a ClutterModelIter pointing to the changed row
`user_data` : | user data set when the signal handler was connected.

Since 0.6

### The `"row-removed"` signal

    void                user_function                      (ClutterModel     *model,
                                                            ClutterModelIter *iter,
                                                            gpointer          user_data)      : Run Last

The ::row-removed signal is emitted when a row has been removed. The data on the row pointed by the passed iterator is still valid when the ::row-removed signal has been emitted.

`model` : | the ClutterModel on which the signal is emitted
`iter` : | a ClutterModelIter pointing to the removed row
`user_data` : | user data set when the signal handler was connected.

Since 0.6

### The `"sort-changed"` signal

    void                user_function                      (ClutterModel *model,
                                                            gpointer      user_data)      : Run Last

The ::sort-changed signal is emitted after the model has been sorted

`model` : | the ClutterModel on which the signal is emitted
`user_data` : | user data set when the signal handler was connected.

Since 0.6