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

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

Generated by GTK-Doc V1.10