DeeModel

DeeModel — A generic table model interface

Functions

gint (*DeeCompareRowFunc) ()
gint (*DeeCompareRowSizedFunc) ()
void dee_model_set_schema ()
void dee_model_set_schema_full ()
const gchar * const* dee_model_get_schema ()
const gchar * dee_model_get_column_schema ()
const gchar * dee_model_get_field_schema ()
gint dee_model_get_column_index ()
void dee_model_set_column_names ()
void dee_model_set_column_names_full ()
const gchar ** dee_model_get_column_names ()
void dee_model_register_vardict_schema ()
GHashTable * dee_model_get_vardict_schema ()
guint dee_model_get_n_columns ()
guint dee_model_get_n_rows ()
DeeModelIter * dee_model_append ()
DeeModelIter * dee_model_append_row ()
DeeModelIter * dee_model_prepend ()
DeeModelIter * dee_model_prepend_row ()
DeeModelIter * dee_model_insert ()
DeeModelIter * dee_model_insert_row ()
DeeModelIter * dee_model_insert_before ()
DeeModelIter * dee_model_insert_row_before ()
DeeModelIter * dee_model_insert_row_sorted ()
DeeModelIter * dee_model_insert_row_sorted_with_sizes ()
DeeModelIter * dee_model_insert_sorted ()
DeeModelIter * dee_model_find_row_sorted ()
DeeModelIter * dee_model_find_row_sorted_with_sizes ()
DeeModelIter * dee_model_find_sorted ()
void dee_model_remove ()
void dee_model_clear ()
void dee_model_set ()
void dee_model_set_value ()
void dee_model_set_row ()
void dee_model_get ()
GVariant ** dee_model_get_row ()
GVariant * dee_model_get_value ()
GVariant * dee_model_get_value_by_name ()
DeeModelIter * dee_model_get_first_iter ()
DeeModelIter * dee_model_get_last_iter ()
DeeModelIter * dee_model_get_iter_at_row ()
gboolean dee_model_get_bool ()
guchar dee_model_get_uchar ()
gint32 dee_model_get_int32 ()
guint32 dee_model_get_uint32 ()
gint64 dee_model_get_int64 ()
guint64 dee_model_get_uint64 ()
gdouble dee_model_get_double ()
const gchar * dee_model_get_string ()
DeeModelIter * dee_model_next ()
DeeModelIter * dee_model_prev ()
gboolean dee_model_is_first ()
gboolean dee_model_is_last ()
guint dee_model_get_position ()
DeeModelTag * dee_model_register_tag ()
gpointer dee_model_get_tag ()
void dee_model_set_tag ()
void dee_model_clear_tag ()
void dee_model_begin_changeset ()
void dee_model_end_changeset ()
GVariant ** dee_model_build_row ()
GVariant ** dee_model_build_named_row ()
GVariant ** dee_model_build_named_row_valist ()
GVariant ** dee_model_build_named_row_sunk ()

Signals

Types and Values

Object Hierarchy

    GBoxed
    ╰── DeeModelIter
    GInterface
    ╰── DeeModel

Includes

#include <dee.h>

Description

DeeModel is a generic table model that can holds GVariants as column values. Each column is restricted to hold variants with some predefined type signature. This is known as the column schema.

Indexes - Access by Key or Full Text Analysis

Instead of forcing you to search the rows and columns for given values or patterns DeeModel is integrated with a powerful DeeIndex that allows you to create custom indexes over the model content that are updated automatically as the model changes.

Indexes can be created for integer keys, string keys (fx. URIs), or for full text search into the model contents. The indexing API is flexible and extensible and can provide huge optimizations in terms of access times if you find yourself iterating over the model searching for something.


Sorting

As a simpler alternative to using indexes you can rely on sorted models. This is done by using the dee_model_insert_sorted() and dee_model_find_sorted() family of APIs. Some model classes have accelerated implementations of sorted inserts and lookups. Notably DeeSequenceModel.


Tags - Attach Arbitrary Data to Rows

It's a very common pattern that you want to render a DeeModel into some view in a classinc MVC pattern. If the view needs to reflect changes in the model dynamically you often find yourself creating ad-hoc mappings between the rows of the model and the widgets in your view.

In situations where you need to pair the rows in a model with some external data structure the tags API may come in handy. It consists of the functions dee_model_register_tag(), dee_model_set_tag(), dee_model_get_tag(), and dee_model_clear_tag().

Functions

DeeCompareRowFunc ()

gint
(*DeeCompareRowFunc) (GVariant **row1,
                      GVariant **row2,
                      gpointer user_data);

Compares row1 and row2 . Mainly used with dee_model_insert_sorted() and dee_model_find_sorted().

Parameters

row1

The model being indexed.

[array]

row2

The row to extract terms for.

[array]

user_data

User data to pass to comparison function.

[closure]

Returns

-1, 0, or 1 if row1 is respectively less than, equal, or greater than row2 .


DeeCompareRowSizedFunc ()

gint
(*DeeCompareRowSizedFunc) (GVariant **row1,
                           guint row1_length,
                           GVariant **row2,
                           guint row2_length,
                           gpointer user_data);

Compares row1 and row2 . Mainly used with dee_model_insert_row_sorted_with_sizes() and dee_model_find_row_sorted_with_sizes().

Parameters

row1

Row data.

[array length=row1_length]

row1_length

The number of elements in row1 array

 

row2

Row data to compare with.

[array length=row2_length]

row2_length

The number of elements in row2 array

 

user_data

User data passed to comparison function.

[closure]

Returns

-1, 0, or 1 if row1 is respectively less than, equal, or greater than row2 .


dee_model_set_schema ()

void
dee_model_set_schema (DeeModel *self,
                      ...);

Set the GVariant types and the number of columns used by self . This method must be called exactly once before using self . Note that some constructors will do this for you.

To create a model with three columns; a 32 bit integer, a string, and lastly an array of strings, you would do:

 DeeModel *model;
 model = dee_sequence_model_new ();
 dee_model_set_schema (model, "i", "s", "as", NULL);

Parameters

self

The DeeModel to set the column layout for

 

VarArgs

A list of GVariant type strings terminated by a NULL

 

dee_model_set_schema_full ()

void
dee_model_set_schema_full (DeeModel *self,
                           const gchar * const *column_schemas,
                           guint num_columns);

Set the GVariant types and the number of columns used by self . This method must be called exactly once before using self . Note that some constructors will do this for you.

Parameters

self

The DeeModel to set the column layout for

 

column_schemas

A list of GVariant type strings terminated by a NULL.

[array length=num_columns zero-terminated=1][element-type utf8][transfer none]

num_columns

an integer specifying the array length for VarArgs

 

dee_model_get_schema ()

const gchar * const*
dee_model_get_schema (DeeModel *self,
                      guint *num_columns);

Get a NULL-terminated array of GVariant type strings that defines the required formats for the columns of self .

Parameters

self

The DeeModel to get the the schema for

 

num_columns

Address of an integer in which to store the number of columns in self . Or NULL to ignore the array length.

[out][allow-none]

Returns

A NULL-terminated array of GVariant type strings. The length of the returned array is written to num_columns . The returned array should not be freed or modified. It is owned by the model.

[array length=num_columns][element-type utf8][transfer none]


dee_model_get_column_schema ()

const gchar *
dee_model_get_column_schema (DeeModel *self,
                             guint column);

Get the GVariant signature of a column

Parameters

self

a DeeModel

 

column

the column to get retrieve the GVariant type string of

 

Returns

the GVariant signature of the column at index column


dee_model_get_field_schema ()

const gchar *
dee_model_get_field_schema (DeeModel *self,
                            const gchar *field_name,
                            guint *out_column);

Get the GVariant signature of field previously registered with dee_model_register_vardict_schema().

Parameters

self

a DeeModel

 

field_name

name of vardict field to get schema of

 

out_column

column index of the associated vardict.

[out]

Returns

the GVariant signature for the field, or NULL if given field wasn't registered with dee_model_register_vardict_schema().


dee_model_get_column_index ()

gint
dee_model_get_column_index (DeeModel *self,
                            const gchar *column_name);

Get the column index of a column.

Parameters

self

a DeeModel

 

column_name

the column name to retrieve the index of

 

Returns

0-based index of the column or -1 if column with this name wasn't found


dee_model_set_column_names ()

void
dee_model_set_column_names (DeeModel *self,
                            const gchar *first_column_name,
                            ...);

dee_model_set_column_names_full ()

void
dee_model_set_column_names_full (DeeModel *self,
                                 const gchar **column_names,
                                 guint num_columns);

Set column names used by self . This method must be called exactly once, but only after setting a schema of the model. Note that some constructors will do this for you.

Parameters

self

A DeeModel.

 

column_names

A list of column names terminated by a NULL.

[array length=num_columns zero-terminated=1][element-type utf8][transfer none]

num_columns

an integer specifying the array length for annotations

 

dee_model_get_column_names ()

const gchar **
dee_model_get_column_names (DeeModel *self,
                            guint *num_columns);

Get a NULL-terminated array of column names for the columns of self . These names can be used in calls to dee_model_build_named_row().

Parameters

self

The DeeModel to get the the schema for

 

num_columns

Address of an integer in which to store the number of columns in self . Or NULL to ignore the array length.

[out][allow-none]

Returns

A NULL-terminated array of GVariant type strings. The length of the returned array is written to num_columns . The returned array should not be freed or modified. It is owned by the model.

[array length=num_columns][element-type utf8][transfer none]


dee_model_register_vardict_schema ()

void
dee_model_register_vardict_schema (DeeModel *self,
                                   guint column,
                                   GHashTable *schemas);

Register schema for fields in a model containing column with variant dictionary schema ('a{sv}'). The keys registered with this function can be later used with dee_model_build_named_row() function, as well as dee_model_get_value_by_name(). Note that it is possible to register the same field name for multiple columns, in which case you need to use fully-qualified "column_name::field" name in the calls to dee_model_build_named_row() and dee_model_get_field_schema().

Parameters

self

a DeeModel

 

column

the column index to register the schemas with

 

schemas

hashtable with keys specifying names of the fields and values defining their schema.

[element-type utf8 utf8]

dee_model_get_vardict_schema ()

GHashTable *
dee_model_get_vardict_schema (DeeModel *self,
                              guint column);

Get a schema for variant dictionary column previously registered using dee_model_register_vardict_schema().

Parameters

self

a DeeModel

 

column

the column index to get the schemas for

 

Returns

Hashtable containing a mapping from field names to schemas or NULL. Note that keys and values in the hashtable may be owned by the model, so you need to create a deep copy if you intend to keep the hashtable around.

[transfer container][element-type utf8 utf8]


dee_model_get_n_columns ()

guint
dee_model_get_n_columns (DeeModel *self);

Gets the number of columns in self

Parameters

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

Parameters

self

a DeeModel

 

Returns

the number of rows in self


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 and example see dee_model_insert_before().

Parameters

self

a DeeModel

 

VarArgs

A list of values matching the column schemas of self . Any basic variant type is passed as the standard C type while any other type must be boxed in a GVariant. Any floating references will be consumed. A NULL value for a string type column will be converted to the empty string.

 

Returns

A DeeModelIter pointing to the new row.

[transfer none][type Dee.ModelIter]


dee_model_append_row ()

DeeModelIter *
dee_model_append_row (DeeModel *self,
                      GVariant **row_members);

Like dee_model_append() but intended for language bindings or situations where you work with models on a meta level and may not have a prior knowledge of the column schemas of the models. See also dee_model_build_row().

Parameters

self

The model to prepend a row to

 

row_members

An array of GVariants with type signature matching those of the column schemas of self . If any of the variants have floating references they will be consumed.

[array zero-terminated=1]

Returns

A DeeModelIter pointing to the new row.

[transfer none][type Dee.ModelIter]


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.

Example:

 DeeModel *model;
 model = ...
 dee_model_set_schema (model, "i", "s", NULL);
 dee_model_prepend (model, 10, "Rooney");

Parameters

self

a DeeModel

 

VarArgs

A list of values matching the column schemas of self . Any basic variant type is passed as the standard C type while any other type must be boxed in a GVariant. Any floating references will be consumed. A NULL value for a string type column will be converted to the empty string.

 

Returns

A DeeModelIter pointing to the new row.

[transfer none][type Dee.ModelIter]


dee_model_prepend_row ()

DeeModelIter *
dee_model_prepend_row (DeeModel *self,
                       GVariant **row_members);

Like dee_model_prepend() but intended for language bindings or situations where you work with models on a meta level and may not have a priori knowledge of the column schemas of the models. See also dee_model_build_row().

Parameters

self

The model to prepend a row to

 

row_members

An array of GVariants with type signature matching those of the column schemas of self . If any of the variants have floating references they will be consumed.

[array zero-terminated=1]

Returns

A DeeModelIter pointing to the new row.

[transfer none][type Dee.ModelIter]


dee_model_insert ()

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

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

For and example see dee_model_insert_before().

Parameters

self

a DeeModel

 

pos

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

 

VarArgs

A list of values matching the column schemas of self . Any basic variant type is passed as the standard C type while any other type must be boxed in a GVariant. Any floating references will be consumed. A NULL value for a string type column will be converted to the empty string.

 

Returns

A DeeModelIter pointing to the new row.

[transfer none][type Dee.ModelIter]


dee_model_insert_row ()

DeeModelIter *
dee_model_insert_row (DeeModel *self,
                      guint pos,
                      GVariant **row_members);

As dee_model_insert(), but intended for language bindings or situations where you work with models on a meta level and may not have a priori knowledge of the column schemas of the models. See also dee_model_build_row().

Parameters

self

a DeeModel

 

pos

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

 

row_members

An array of GVariants with type signature matching those of the column schemas of self . If any of the variants have floating references they will be consumed.

[array zero-terminated=1]

Returns

A DeeModelIter pointing to the new row.

[transfer none][type Dee.ModelIter]


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 in a model with schema ("u", "s", "as") you would do:

 DeeModelIter    *iter;
 GVariantBuilder  b;

 g_variant_builder_init (&b, "as");
 g_variant_builder_add (&b, "s", "Hello");
 g_variant_builder_add (&b, "s", "World");

 iter = find_my_special_row (model);
 dee_model_insert_before (model, iter,
                          27,
                          "Howdy",
                          g_variant_builder_end (&b));

Parameters

self

a DeeModel

 

iter

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

 

VarArgs

A list of values matching the column schemas of self . Any basic variant type is passed as the standard C type while any other type must be boxed in a GVariant. Any floating references will be consumed. A NULL value for a string type column will be converted to the empty string.

 

Returns

A DeeModelIter pointing to the new row.

[transfer none][type Dee.ModelIter]


dee_model_insert_row_before ()

DeeModelIter *
dee_model_insert_row_before (DeeModel *self,
                             DeeModelIter *iter,
                             GVariant **row_members);

As dee_model_insert_before(), but intended for language bindings or situations where you work with models on a meta level and may not have a priori knowledge of the column schemas of the models. See also dee_model_build_row().

Parameters

self

a DeeModel

 

iter

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

 

row_members

An array of GVariants with type signature matching those of the column schemas of self . If any of the variants have floating references they will be consumed.

[array zero-terminated=1]

Returns

A DeeModelIter pointing to the new row.

[transfer none][type Dee.ModelIter]


dee_model_insert_row_sorted ()

DeeModelIter *
dee_model_insert_row_sorted (DeeModel *self,
                             GVariant **row_members,
                             DeeCompareRowFunc cmp_func,
                             gpointer user_data);

Inserts a row in self according to the sorting specified by cmp_func . If you use this method for insertion you should not use other methods as this method assumes the model to be already sorted by cmp_func .

Parameters

self

The model to do a sorted insert on

 

row_members

An array of GVariants with type signature matching those of the column schemas of self . If any of the variants have floating references they will be consumed.

[array zero-terminated=1]

cmp_func

Callback used for comparison or rows.

[scope call]

user_data

Arbitrary pointer passed to cmp_func during search.

[closure]

Returns

A DeeModelIter pointing to the new row.

[transfer none][type Dee.ModelIter]


dee_model_insert_row_sorted_with_sizes ()

DeeModelIter *
dee_model_insert_row_sorted_with_sizes
                               (DeeModel *self,
                                GVariant **row_members,
                                DeeCompareRowSizedFunc cmp_func,
                                gpointer user_data);

Inserts a row in self according to the sorting specified by cmp_func . If you use this method for insertion you should not use other methods as this method assumes the model to be already sorted by cmp_func .

Parameters

self

The model to do a sorted insert on

 

row_members

An array of GVariants with type signature matching those of the column schemas of self . If any of the variants have floating references they will be consumed.

[array zero-terminated=1]

cmp_func

Callback used for comparison or rows.

[scope call]

user_data

Arbitrary pointer passed to cmp_func during search.

[closure]

Returns

A DeeModelIter pointing to the new row.

[transfer none][type Dee.ModelIter]


dee_model_insert_sorted ()

DeeModelIter *
dee_model_insert_sorted (DeeModel *self,
                         DeeCompareRowFunc cmp_func,
                         gpointer user_data,
                         ...);

Convenience function for calling dee_model_insert_row_sorted(). Inserts a row in self according to the sorting specified by cmp_func . If you use this method for insertion you should not use other methods as this method assumes the model to be already sorted by cmp_func .

Parameters

self

The model to do a sorted insert on

 

cmp_func

Callback used for comparison or rows.

[scope call]

user_data

Arbitrary pointer passed to cmp_func during search.

[closure]

VarArgs

Specifies the row to insert. A collection of GVariants matching the number of columns self

 

Returns

A DeeModelIter pointing to the new row.

[transfer none][type Dee.ModelIter]


dee_model_find_row_sorted ()

DeeModelIter *
dee_model_find_row_sorted (DeeModel *self,
                           GVariant **row_spec,
                           DeeCompareRowFunc cmp_func,
                           gpointer user_data,
                           gboolean *out_was_found);

Finds a row in self according to the sorting specified by cmp_func . This method will assume that self is already sorted by cmp_func .

If you use this method for searching you should only use dee_model_insert_row_sorted() to insert rows in the model.

Parameters

self

The model to search

 

row_spec

An array of GVariants with type signature matching those of the column schemas of self . No references will be taken on the variants.

[array zero-terminated=1]

cmp_func

Callback used for comparison or rows.

[scope call]

user_data

Arbitrary pointer passed to cmp_func during search.

[closure]

out_was_found

A place to store a boolean value that will be set when this method returns. If TRUE then an exact match was found. If FALSE then the returned iter points to a row just after where row_spec would have been inserted. Pass NULL to ignore.

[out]

Returns

If out_was_found is set to TRUE then a DeeModelIter pointing to the last matching row. If it is FALSE then the iter pointing to the row just after where row_spec_would have been inserted.

[transfer none][type Dee.ModelIter]


dee_model_find_row_sorted_with_sizes ()

DeeModelIter *
dee_model_find_row_sorted_with_sizes (DeeModel *self,
                                      GVariant **row_spec,
                                      DeeCompareRowSizedFunc cmp_func,
                                      gpointer user_data,
                                      gboolean *out_was_found);

Like dee_model_find_row_sorted(), but uses DeeCompareRowSizedFunc and therefore doesn't cause trouble when used from introspected languages.

Finds a row in self according to the sorting specified by cmp_func . This method will assume that self is already sorted by cmp_func .

If you use this method for searching you should only use dee_model_insert_row_sorted() (or dee_model_insert_row_sorted_with_sizes()) to insert rows in the model.

Parameters

self

The model to search

 

row_spec

An array of GVariants with type signature matching those of the column schemas of self . No references will be taken on the variants.

[array zero-terminated=1]

cmp_func

Callback used for comparison or rows.

[scope call]

user_data

Arbitrary pointer passed to cmp_func during search.

[closure]

out_was_found

A place to store a boolean value that will be set when this method returns. If TRUE then an exact match was found. If FALSE then the returned iter points to a row just after where row_spec would have been inserted. Pass NULL to ignore.

[out]

Returns

If out_was_found is set to TRUE then a DeeModelIter pointing to the last matching row. If it is FALSE then the iter pointing to the row just after where row_spec_would have been inserted.

[transfer none][type Dee.ModelIter]


dee_model_find_sorted ()

DeeModelIter *
dee_model_find_sorted (DeeModel *self,
                       DeeCompareRowFunc cmp_func,
                       gpointer user_data,
                       gboolean *out_was_found,
                       ...);

Finds a row in self according to the sorting specified by cmp_func . This method will assume that self is already sorted by cmp_func .

If you use this method for searching you should only use dee_model_insert_row_sorted() to insert rows in the model.

Parameters

self

The model to search

 

cmp_func

Callback used for comparison or rows.

[scope call]

user_data

Arbitrary pointer passed to cmp_func during search.

[closure]

out_was_found

A place to store a boolean value that will be set when this method returns. If TRUE then an exact match was found. If FALSE then the returned iter points to a row just after where row_spec would have been inserted. Pass NULL to ignore.

[out]

VarArgs

A sequence of variables with type signature matching those of the column schemas of self .

 

Returns

If out_was_found is set to TRUE then a DeeModelIter pointing to the last matching row. If it is FALSE then the iter pointing to the row just after where row_spec_would have been inserted.

[transfer none][type Dee.ModelIter]


dee_model_remove ()

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

Removes the row at the given position from the model.

Parameters

self

a DeeModel

 

iter

a DeeModelIter pointing to the row to remove

 

dee_model_clear ()

void
dee_model_clear (DeeModel *self);

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

Parameters

self

a DeeModel object to clear

 

dee_model_set ()

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

Sets all values across the entire row referenced by iter . The variable argument list should contain values that match the column schemas for the model. All basic variant type (see g_variant_type_is_basic()) are passed in as their raw C type while all other types are passed in boxed in a GVariant. Any floating references on variants passed to this method are consumed.

For example, to set the values for a row on model with the schema ("u", "s", "as"):

  GVariantBuilder b;

  g_variant_builder_init (&b, "as");
  g_variant_builder_add (&b, "Hello");
  g_variant_builder_add (&b, "World");

  dee_model_set (model, iter, 27, "foo", g_variant_builder_end (&b));

Parameters

self

a DeeModel

 

iter

a DeeModelIter

 

VarArgs

A list of values to set matching the column schemas. Any basic variant type is passed as the standard C type while any other type must be boxed in a GVariant. Any floating references will be consumed. A NULL value for a string type column will be converted to the empty string.

 

dee_model_set_value ()

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

Sets the data in column for the row iter points to, to value . The type of value must be convertible 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().

Parameters

self

a DeeModel

 

iter

a DeeModelIter

 

column

column number to set the value

 

value

New value for cell. If value is a floating reference the model will assume ownership of the variant

 

dee_model_set_row ()

void
dee_model_set_row (DeeModel *self,
                   DeeModelIter *iter,
                   GVariant **row_members);

Sets all columns in the row iter points to, to those found in row_members . The variants in row_members must match the types defined in the model's schema.

Parameters

self

a DeeModel

 

iter

a DeeModelIter

 

row_members

And array of GVariants with type signature matching those from the model schema. If any of the variants have floating references these will be consumed.

[array]

dee_model_get ()

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

Gets all the values across the entire row referenced by iter . The variable argument list should contain pointers to variables that match the column schemas of this model.

For all basic variant types (see g_variant_type_is_basic()) this method expects pointers to their native C types while for all other types it expects a pointer to a pointer to a GVariant.

For string values you are passed a constant reference which is owned by the model, but any returned variants must be freed with g_variant_unref().

For example, to get all values a model with signature ("u", "s", "as") you would do:

 guint32      u;
 const gchar *s;
 GVariant    *v;

 dee_model_get (model, iter, &u, &s, &v);

 // do stuff

 g_variant_unref (v);

Parameters

self

a DeeModel

 

iter

a DeeModelIter

 

VarArgs

a list of return locations matching the types defined in the column schemas. To ignore the data in a specific column pass a NULL on that position

 

dee_model_get_row ()

GVariant **
dee_model_get_row (DeeModel *self,
                   DeeModelIter *iter,
                   GVariant **out_row_members);

Parameters

self

A DeeModel to get a row from

 

iter

A DeeModelIter pointing to the row to get

 

out_row_members

An array of variants with a length bigger than or equal to the number of columns in self , or NULL. If you pass NULL here a new array will be allocated for you. The returned variants will have a non-floating reference.

[array][out][allow-none][default NULL]

Returns

out_row_members if it was not NULL or a newly allocated array otherwise which you must free with g_free(). The variants in the array will have a strong reference and needs to be freed with g_variant_unref().

[array zero-terminated=1]


dee_model_get_value ()

GVariant *
dee_model_get_value (DeeModel *self,
                     DeeModelIter *iter,
                     guint column);

Parameters

self

The DeeModel to inspect

 

iter

a DeeModelIter pointing to the row to inspect

 

column

column number to retrieve the value from

 

Returns

A, guaranteed non-floating, reference to a GVariant containing the row data. Free with g_variant_unref().

[transfer full]


dee_model_get_value_by_name ()

GVariant *
dee_model_get_value_by_name (DeeModel *self,
                             DeeModelIter *iter,
                             const gchar *column_name);

Parameters

self

The DeeModel to inspect

 

iter

a DeeModelIter pointing to the row to inspect

 

column

column name to retrieve the value from

 

Returns

A, guaranteed non-floating, reference to a GVariant containing the row data. Free with g_variant_unref().

[transfer full]


dee_model_get_first_iter ()

DeeModelIter *
dee_model_get_first_iter (DeeModel *self);

Retrieves a DeeModelIter representing the first row in self .

Parameters

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 pointing right after the last row in self . This is refered to also the the end iter.

As with other iters the end iter, in particular, is stable over inserts, changes, or removals.

Parameters

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.

Note that this method does not have any performance guarantees. In particular it is not guaranteed to be O(1).

Parameters

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

Parameters

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

Parameters

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_int32 ()

gint32
dee_model_get_int32 (DeeModel *self,
                     DeeModelIter *iter,
                     guint column);

Parameters

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_uint32 ()

guint32
dee_model_get_uint32 (DeeModel *self,
                      DeeModelIter *iter,
                      guint column);

Parameters

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

Parameters

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

Parameters

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

Parameters

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

Parameters

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.

Parameters

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.

Parameters

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

Checks if iter is the very first iter self .

Parameters

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 the end iter of self . Note that the end iter points right after the last valid row in self .

Parameters

self

a DeeModel

 

iter

a DeeModelIter

 

Returns

TRUE if iter is the last iter in the model


dee_model_get_position ()

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

Get the numeric offset of iter into self . Note that this method is not guaranteed to be O(1).

Parameters

self

The model to inspect

 

iter

The iter to get the position of

 

Returns

The integer offset of iter in self


dee_model_register_tag ()

DeeModelTag *
dee_model_register_tag (DeeModel *self,
                        GDestroyNotify tag_destroy);

Register a new tag on a DeeModel. A tag is an extra value attached to a given row on a model. The tags are invisible to all that doesn't have the tag handle returned by this method. DeeModel implementations must ensure that dee_model_get_tag() is an O(1) operation.

Tags can be very useful in associating some extra data to a row in a model and have that automatically synced when the model changes. If you're writing a tiled view for a model you might want to tag each row with the tile widget for that row. That way you have very convenient access to the tile widget given any row in the model.

The private nature of tags and the fact that you can store arbitrary pointers and binary data in them also means that they are not serialized if you utilize a model implementation that exposes the DeeSerializable interface.

Parameters

self

The model to register a tag on

 

tag_destroy

Function called when a tagged row is removed from the model. This function will also be called on all tagged rows when the model is finalized.

 

Returns

A DeeModelTag handle that you can use to set and get tags with.

[transfer none][type Dee.ModelTag]


dee_model_get_tag ()

gpointer
dee_model_get_tag (DeeModel *self,
                   DeeModelIter *iter,
                   DeeModelTag *tag);

Look up a tag value for a given row in a model. This method is guaranteed to be O(1).

Parameters

self

The model to get a tag from

 

iter

A DeeModelIter pointing to the row to get the tag from

 

tag

The tag handle to retrieve the tag value for

 

Returns

Returns NULL if tag is unset otherwise the value of the tag as it was set with dee_model_set_tag().

[transfer none]


dee_model_set_tag ()

void
dee_model_set_tag (DeeModel *self,
                   DeeModelIter *iter,
                   DeeModelTag *tag,
                   gpointer value);

Set a tag on a row in a model. This function is guaranteed to be O(1). See also dee_model_register_tag().

If tag is already set on this row the existing tag value will be destroyed with the GDestroyNotify passed to the dee_model_register_tag().

Parameters

self

The model to set a tag on

 

iter

The row to set the tag on

 

tag

The tag handle for the tag as obtained from dee_model_register_tag()

 

value

The value to set for tag . Note that NULL represents an unset tag

 

dee_model_clear_tag ()

void
dee_model_clear_tag (DeeModel *self,
                     DeeModelIter *iter,
                     DeeModelTag *tag);

This method is purely syntactic sugar for calling dee_model_set_tag() with a value of NULL. It's included in order to help developers write more readable code.

Parameters

self

The model to clear a tag on

 

iter

The row to clear the tag from

 

tag

The tag to clear from iter

 

dee_model_begin_changeset ()

void
dee_model_begin_changeset (DeeModel *self);

Notify listeners that the model is about to be changed, which means that multiple row additions / changes / removals will follow. The default implementation of this method will emit the ::changeset-started signal.

It is not stricly necessary to enclose every change to a model in a dee_model_begin_changeset() and dee_model_end_changeset() calls, but doing so is highly recommended and allows implementing various optimizations.

The usual way to perform multiple changes to a model is as follows:

void update_model (DeeModel *model)
{
  GVariant **added_row_data1 = ...;
  GVariant **added_row_data2 = ...;

  dee_model_begin_changeset (model);

  dee_model_remove (model, dee_model_get_first_iter (model));
  dee_model_append_row (model, added_row_data1);
  dee_model_append_row (model, added_row_data2);

  dee_model_end_changeset (model);
}

Parameters

self

a DeeModel

 

dee_model_end_changeset ()

void
dee_model_end_changeset (DeeModel *self);

Notify listeners that all changes have been committed to the model. The default implementation of this method will emit the ::changeset-finished signal.

See also dee_model_begin_changeset().

Parameters

self

a DeeModel

 

dee_model_build_row ()

GVariant **
dee_model_build_row (DeeModel *self,
                     GVariant **out_row_members,
                     ...);

Build an array of GVariants with values from the variadic argument list according to the model schema for self . The caller must call g_variant_ref_sink() and g_variant_unref() on all the returned variants and g_free() the array itself if NULL was passed as out_row_members .

This is utility function and will not touch or modify self in any way.

Parameters

self

The model to create a row for

 

out_row_members

An array to write the values to or NULL to allocate a new array. If non-NULL it must have a length that is longer or equal to the number of columns in self

 

VarArgs

A list with values matching the column schemas of self . Basic variant types are passed directly while any other types must be boxed in a GVariant. It's important to note that any floating references on variants passed to this method will be not be consumed. A NULL value for a string type column will be converted to the empty string.

 

Returns

If out_row_members is NULL a newly allocated array of variants will be returned and the array must be freed with g_free(). If out_row_members is non-NULL it will be reused, and variants in the array may or may not have floating references, which means the caller must make sure that g_variant_ref_sink() and g_variant_unref() are called on them.


dee_model_build_named_row ()

GVariant **
dee_model_build_named_row (DeeModel *self,
                           GVariant **out_row_members,
                           const gchar *first_column_name,
                           ...);

Build an array of GVariants with values from the variadic argument list according to the column names and model schema for self . The caller must call g_variant_ref_sink() and g_variant_unref() on all the returned variants and g_free() the array itself if NULL was passed as out_row_members .

This is utility function and will not touch or modify self in any way.

For example, to append a row to model with signature ("s", "u", "s") and column names set to ("uri", "count", "description") you could do:

 GVariant    *row_buf[3];

 dee_model_append_row (model,
   dee_model_build_named_row (model, row_buf,
                              "uri", "http://example.org",
                              "count", 435,
                              "description", "Example.org site", NULL));

Parameters

self

The model to create a row for

 

out_row_members

An array to write the values to or NULL to allocate a new array. If non-NULL it must have a length that is longer or equal to the number of columns in self

 

first_column_name

A column name

 

VarArgs

Value for given column, followed by more name/value pairs, followed by NULL. The passed names have to match the column names (or field names registered with dee_model_register_vardict_schema()) and values have to be set according to schema of the given column or field. Basic variant types are passed directly while any other types must be boxed in a GVariant, similar to dee_model_build_row().

 

Returns

If out_row_members is NULL a newly allocated array of variants will be returned and the array must be freed with g_free(). If out_row_members is non-NULL it will be reused, and variants in the array may or may not have floating references, which means the caller must make sure that g_variant_ref_sink() and g_variant_unref() are called on them.


dee_model_build_named_row_valist ()

GVariant **
dee_model_build_named_row_valist (DeeModel *self,
                                  GVariant **out_row_members,
                                  const gchar *first_column_name,
                                  va_list *args);

dee_model_build_named_row_sunk ()

GVariant **
dee_model_build_named_row_sunk (DeeModel *self,
                                GVariant **out_row_members,
                                guint *out_array_length,
                                const gchar *first_column_name,
                                ...);

Version of dee_model_build_named_row() for language bindings - as opposed to dee_model_build_named_row(), the returned variants will be strong references, therefore you always have to call g_variant_unref() on the items and g_free() the array itself if NULL was passed as out_row_members .

If out_row_members is non-NULL, g_variant_unref() will be called on its elements (if also non-NULL), which allows easy reuse of the array memory in loops.

This is utility function and will not touch or modify self in any way.

Example of memory management for model with schema ("s", "i") and column names ("uri", "count"):

 GVariant    **row_buf;

 row_buf = dee_model_build_named_row_sunk (model, NULL, "uri", "file:///",
                                           "count", 0, NULL);
 dee_model_append_row (model, row_buf);

 for (int i = 1; i < 100; i++)
 {
   dee_model_append_row (model,
     dee_model_build_named_row_sunk (model, row_buf, "uri", "file:///",
                                     "count", i, NULL));
 }
 
 g_variant_unref (row_buf[0]);
 g_variant_unref (row_buf[1]);
 g_free (row_buf);

Parameters

self

The model to create a row for

 

out_row_members

An array to write the values to or NULL to allocate a new array. If non-NULL it must have a length that is longer or equal to the number of columns in self .

[array]

out_array_length

Length of the returned variant array.

[out]

first_column_name

A column name

 

VarArgs

Value for given column, followed by more name/value pairs, followed by NULL. The passed names have to match the column names and values have to be set according to schema of self . Basic variant types are passed directly while any other types must be boxed in a GVariant, similar to dee_model_build_row().

 

Returns

If out_row_members is NULL a newly allocated array of variants will be returned and the array must be freed with g_free(). If out_row_members is non-NULL it will be reused. Variants in the array will have strong references, which means the caller must make sure that g_variant_unref() is called on them.

[array length=out_array_length]

Types and Values

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.


DeeModelTag

typedef struct _DeeModelTag DeeModelTag;

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

Signal Details

The “changeset-finished” signal

void
user_function (DeeModel *self,
               gpointer  user_data)

Connect to this signal to be notified when a changeset that can contain multiple row additions / changes / removals has been committed to the model.

Parameters

self

the DeeModel on which the signal is emitted

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “changeset-started” signal

void
user_function (DeeModel *self,
               gpointer  user_data)

Connect to this signal to be notified when a changeset that can contain multiple row additions / changes / removals is about to be committed to the model. Note that not all model implementations use the changeset approach and you might still get a row change signal outside of changeset-started and changeset-finished signals. It also isn't guaranteed that a changeset would always be non-empty.

Parameters

self

the DeeModel on which the signal is emitted

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “row-added” signal

void
user_function (DeeModel     *self,
               DeeModelIter *iter,
               gpointer      user_data)

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

Parameters

self

the DeeModel on which the signal is emitted

 

iter

a DeeModelIter pointing to the newly added row.

[transfer none][type Dee.ModelIter]

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “row-changed” signal

void
user_function (DeeModel     *self,
               DeeModelIter *iter,
               gpointer      user_data)

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

Parameters

self

the DeeModel on which the signal is emitted

 

iter

a DeeModelIter pointing to the changed row.

[transfer none][type Dee.ModelIter]

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “row-removed” signal

void
user_function (DeeModel     *self,
               DeeModelIter *iter,
               gpointer      user_data)

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.

Parameters

self

the DeeModel on which the signal is emitted

 

iter

a DeeModelIter pointing to the removed row.

[transfer none][type Dee.ModelIter]

user_data

user data set when the signal handler was connected.

 

Flags: Run Last