DeeModel

DeeModel — A generic table model interface

Synopsis

#include <dee.h>

                    DeeModelIface;
                    DeeModel;
                    DeeModelIter;
gboolean            dee_model_check_type                (GType type);
GType               dee_model_get_type_for_signature    (gchar chr);
gchar*              dee_model_build_col_spec            (DeeModel *self);
void                dee_model_set_column_type           (DeeModel *self,
                                                         guint column,
                                                         GType type);
void                dee_model_set_n_columns             (DeeModel *self,
                                                         guint n_columns);
guint               dee_model_get_n_columns             (DeeModel *self);
guint               dee_model_get_n_rows                (DeeModel *self);
GType               dee_model_get_column_type           (DeeModel *self,
                                                         guint column);
void                dee_model_clear                     (DeeModel *self);
DeeModelIter*       dee_model_append                    (DeeModel *self,
                                                         ...);
DeeModelIter*       dee_model_append_valist             (DeeModel *self,
                                                         va_list args);
DeeModelIter*       dee_model_prepend                   (DeeModel *self,
                                                         ...);
DeeModelIter*       dee_model_prepend_valist            (DeeModel *self,
                                                         va_list args);
DeeModelIter*       dee_model_insert                    (DeeModel *self,
                                                         gint pos,
                                                         ...);
DeeModelIter*       dee_model_insert_valist             (DeeModel *self,
                                                         gint pos,
                                                         va_list args);
DeeModelIter*       dee_model_insert_before             (DeeModel *self,
                                                         DeeModelIter *iter,
                                                         ...);
DeeModelIter*       dee_model_insert_before_valist      (DeeModel *self,
                                                         DeeModelIter *iter,
                                                         va_list args);
void                dee_model_remove                    (DeeModel *self,
                                                         DeeModelIter *iter);
void                dee_model_set                       (DeeModel *self,
                                                         DeeModelIter *iter,
                                                         ...);
void                dee_model_set_valist                (DeeModel *self,
                                                         DeeModelIter *iter,
                                                         va_list args);
void                dee_model_set_value                 (DeeModel *self,
                                                         DeeModelIter *iter,
                                                         guint column,
                                                         const GValue *value);
void                dee_model_set_value_silently        (DeeModel *self,
                                                         DeeModelIter *iter,
                                                         guint column,
                                                         const GValue *value);
void                dee_model_get                       (DeeModel *self,
                                                         DeeModelIter *iter,
                                                         ...);
void                dee_model_get_valist                (DeeModel *self,
                                                         DeeModelIter *iter,
                                                         va_list args);
void                dee_model_get_value                 (DeeModel *self,
                                                         DeeModelIter *iter,
                                                         guint column,
                                                         GValue *value);
DeeModelIter *      dee_model_get_first_iter            (DeeModel *self);
DeeModelIter *      dee_model_get_last_iter             (DeeModel *self);
DeeModelIter *      dee_model_get_iter_at_row           (DeeModel *self,
                                                         guint row);
gboolean            dee_model_get_bool                  (DeeModel *self,
                                                         DeeModelIter *iter,
                                                         guint column);
guchar              dee_model_get_uchar                 (DeeModel *self,
                                                         DeeModelIter *iter,
                                                         guint column);
gint                dee_model_get_int                   (DeeModel *self,
                                                         DeeModelIter *iter,
                                                         guint column);
guint               dee_model_get_uint                  (DeeModel *self,
                                                         DeeModelIter *iter,
                                                         guint column);
gint64              dee_model_get_int64                 (DeeModel *self,
                                                         DeeModelIter *iter,
                                                         guint column);
guint64             dee_model_get_uint64                (DeeModel *self,
                                                         DeeModelIter *iter,
                                                         guint column);
gdouble             dee_model_get_double                (DeeModel *self,
                                                         DeeModelIter *iter,
                                                         guint column);
const gchar *       dee_model_get_string                (DeeModel *self,
                                                         DeeModelIter *iter,
                                                         guint column);
DeeModelIter *      dee_model_next                      (DeeModel *self,
                                                         DeeModelIter *iter);
DeeModelIter *      dee_model_prev                      (DeeModel *self,
                                                         DeeModelIter *iter);
gboolean            dee_model_is_first                  (DeeModel *self,
                                                         DeeModelIter *iter);
gboolean            dee_model_is_last                   (DeeModel *self,
                                                         DeeModelIter *iter);
gint                dee_model_get_position              (DeeModel *self,
                                                         DeeModelIter *iter);
void                dee_model_freeze_signals            (DeeModel *self);
void                dee_model_thaw_signals              (DeeModel *self);

Object Hierarchy

  GInterface
   +----DeeModel

Prerequisites

DeeModel requires GObject.

Known Implementations

DeeModel is implemented by DeeFilterModel, DeeProxyModel, DeeSequenceModel, DeeSharedModel and DeeVersionedModel.

Signals

  "row-added"                                      : Run Last
  "row-changed"                                    : Run Last
  "row-removed"                                    : Run Last

Description

DeeModel is a generic table model that can hold most GLib Types as column types.

Details

DeeModelIface

typedef struct {
  GTypeInterface g_iface;

  /* Signals */
  void           (*row_added)       (DeeModel     *self,
                                     DeeModelIter *iter);

  void           (*row_removed)     (DeeModel     *self,
                                     DeeModelIter *iter);

  void           (*row_changed)     (DeeModel     *self,
                                     DeeModelIter *iter);

  void           (* set_column_type)(DeeModel     *self,
                                     guint         column,
                                     GType         type);

  void           (* set_n_columns)  (DeeModel     *self,
                                     guint         n_columns);
  
  guint          (*get_n_columns)   (DeeModel *self);

  guint          (*get_n_rows)      (DeeModel *self);

  GType          (*get_column_type) (DeeModel *self,
                                     guint      column);

  void           (*clear)           (DeeModel *self);

  DeeModelIter*  (*append_valist)    (DeeModel *self,
                                      va_list    args);

  DeeModelIter*  (*prepend_valist)   (DeeModel *self,
                                      va_list    args);

  DeeModelIter*  (*insert_valist)    (DeeModel *self,
                                      gint       pos,
                                      va_list    args);

  DeeModelIter*  (*insert_before_valist) (DeeModel     *self,
                                          DeeModelIter *iter,
                                          va_list    args);

  void           (*remove)          (DeeModel     *self,
                                     DeeModelIter *iter);

  void           (*set_valist)      (DeeModel       *self,
                                     DeeModelIter   *iter,
                                     va_list          args);

  void           (*set_value)       (DeeModel       *self,
                                     DeeModelIter   *iter,
                                     guint            column,
                                     const GValue    *value);

  void           (*set_value_silently) (DeeModel       *self,
                                        DeeModelIter   *iter,
                                        guint            column,
                                        const GValue    *value);
  
  void           (*get_valist)      (DeeModel     *self,
                                     DeeModelIter *iter,
                                     va_list        args);

  void           (*get_value)       (DeeModel     *self,
                                     DeeModelIter *iter,
                                     guint          column,
                                     GValue        *value);
  
  DeeModelIter* (*get_first_iter)  (DeeModel     *self);

  DeeModelIter* (*get_last_iter)   (DeeModel     *self);

  DeeModelIter* (*get_iter_at_row) (DeeModel     *self,
                                     guint          row);

  gboolean       (*get_bool)        (DeeModel     *self,
                                     DeeModelIter *iter,
                                     guint          column);

  guchar         (*get_uchar)       (DeeModel     *self,
                                     DeeModelIter *iter,
                                     guint          column);

  gint           (*get_int)         (DeeModel     *self,
                                     DeeModelIter *iter,
                                     guint          column);

  guint          (*get_uint)        (DeeModel     *self,
                                     DeeModelIter *iter,
                                     guint          column);

  gint64         (*get_int64)       (DeeModel     *self,
                                     DeeModelIter *iter,
                                     guint          column);

  guint64        (*get_uint64)      (DeeModel     *self,
                                     DeeModelIter *iter,
                                     guint          column);

  gdouble        (*get_double)      (DeeModel     *self,
                                     DeeModelIter *iter,
                                     guint          column);

  const gchar*   (*get_string)      (DeeModel     *self,
                                     DeeModelIter *iter,
                                     guint          column);

  DeeModelIter*  (*next)            (DeeModel     *self,
                                     DeeModelIter *iter);

  DeeModelIter*  (*prev)            (DeeModel     *self,
                                     DeeModelIter *iter);

  gboolean       (*is_first)        (DeeModel     *self,
                                     DeeModelIter *iter);

  gboolean       (*is_last)         (DeeModel     *self,
                                     DeeModelIter *iter);

  gint           (*get_position)    (DeeModel     *self,
                                     DeeModelIter *iter);

  void           (*freeze_signals)  (DeeModel     *self);
  
  void           (*thaw_signals)    (DeeModel     *self);
} DeeModelIface;


DeeModel

typedef struct _DeeModel DeeModel;


DeeModelIter

typedef struct _DeeModelIter DeeModelIter;

The DeeModelIter structure is private and should only be used with the provided DeeModel API. It is owned by DeeModel and should not be freed.


dee_model_check_type ()

gboolean            dee_model_check_type                (GType type);

Check if a given type is allowed as a storage type in a DeeModel. The allowed column types for DeeModels are:

G_TYPE_BOOLEAN, G_TYPE_UCHAR, G_TYPE_INT, G_TYPE_UINT, G_TYPE_INT64, G_TYPE_UINT64, G_TYPE_DOUBLE, G_TYPE_STRING

type :

The GType to check

Returns :

TRUE if and only if type can be stored in a DeeModel

dee_model_get_type_for_signature ()

GType               dee_model_get_type_for_signature    (gchar chr);

Find the corresponding GType gievn a DBus type signature. The type mapping is as follows:

b G_TYPE_BOOLEAN, y G_TYPE_UCHAR, i G_TYPE_INT, u G_TYPE_UINT, x G_TYPE_INT64, t G_TYPE_UINT64, d G_TYPE_DOUBLE, s G_TYPE_STRING

chr :

Character signature to find corresponding GType for

Returns :

The Gtype for chr or G_TYPE_NONE in case the type of chr is not known

dee_model_build_col_spec ()

gchar*              dee_model_build_col_spec            (DeeModel *self);

Returns :

A newly allocated string containing the column specification encoded as a DBus type signature. Free with g_free().

dee_model_set_column_type ()

void                dee_model_set_column_type           (DeeModel *self,
                                                         guint column,
                                                         GType type);

dee_model_set_n_columns ()

void                dee_model_set_n_columns             (DeeModel *self,
                                                         guint n_columns);

dee_model_get_n_columns ()

guint               dee_model_get_n_columns             (DeeModel *self);

Gets the number of columns in self

self :

a DeeModel

Returns :

the number of columns per row in self

dee_model_get_n_rows ()

guint               dee_model_get_n_rows                (DeeModel *self);

Gets the number of rows in self

self :

a DeeModel

Returns :

the number of rows in self

dee_model_get_column_type ()

GType               dee_model_get_column_type           (DeeModel *self,
                                                         guint column);

Get the GType of column

self :

a DeeModel

column :

the column to get retrieve the type of

Returns :

the GType that column holds

dee_model_clear ()

void                dee_model_clear                     (DeeModel *self);

Removes all rows in the model. Signals are emitted for each row in the model

self :

a DeeModel object to clear

dee_model_append ()

DeeModelIter*       dee_model_append                    (DeeModel *self,
                                                         ...);

Creates and appends a new row to the end of a DeeModel, setting the row values upon creation.

For example, to append a new row where column 0 is G_TYPE_INT and column 1 is G_TYPE_STRING:

 DeeModel *model;
 model = dee_model_new ("org.myapp.Results", 2, G_TYPE_INT, G_TYPE_STRING);
 dee_model_append (model, 0, 10, 1, "Rooney", -1);

self :

a DeeModel

... :

pairs of column number and value, terminated with -1

Returns :


dee_model_append_valist ()

DeeModelIter*       dee_model_append_valist             (DeeModel *self,
                                                         va_list args);

self :

args :

Returns :


dee_model_prepend ()

DeeModelIter*       dee_model_prepend                   (DeeModel *self,
                                                         ...);

Creates and prepends a new row to the beginning of a DeeModel, setting the row values upon creation.

For example, to prepend a new row where column 0 is G_TYPE_INT and column 1 is G_TYPE_STRING:

 DeeModel *model;
 model = dee_model_new ("org.myapp.Results", 2, G_TYPE_INT, G_TYPE_STRING);
 dee_model_prepend (model, 0, 10, 1, "Rooney", -1);

self :

a DeeModel

... :

pairs of column number and value, terminated with -1

Returns :


dee_model_prepend_valist ()

DeeModelIter*       dee_model_prepend_valist            (DeeModel *self,
                                                         va_list args);

self :

args :

Returns :


dee_model_insert ()

DeeModelIter*       dee_model_insert                    (DeeModel *self,
                                                         gint pos,
                                                         ...);

Creates and inserts a new row into a DeeModel, pushing the existing rows down.

For example, to insert a new row at position 27 where column 0 is G_TYPE_INT and column 1 is G_TYPE_STRING:

 dee_model_insert (model, 27, 0, 10, 1, "Rooney", -1);

self :

a DeeModel

pos :

The index to insert the row on. The existing row will be pushed down

... :

pairs of column number and value, terminated with -1

Returns :


dee_model_insert_valist ()

DeeModelIter*       dee_model_insert_valist             (DeeModel *self,
                                                         gint pos,
                                                         va_list args);

As dee_model_insert(), but intended for language bindings.

self :

a DeeModel

pos :

The index to insert the row on. The existing row will be pushed down.

args :

pairs of column number and value, terminated with -1

Returns :


dee_model_insert_before ()

DeeModelIter*       dee_model_insert_before             (DeeModel *self,
                                                         DeeModelIter *iter,
                                                         ...);

Creates and inserts a new row into a DeeModel just before the row pointed to by iter.

For example, to insert a new row where column 0 is G_TYPE_INT and column 1 is G_TYPE_STRING:

 DeeModelIter *iter = find_my_special_row (model);
 dee_model_insert_before (model, iter, 0, 10, 1, "Rooney", -1);

self :

a DeeModel

iter :

An iter pointing to the row before which to insert the new one

... :

pairs of column number and value, terminated with -1

Returns :


dee_model_insert_before_valist ()

DeeModelIter*       dee_model_insert_before_valist      (DeeModel *self,
                                                         DeeModelIter *iter,
                                                         va_list args);

As dee_model_insert_before(), but intended for language bindings.

self :

a DeeModel

iter :

An iter pointing to the row before which to insert the new one

args :

Returns :


dee_model_remove ()

void                dee_model_remove                    (DeeModel *self,
                                                         DeeModelIter *iter);

Removes the row at the given position from the model.

self :

a DeeModel

iter :


dee_model_set ()

void                dee_model_set                       (DeeModel *self,
                                                         DeeModelIter *iter,
                                                         ...);

Sets the value of one or more cells in the row references by iter. The variable argument list should contain integer column numbers, each column number followed by the value to be set. The list is terminated by a -1.

For example, to set column 0 with type G_TYPE_STRING, use:

  dee_model_set (model, iter, 0, "foo", -1);

self :

a DeeModel

iter :

a DeeModelIter

... :

a list of column/value pairs, terminated by -1

dee_model_set_valist ()

void                dee_model_set_valist                (DeeModel *self,
                                                         DeeModelIter *iter,
                                                         va_list args);

See #dee_model_set(). This version takes a va_list for language bindings.

self :

a DeeModel

iter :

a DeeModelIter

args :

a list of column/value location pairs, terminated by -1

dee_model_set_value ()

void                dee_model_set_value                 (DeeModel *self,
                                                         DeeModelIter *iter,
                                                         guint column,
                                                         const GValue *value);

Sets the data in column for the row iter points to, to value. The type of value must be convertable to the type of the column.

When this method call completes the model will emit ::row-changed. You can edit the model in place without triggering the change signals by calling dee_model_set_value_silently().

self :

a DeeModel

iter :

a DeeModelIter

column :

column number to set the value

value :

new value for cell

dee_model_set_value_silently ()

void                dee_model_set_value_silently        (DeeModel *self,
                                                         DeeModelIter *iter,
                                                         guint column,
                                                         const GValue *value);

Sets the data in column for the row iter points to, to value. The type of value must be convertable to the type of the column.

Calling this method will <emphasise>not</emphasise> trigger a ::row-changed signal. Also, if self is a sub class of DeeVersionedModel the seqnum of the affected row will <emphasise>not</emphasise> be incremented.

self :

a DeeModel

iter :

a DeeModelIter

column :

column number to set the value

value :

new value for cell

dee_model_get ()

void                dee_model_get                       (DeeModel *self,
                                                         DeeModelIter *iter,
                                                         ...);

Gets the value of one or more cells in the row references by iter. The variable argument list should contain integer column numbers, each column number followed by a place to store the value being retrieved. The list is terminated by a -1.

For example, to get a value from column 0 with type G_TYPE_STRING use:

 dee_model_get (model, iter, 0, &place_string_here, -1);

where place_string_here is a gchar* to be filled with the string. If appropriate, the returned values have to be freed or unreferenced.

self :

a DeeModel

iter :

a DeeModelIter

... :

a list of column/return location pairs, terminated by -1

dee_model_get_valist ()

void                dee_model_get_valist                (DeeModel *self,
                                                         DeeModelIter *iter,
                                                         va_list args);

See #dee_model_get(). This version takes a va_list for language bindings.

self :

a DeeModel

iter :

a DeeModelIter

args :

a list of column/return location pairs, terminated by -1

dee_model_get_value ()

void                dee_model_get_value                 (DeeModel *self,
                                                         DeeModelIter *iter,
                                                         guint column,
                                                         GValue *value);

Sets an intializes value to that at column. When done with value g_value_unset() needs to be called to free any allocated memory.

self :

a DeeModel

iter :

a DeeModelIter

column :

column number to retrieve the value from

value :

an empty GValue to set

dee_model_get_first_iter ()

DeeModelIter *      dee_model_get_first_iter            (DeeModel *self);

Retrieves a DeeModelIter representing the first row in self.

self :

a DeeModel

Returns :

A DeeModelIter (owned by self, do not free it). [transfer none]

dee_model_get_last_iter ()

DeeModelIter *      dee_model_get_last_iter             (DeeModel *self);

Retrieves a DeeModelIter representing the last row in self.

self :

a DeeModel

Returns :

A DeeModelIter (owned by self, do not free it). [transfer none]

dee_model_get_iter_at_row ()

DeeModelIter *      dee_model_get_iter_at_row           (DeeModel *self,
                                                         guint row);

Retrieves a DeeModelIter representing the row at the given index.

self :

a DeeModel

row :

position of the row to retrieve

Returns :

A new DeeModelIter, or NULL if row was out of bounds. The returned iter is owned by self, so do not free it. [transfer none]

dee_model_get_bool ()

gboolean            dee_model_get_bool                  (DeeModel *self,
                                                         DeeModelIter *iter,
                                                         guint column);

self :

a DeeModel

iter :

a DeeModelIter

column :

the column to retrieve a boolean from

Returns :

if iter and column are valid, the boolean stored at column. Otherwise FALSE

dee_model_get_uchar ()

guchar              dee_model_get_uchar                 (DeeModel *self,
                                                         DeeModelIter *iter,
                                                         guint column);

self :

a DeeModel

iter :

a DeeModelIter

column :

the column to retrieve a uchar from

Returns :

if iter and column are valid, the uchar stored at column. Otherwise 0.

dee_model_get_int ()

gint                dee_model_get_int                   (DeeModel *self,
                                                         DeeModelIter *iter,
                                                         guint column);

self :

a DeeModel

iter :

a DeeModelIter

column :

the column to retrieve a int from

Returns :

if iter and column are valid, the int stored at column. Otherwise 0.

dee_model_get_uint ()

guint               dee_model_get_uint                  (DeeModel *self,
                                                         DeeModelIter *iter,
                                                         guint column);

self :

a DeeModel

iter :

a DeeModelIter

column :

the column to retrieve a uint from

Returns :

if iter and column are valid, the uint stored at column. Otherwise 0.

dee_model_get_int64 ()

gint64              dee_model_get_int64                 (DeeModel *self,
                                                         DeeModelIter *iter,
                                                         guint column);

self :

a DeeModel

iter :

a DeeModelIter

column :

the column to retrieve a int64 from

Returns :

if iter and column are valid, the int64 stored at column. Otherwise 0.

dee_model_get_uint64 ()

guint64             dee_model_get_uint64                (DeeModel *self,
                                                         DeeModelIter *iter,
                                                         guint column);

self :

a DeeModel

iter :

a DeeModelIter

column :

the column to retrieve a uint64 from

Returns :

if iter and column are valid, the uint64 stored at column. Otherwise 0.

dee_model_get_double ()

gdouble             dee_model_get_double                (DeeModel *self,
                                                         DeeModelIter *iter,
                                                         guint column);

self :

a DeeModel

iter :

a DeeModelIter

column :

the column to retrieve a double from

Returns :

if iter and column are valid, the double stored at column. Otherwise 0.

dee_model_get_string ()

const gchar *       dee_model_get_string                (DeeModel *self,
                                                         DeeModelIter *iter,
                                                         guint column);

self :

a DeeModel

iter :

a DeeModelIter

column :

the column to retrieve a string from

Returns :

if iter and column are valid, the string stored at column. Otherwise NULL.

dee_model_next ()

DeeModelIter *      dee_model_next                      (DeeModel *self,
                                                         DeeModelIter *iter);

Returns a DeeModelIter that points to the next position in the model.

self :

a DeeModel

iter :

a DeeModelIter

Returns :

A DeeModelIter, pointing to the next row in the model. The iter is owned by self, do not free it. [transfer none]

dee_model_prev ()

DeeModelIter *      dee_model_prev                      (DeeModel *self,
                                                         DeeModelIter *iter);

Returns a DeeModelIter that points to the previous position in the model.

self :

a DeeModel

iter :

a DeeModelIter

Returns :

A DeeModelIter, pointing to the previous row in the model. The iter is owned by self, do not free it. [transfer none]

dee_model_is_first ()

gboolean            dee_model_is_first                  (DeeModel *self,
                                                         DeeModelIter *iter);

Where iter is at the start of self.

self :

a DeeModel

iter :

a DeeModelIter

Returns :

TRUE if iter is the first iter in the model

dee_model_is_last ()

gboolean            dee_model_is_last                   (DeeModel *self,
                                                         DeeModelIter *iter);

Whether iter is at the end of self.

self :

a DeeModel

iter :

a DeeModelIter

Returns :

TRUE if iter is the last iter in the model

dee_model_get_position ()

gint                dee_model_get_position              (DeeModel *self,
                                                         DeeModelIter *iter);

Returns :

The integer offset of iter in self

dee_model_freeze_signals ()

void                dee_model_freeze_signals            (DeeModel *self);

Increase the freeze count of self by one. When the freeze count of a model is greater than 0 it will not emit any of the signals ::row-added or ::row-changed, but simply queue them up. Once the freeze count hits zero (by calling dee_model_thaw_signals()) all signals will be played back in the order they where originally triggered.

Note that the ::row-removed signal will be emitted disregarding the freeze count. It has to be this way because otherwise the row iter would be invalid once the signal was emitted.

self :

The model for which to freeze the change notification signals

dee_model_thaw_signals ()

void                dee_model_thaw_signals              (DeeModel *self);

Decrease the freeze count of self by one. When the freeze count of a model is greater than 0 it will not emit any of the signals ::row-added or ::row-changed, but simply queue them up. Once the freeze count hits zero (by calling this method) all signals will be played back in the order they where originally triggered.

Note that the ::row-removed signal will be emitted disregarding the freeze count. It has to be this way because otherwise the row iter would be invalid once the signal was emitted.

self :

The model for which to freeze the

Signal Details

The "row-added" signal

void                user_function                      (DeeModel *self,
                                                        gpointer  iter,
                                                        gpointer  user_data)      : Run Last

Connect to this signal to be notified when a row is added to self.

self :

the DeeModel on which the signal is emitted

iter :

a DeeModelIter pointing to the newly added row

user_data :

user data set when the signal handler was connected.

The "row-changed" signal

void                user_function                      (DeeModel *self,
                                                        gpointer  iter,
                                                        gpointer  user_data)      : Run Last

Connect to this signal to be notified when a row is changed.

self :

the DeeModel on which the signal is emitted

iter :

a DeeModelIter pointing to the changed row

user_data :

user data set when the signal handler was connected.

The "row-removed" signal

void                user_function                      (DeeModel *self,
                                                        gpointer  iter,
                                                        gpointer  user_data)      : Run Last

Connect to this signal to be notified when a row is removed from self. The row is still valid while the signal is being emitted.

self :

the DeeModel on which the signal is emitted

iter :

a DeeModelIter pointing to the removed row

user_data :

user data set when the signal handler was connected.