ClutterModel

ClutterModel — A generic model implementation

Synopsis




                    ClutterModel;
                    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,
                                                         guint 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_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

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:

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:

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 default model implementation called ClutterModelDefault which has been optimised for insertion and look up in sorted lists.

ClutterModel is available since Clutter 0.6

Details

ClutterModel

typedef struct _ClutterModel ClutterModel;

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

Since 0.6


ClutterModelClass

typedef struct {
  /* 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);
} ClutterModelClass;

Class for ClutterModel instances.

get_n_rows () virtual function for returning the number of rows of the model, not considering any filter function if present
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

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

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.

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:

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

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
values : a vector with the values

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:

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

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
values : a vector containing the values for the cells

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:

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

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
values : a vector containing the values for the cells

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
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,
                                                         guint 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
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
user_data : user data to pass to func, or NULL
notify : destroy notifier of user_data, or NULL

Since 0.6


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 row in model.

model : a ClutterModel
Returns : A new ClutterModelIter. Call g_object_unref() when done using it

Since 0.6


clutter_model_get_last_iter ()

ClutterModelIter*   clutter_model_get_last_iter         (ClutterModel *model);

Retrieves a ClutterModelIter representing the last row in model.

model : a ClutterModel
Returns : A new ClutterModelIter. Call g_object_unref() when done using it

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.

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

Since 0.6

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