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

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.

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.

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

Since: 0.6

clutter_model_get_column_type ()

GType
clutter_model_get_column_type (ClutterModel *model,
                               guint column);

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

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

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

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.

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

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.

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

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.

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.

Since: 0.6

clutter_model_remove ()

void
clutter_model_remove (ClutterModel *model,
                      guint row);

Removes the row at the given position from the model.

Since: 0.6

ClutterModelForeachFunc ()

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

Iterates on the content of a row in the model

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.

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.

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 .

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.

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.

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.

Since: 0.6

ClutterModelFilterFunc ()

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

Filters the content of a row in the model.

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.

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

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.

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.

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 .

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 .

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.

Since: 0.6

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.

Since: 0.6

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

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

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.

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.

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.

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

Flags: Run Last

Since: 0.6