## ClutterModel

ClutterModel — A generic model implementation

## Functions

void | clutter_model_set_names ()
void | clutter_model_set_types ()
const gchar * | clutter_model_get_column_name ()
GType | clutter_model_get_column_type ()
guint | clutter_model_get_n_columns ()
guint | clutter_model_get_n_rows ()
void | clutter_model_append ()
void | clutter_model_appendv ()
void | clutter_model_prepend ()
void | clutter_model_prependv ()
void | clutter_model_insert ()
void | clutter_model_insertv ()
void | clutter_model_insert_value ()
void | clutter_model_remove ()
gboolean | (*ClutterModelForeachFunc) ()
void | clutter_model_foreach ()
void | clutter_model_set_sorting_column ()
gint | clutter_model_get_sorting_column ()
gint | (*ClutterModelSortFunc) ()
void | clutter_model_set_sort ()
void | clutter_model_resort ()
gboolean | (*ClutterModelFilterFunc) ()
void | clutter_model_set_filter ()
gboolean | clutter_model_get_filter_set ()
gboolean | clutter_model_filter_iter ()
gboolean | clutter_model_filter_row ()
ClutterModelIter * | clutter_model_get_first_iter ()
ClutterModelIter * | clutter_model_get_last_iter ()
ClutterModelIter * | clutter_model_get_iter_at_row ()

## Properties

gboolean | filter-set | Read

## Signals

void | filter-changed | Run Last
void | row-added | Run Last
void | row-changed | Run Last
void | row-removed | Run Last
void | sort-changed | Run Last

## Types and Values

struct | ClutterModel
struct | ClutterModelClass

## Object Hierarchy

        GObject
        ╰── ClutterModel
            ╰── ClutterListModel

## Implemented Interfaces

ClutterModel implements ClutterScriptable.

## 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 ClutterModel

The example below shows how to create a simple list 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_list_model_new (N_COLUMNS,
                                      // column type, 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 a ClutterModel

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.

    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 iterator for the first row in the model
      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 is available since Clutter 0.6

#### 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.

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.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14

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

## Functions

### 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.

#### Parameters

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.

#### Parameters

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`

#### Parameters

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` .

#### Parameters

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` .

#### Parameters

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()`.

#### Parameters

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`:

<informalexample><programlisting> ClutterModel *model; model = clutter_model_default_new (2, G_TYPE_INT, "Score", G_TYPE_STRING, "Team"); clutter_model_append (model, 0, 42, 1, "Team #1", -1); </programlisting></informalexample>

#### Parameters

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.

#### Parameters

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`:

<informalexample><programlisting> ClutterModel *model; model = clutter_model_default_new (2, G_TYPE_INT, "Score", G_TYPE_STRING, "Team"); clutter_model_prepend (model, 0, 42, 1, "Team #1", -1); </programlisting></informalexample>

#### Parameters

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.

#### Parameters

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`:

<informalexample><programlisting> 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 #1", -1); </programlisting></informalexample>

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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` .

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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()`

#### Parameters

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.

#### Parameters

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.

#### Parameters

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` .

#### Parameters

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` .

#### Parameters

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.

#### Parameters

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

## Types and Values

### 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.

#### Members

`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

## Property Details

### The `“filter-set”` property

      “filter-set”               gboolean

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()`

Flags: Read

Default value: FALSE

Since 1.0

## Signal Details

### The `“filter-changed”` signal

    void
    user_function (ClutterModel *model,
                   gpointer      user_data)

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

#### Parameters

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

Flags: Run Last

Since 0.6

### The `“row-added”` signal

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

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.

#### Parameters

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. |

Flags: Run Last

Since 0.6

### The `“row-changed”` signal

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

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.

#### Parameters

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. |

Flags: Run Last

Since 0.6

### The `“row-removed”` signal

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

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.

#### Parameters

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. |

Flags: Run Last

Since 0.6

### The `“sort-changed”` signal

    void
    user_function (ClutterModel *model,
                   gpointer      user_data)

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

#### Parameters

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

Flags: Run Last

Since 0.6