clutter/clutter-model.h

   1 /*
   2  * Clutter.
   3  *
   4  * An OpenGL based 'interactive canvas' library.
   5  *
   6  * Authored By Matthew Allum  <mallum@openedhand.com>
   7  *             Neil Jagdish Patel <njp@o-hand.com>
   8  *             Emmanuele Bassi <ebassi@openedhand.com>
   9  *
  10  * Copyright (C) 2006 OpenedHand
  11  *
  12  * This library is free software; you can redistribute it and/or
  13  * modify it under the terms of the GNU Lesser General Public
  14  * License as published by the Free Software Foundation; either
  15  * version 2 of the License, or (at your option) any later version.
  16  *
  17  * This library is distributed in the hope that it will be useful,
  18  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  19  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  20  * Lesser General Public License for more details.
  21  *
  22  * You should have received a copy of the GNU Lesser General Public
  23  * License along with this library. If not, see <http://www.gnu.org/licenses/>.
  24  */
  25
  26 #if !defined(__CLUTTER_H_INSIDE__) && !defined(CLUTTER_COMPILATION)
  27 #error "Only <clutter/clutter.h> can be included directly."
  28 #endif
  29
  30 #ifndef __CLUTTER_MODEL_H__
  31 #define __CLUTTER_MODEL_H__
  32
  33 #include <glib-object.h>
  34
  35 G_BEGIN_DECLS
  36
  37 #define CLUTTER_TYPE_MODEL              (clutter_model_get_type ())
  38 #define CLUTTER_MODEL(obj)              (G_TYPE_CHECK_INSTANCE_CAST ((obj), CLUTTER_TYPE_MODEL, ClutterModel))
  39 #define CLUTTER_MODEL_CLASS(klass)      (G_TYPE_CHECK_CLASS_CAST ((klass), CLUTTER_TYPE_MODEL, ClutterModelClass))
  40 #define CLUTTER_IS_MODEL(obj)           (G_TYPE_CHECK_INSTANCE_TYPE ((obj), CLUTTER_TYPE_MODEL))
  41 #define CLUTTER_IS_MODEL_CLASS(klass)   (G_TYPE_CHECK_CLASS_TYPE ((klass), CLUTTER_TYPE_MODEL))
  42 #define CLUTTER_MODEL_GET_CLASS(obj)    (G_TYPE_INSTANCE_GET_CLASS ((obj), CLUTTER_TYPE_MODEL, ClutterModelClass))
  43
  44 typedef struct _ClutterModel            ClutterModel;
  45 typedef struct _ClutterModelClass       ClutterModelClass;
  46 typedef struct _ClutterModelPrivate     ClutterModelPrivate;
  47 typedef struct _ClutterModelIter        ClutterModelIter;
  48 typedef struct _ClutterModelIterClass   ClutterModelIterClass;
  49 typedef struct _ClutterModelIterPrivate ClutterModelIterPrivate;
  50
  51
  52 /**
  53  * ClutterModelFilterFunc:
  54  * @model: a #ClutterModel
  55  * @iter: the iterator for the row
  56  * @user_data: data passed to clutter_model_set_filter()
  57  *
  58  * Filters the content of a row in the model.
  59  *
  60  * Return value: If the row should be displayed, return %TRUE
  61  *
  62  * Since: 0.6
  63  */
  64 typedef gboolean (*ClutterModelFilterFunc) (ClutterModel     *model,
  65                                             ClutterModelIter *iter,
  66                                             gpointer          user_data);
  67
  68 /**
  69  * ClutterModelSortFunc:
  70  * @model: a #ClutterModel
  71  * @a: a #GValue representing the contents of the row
  72  * @b: a #GValue representing the contents of the second row
  73  * @user_data: data passed to clutter_model_set_sort()
  74  *
  75  * Compares the content of two rows in the model.
  76  *
  77  * Return value: a positive integer if @a is after @b, a negative integer if
  78  *   @a is before @b, or 0 if the rows are the same
  79  *
  80  * Since: 0.6
  81  */
  82 typedef gint (*ClutterModelSortFunc) (ClutterModel *model,
  83                                       const GValue *a,
  84                                       const GValue *b,
  85                                       gpointer      user_data);
  86
  87 /**
  88  * ClutterModelForeachFunc:
  89  * @model: a #ClutterModel
  90  * @iter: the iterator for the row
  91  * @user_data: data passed to clutter_model_foreach()
  92  *
  93  * Iterates on the content of a row in the model
  94  *
  95  * Return value: %TRUE if the iteration should continue, %FALSE otherwise
  96  *
  97  * Since: 0.6
  98  */
  99 typedef gboolean (*ClutterModelForeachFunc) (ClutterModel     *model,
 100                                              ClutterModelIter *iter,
 101                                              gpointer          user_data);
 102
 103 /**
 104  * ClutterModel:
 105  *
 106  * Base class for list models. The #ClutterModel structure contains
 107  * only private data and should be manipulated using the provided
 108  * API.
 109  *
 110  * Since: 0.6
 111  */
 112 struct _ClutterModel
 113 {
 114   /*< private >*/
 115   GObject parent_instance;
 116
 117   ClutterModelPrivate *priv;
 118 };
 119
 120 /**
 121  * ClutterModelClass:
 122  * @row_added: signal class handler for ClutterModel::row-added
 123  * @row_removed: signal class handler for ClutterModel::row-removed
 124  * @row_changed: signal class handler for ClutterModel::row-changed
 125  * @sort_changed: signal class handler for ClutterModel::sort-changed
 126  * @filter_changed: signal class handler for ClutterModel::filter-changed
 127  * @get_column_name: virtual function for returning the name of a column
 128  * @get_column_type: virtual function for returning the type of a column
 129  * @get_iter_at_row: virtual function for returning an iterator for the
 130  *   given row
 131  * @get_n_rows: virtual function for returning the number of rows
 132  *   of the model
 133  * @get_n_columns: virtual function for retuning the number of columns
 134  *   of the model
 135  * @resort: virtual function for sorting the model using the passed
 136  *   sorting function
 137  * @insert_row: virtual function for inserting a row at the given index
 138  *   and returning an iterator pointing to it; if the index is a negative
 139  *   integer, the row should be appended to the model
 140  * @remove_row: virtual function for removing a row at the given index
 141  *
 142  * Class for #ClutterModel instances.
 143  *
 144  * Since: 0.6
 145  */
 146 struct _ClutterModelClass
 147 {
 148   /*< private >*/
 149   GObjectClass parent_class;
 150
 151   /*< public >*/
 152   /* vtable */
 153   guint             (* get_n_rows)      (ClutterModel         *model);
 154   guint             (* get_n_columns)   (ClutterModel         *model);
 155   const gchar *     (* get_column_name) (ClutterModel         *model,
 156                                          guint                 column);
 157   GType             (* get_column_type) (ClutterModel         *model,
 158                                          guint                 column);
 159   ClutterModelIter *(* insert_row)      (ClutterModel         *model,
 160                                          gint                  index_);
 161   void              (* remove_row)      (ClutterModel         *model,
 162                                          guint                 row);
 163   ClutterModelIter *(* get_iter_at_row) (ClutterModel         *model,
 164                                          guint                 row);
 165   void              (* resort)          (ClutterModel         *model,
 166                                          ClutterModelSortFunc  func,
 167                                          gpointer              data);
 168
 169   /* signals */
 170   void              (* row_added)       (ClutterModel     *model,
 171                                          ClutterModelIter *iter);
 172   void              (* row_removed)     (ClutterModel     *model,
 173                                          ClutterModelIter *iter);
 174   void              (* row_changed)     (ClutterModel     *model,
 175                                          ClutterModelIter *iter);
 176   void              (* sort_changed)    (ClutterModel     *model);
 177   void              (* filter_changed)  (ClutterModel     *model);
 178
 179   /*< private >*/
 180   /* padding for future expansion */
 181   void (*_clutter_model_1) (void);
 182   void (*_clutter_model_2) (void);
 183   void (*_clutter_model_3) (void);
 184   void (*_clutter_model_4) (void);
 185   void (*_clutter_model_5) (void);
 186   void (*_clutter_model_6) (void);
 187   void (*_clutter_model_7) (void);
 188   void (*_clutter_model_8) (void);
 189 };
 190
 191 GType                 clutter_model_get_type           (void) G_GNUC_CONST;
 192
 193 void                  clutter_model_set_types          (ClutterModel     *model,
 194                                                         guint             n_columns,
 195                                                         GType            *types);
 196 void                  clutter_model_set_names          (ClutterModel     *model,
 197                                                         guint             n_columns,
 198                                                         const gchar * const names[]);
 199
 200 void                  clutter_model_append             (ClutterModel     *model,
 201                                                         ...);
 202 void                  clutter_model_appendv            (ClutterModel     *model,
 203                                                         guint             n_columns,
 204                                                         guint            *columns,
 205                                                         GValue           *values);
 206 void                  clutter_model_prepend            (ClutterModel     *model,
 207                                                         ...);
 208 void                  clutter_model_prependv           (ClutterModel     *model,
 209                                                         guint             n_columns,
 210                                                         guint            *columns,
 211                                                         GValue           *values);
 212 void                  clutter_model_insert             (ClutterModel     *model,
 213                                                         guint             row,
 214                                                         ...);
 215 void                  clutter_model_insertv            (ClutterModel     *model,
 216                                                         guint             row,
 217                                                         guint             n_columns,
 218                                                         guint            *columns,
 219                                                         GValue           *values);
 220 void                  clutter_model_insert_value       (ClutterModel     *model,
 221                                                         guint             row,
 222                                                         guint             column,
 223                                                         const GValue     *value);
 224 void                  clutter_model_remove             (ClutterModel     *model,
 225                                                         guint             row);
 226
 227 guint                 clutter_model_get_n_rows         (ClutterModel     *model);
 228 guint                 clutter_model_get_n_columns      (ClutterModel     *model);
 229 const gchar *         clutter_model_get_column_name    (ClutterModel     *model,
 230                                                         guint             column);
 231 GType                 clutter_model_get_column_type    (ClutterModel     *model,
 232                                                         guint             column);
 233
 234 ClutterModelIter *    clutter_model_get_first_iter     (ClutterModel     *model);
 235 ClutterModelIter *    clutter_model_get_last_iter      (ClutterModel     *model);
 236 ClutterModelIter *    clutter_model_get_iter_at_row    (ClutterModel     *model,
 237                                                         guint             row);
 238
 239 void                  clutter_model_set_sorting_column (ClutterModel     *model,
 240                                                         gint              column);
 241 gint                  clutter_model_get_sorting_column (ClutterModel     *model);
 242
 243 void                  clutter_model_foreach            (ClutterModel     *model,
 244                                                         ClutterModelForeachFunc func,
 245                                                         gpointer          user_data);
 246 void                  clutter_model_set_sort           (ClutterModel     *model,
 247                                                         gint              column,
 248                                                         ClutterModelSortFunc func,
 249                                                         gpointer          user_data,
 250                                                         GDestroyNotify    notify);
 251 void                  clutter_model_set_filter         (ClutterModel     *model,
 252                                                         ClutterModelFilterFunc func,
 253                                                         gpointer          user_data,
 254                                                         GDestroyNotify    notify);
 255 gboolean              clutter_model_get_filter_set     (ClutterModel     *model);
 256
 257 void                  clutter_model_resort             (ClutterModel     *model);
 258 gboolean              clutter_model_filter_row         (ClutterModel     *model,
 259                                                         guint             row);
 260 gboolean              clutter_model_filter_iter        (ClutterModel     *model,
 261                                                         ClutterModelIter *iter);
 262
 263 /*
 264  * ClutterModelIter
 265  */
 266
 267 #define CLUTTER_TYPE_MODEL_ITER                 (clutter_model_iter_get_type ())
 268 #define CLUTTER_MODEL_ITER(obj)                 (G_TYPE_CHECK_INSTANCE_CAST ((obj), CLUTTER_TYPE_MODEL_ITER, ClutterModelIter))
 269 #define CLUTTER_MODEL_ITER_CLASS(klass)         (G_TYPE_CHECK_CLASS_CAST ((klass), CLUTTER_TYPE_MODEL_ITER, ClutterModelIterClass))
 270 #define CLUTTER_IS_MODEL_ITER(obj)              (G_TYPE_CHECK_INSTANCE_TYPE ((obj), CLUTTER_TYPE_MODEL_ITER))
 271 #define CLUTTER_IS_MODEL_ITER_CLASS(klass)      (G_TYPE_CHECK_CLASS_TYPE ((klass), CLUTTER_TYPE_MODEL_ITER))
 272 #define CLUTTER_MODEL_ITER_GET_CLASS(obj)       (G_TYPE_INSTANCE_GET_CLASS ((obj), CLUTTER_TYPE_MODEL_ITER, ClutterModelIterClass))
 273
 274 /**
 275  * ClutterModelIter:
 276  *
 277  * Base class for list models iters. The #ClutterModelIter structure
 278  * contains only private data and should be manipulated using the
 279  * provided API.
 280  *
 281  * Since: 0.6
 282  */
 283 struct _ClutterModelIter
 284 {
 285   /*< private >*/
 286   GObject parent_instance;
 287
 288   ClutterModelIterPrivate *priv;
 289 };
 290
 291 /**
 292  * ClutterModelIterClass:
 293  * @get_value: Virtual function for retrieving the value at the given
 294  *   column of the row pointed by the iterator
 295  * @set_value: Virtual function for setting the value at the given
 296  *   column of the row pointer by the iterator
 297  * @is_last: Virtual function for knowing whether the iterator points
 298  *   at the last row in the model
 299  * @is_first: Virtual function for knowing whether the iterator points
 300  *   at the first row in the model
 301  * @next: Virtual function for moving the iterator to the following
 302  *   row in the model
 303  * @prev: Virtual function for moving the iterator toe the previous
 304  *   row in the model
 305  * @get_model: Virtual function for getting the model to which the
 306  *   iterator belongs to
 307  * @get_row: Virtual function for getting the row to which the iterator
 308  *   points
 309  * @copy: Virtual function for copying a #ClutterModelIter.
 310  *
 311  * Class for #ClutterModelIter instances.
 312  *
 313  * Since: 0.6
 314  */
 315 struct _ClutterModelIterClass
 316 {
 317   /*< private >*/
 318   GObjectClass parent_class;
 319
 320   /*< public >*/
 321   /* vtable not signals */
 322   void              (* get_value) (ClutterModelIter *iter,
 323                                    guint             column,
 324                                    GValue           *value);
 325   void              (* set_value) (ClutterModelIter *iter,
 326                                    guint             column,
 327                                    const GValue     *value);
 328
 329   gboolean          (* is_first)  (ClutterModelIter *iter);
 330   gboolean          (* is_last)   (ClutterModelIter *iter);
 331
 332   ClutterModelIter *(* next)      (ClutterModelIter *iter);
 333   ClutterModelIter *(* prev)      (ClutterModelIter *iter);
 334
 335   ClutterModel *    (* get_model) (ClutterModelIter *iter);
 336   guint             (* get_row)   (ClutterModelIter *iter);
 337
 338   ClutterModelIter *(* copy)      (ClutterModelIter *iter);
 339
 340   /*< private >*/
 341   /* padding for future expansion */
 342   void (*_clutter_model_iter_1) (void);
 343   void (*_clutter_model_iter_2) (void);
 344   void (*_clutter_model_iter_3) (void);
 345   void (*_clutter_model_iter_4) (void);
 346   void (*_clutter_model_iter_5) (void);
 347   void (*_clutter_model_iter_6) (void);
 348   void (*_clutter_model_iter_7) (void);
 349   void (*_clutter_model_iter_8) (void);
 350 };
 351
 352 GType             clutter_model_iter_get_type   (void) G_GNUC_CONST;
 353
 354 void              clutter_model_iter_get        (ClutterModelIter *iter,
 355                                                  ...);
 356 void              clutter_model_iter_get_valist (ClutterModelIter *iter,
 357                                                  va_list          args);
 358 void              clutter_model_iter_get_value  (ClutterModelIter *iter,
 359                                                  guint             column,
 360                                                  GValue           *value);
 361 void              clutter_model_iter_set        (ClutterModelIter *iter,
 362                                                  ...);
 363 void              clutter_model_iter_set_valist (ClutterModelIter *iter,
 364                                                  va_list          args);
 365 void              clutter_model_iter_set_value  (ClutterModelIter *iter,
 366                                                  guint             column,
 367                                                  const GValue     *value);
 368
 369 gboolean          clutter_model_iter_is_first   (ClutterModelIter *iter);
 370 gboolean          clutter_model_iter_is_last    (ClutterModelIter *iter);
 371 ClutterModelIter *clutter_model_iter_next       (ClutterModelIter *iter);
 372 ClutterModelIter *clutter_model_iter_prev       (ClutterModelIter *iter);
 373
 374 ClutterModel *    clutter_model_iter_get_model  (ClutterModelIter *iter);
 375 guint             clutter_model_iter_get_row    (ClutterModelIter *iter);
 376
 377 ClutterModelIter *clutter_model_iter_copy       (ClutterModelIter *iter);
 378
 379 G_END_DECLS
 380
 381 #endif /* __CLUTTER_MODEL_H__ */