hi everyone;
in this mail I'll expose the ClutterModel API that will be available in
Clutter 0.6.
ClutterModel is a generic class that can be used as the base for actors
implementing the MVC [Model Viewer Controller] design pattern. a
ClutterModel is a table composed of columns, each holding a specific
data type, and rows.
while ClutterModel is an abstract type, Clutter provides a default
ClutterModel implementation called ClutterModelDefault; the default
implementation uses GSequence - a data type exposed by GLib 2.14 and
optimised for insertion and look up in sorted lists; it's the same data
type used, for instance, by the GtkListStore class.
for instance, this is the constructor for a default model:
ClutterModel *model;
model = clutter_model_default_new (4,
G_TYPE_INT, "Score",
G_TYPE_BOOLEAN, "Favourite",
G_TYPE_STRING, "Team Name",
GDK_TYPE_PIXBUF, "Team Logo");
the model has four columns:
Score (integer) | Favourite (boolean) | Team Name (string) | Team Logo
(pixbuf)
----------------+---------------------+--------------------+-------------------
1 ... | ... | ... | ...
2 ... | ... | ... | ...
and each row can be appended, prepended or just inserted at the given
index using the ClutterModel API:
clutter_model_append (model,
COLUMN_SCORE, 42,
COLUMN_FAVOURITE, TRUE,
COLUMN_TEAM_NAME, "My Team",
COLUMN_TEAM_LOGO, my_team_logo,
-1);
iteration on a model is done using the ClutterModelIter object methods;
the basic usage is retrieving an iterator at the given row and then keep
calling clutter_model_iter_next() to iterate on the following rows:
iter = clutter_model_get_iter_at_row (model, 42);
while (!clutter_model_iter_is_last (iter))
{
gint score;
gboolean favourite;
gchar *name;
GdkPixbuf *logo;
clutter_model_iter_get (iter,
COLUMN_SCORE, &score,
COLUMN_FAVOURITE, &favourite,
COLUMN_TEAM_NAME, &name,
COLUMN_TEAM_LOGO, &logo,
-1);
/* ... operate on the data ... */
/* clutter_model_iter_get() returns a copy of the data */
g_free (name);
g_object_unref (logo);
}
g_object_unref (iter);
the obvious differences with the GtkTreeModel API is that ClutterModel
favours the lists implementations, and that iterators are full objects.
the ClutterModel API tries its best to provide as much introspection as
possible for actors based on them. it is perfectly possible to construct
a generic table-like actor displaying the data inside a ClutterModel in
such a way that a single call is needed:
list_view = tidy_list_view_new (model);
and all the columns, rows, types and names are already available for it
do display.
in the tradition (and guidelines) of Clutter core, the generic model is
just a convenient uniform API: developers are encouraged to subclass
ClutterModel and make their own implementations, using for instance
sqllite, bdb, or even high-level languages data types. subclassing a
ClutterModel is fairly easy: the base class provides sane default
implementations for most of its functions, so that the only methods that
must be overridden are:
ClutterModelIter *(* insert_row) (ClutterModel *model,
gint index_);
void (* remove_row) (ClutterModel *model,
guint row);
ClutterModelIter *(* get_iter_at_row) (ClutterModel *model,
guint row);
guint (* get_n_rows) (ClutterModel *model); [1]
void (* resort) (ClutterModel *model);
and, obviously, the ClutterModelIter methods (next, prev, is_first,
is_last, get_value, set_value). the default implementation of model and
iterator using GSequence is 630 lines long, including license notice,
documentation and comments. it is possible for subclasses of
ClutterModel to completely override the introspection functions, such as
get_column_name() and get_column_type() and get_n_columns().
ClutterModel provides API for sorting and filtering the model using
custom functions; while sorting is usually model-specific (hence the
presence of a ::resort() virtual function in ClutterModelClass),
filtering is implemented by just using the abstract API.
actors implementing the Viewer in the MVC pattern should rely on the
signals emitted by a model implementation:
row-added
row-removed
row-changed
sort-changed
filter-changed
to update themselves.
ciao,
Emmanuele.
+++
[1] get_n_rows() is required as of trunk, but it won't be needed by the
time 0.6 is released, and will remain as an optimisation override.
--
Emmanuele Bassi, OpenedHand Ltd.
Unit R, Homesdale Business Centre
216-218 Homesdale Rd., Bromley - BR12QZ
http://www.o-hand.com
--
To unsubscribe send a mail to [EMAIL PROTECTED]
