GdaDataModel

GdaDataModel — Basic data model class

Synopsis




            GdaDataModel;
void        gda_data_model_freeze           (GdaDataModel *model);
void        gda_data_model_thaw             (GdaDataModel *model);
gint        gda_data_model_get_n_rows       (GdaDataModel *model);
gint        gda_data_model_get_n_columns    (GdaDataModel *model);
GdaColumn*  gda_data_model_describe_column  (GdaDataModel *model,
                                             gint col);
const gchar* gda_data_model_get_column_title
                                            (GdaDataModel *model,
                                             gint col);
void        gda_data_model_set_column_title (GdaDataModel *model,
                                             gint col,
                                             const gchar *title);
gint        gda_data_model_get_column_position
                                            (GdaDataModel *model,
                                             const gchar *title);
const GdaRow* gda_data_model_get_row        (GdaDataModel *model,
                                             gint row);
const GdaValue* gda_data_model_get_value_at (GdaDataModel *model,
                                             gint col,
                                             gint row);
gboolean    gda_data_model_is_updatable     (GdaDataModel *model);
const GdaRow* gda_data_model_append_values  (GdaDataModel *model,
                                             const GList *values);
gboolean    gda_data_model_append_row       (GdaDataModel *model,
                                             GdaRow *row);
gboolean    gda_data_model_update_row       (GdaDataModel *model,
                                             const GdaRow *row);
gboolean    gda_data_model_remove_row       (GdaDataModel *model,
                                             const GdaRow *row);
gboolean    gda_data_model_append_column    (GdaDataModel *model,
                                             const GdaColumn *attrs);
gboolean    gda_data_model_remove_column    (GdaDataModel *model,
                                             gint col);
gboolean    (*GdaDataModelForeachFunc)      (GdaDataModel *model,
                                             GdaRow *row,
                                             gpointer user_data);
void        gda_data_model_foreach          (GdaDataModel *model,
                                             GdaDataModelForeachFunc func,
                                             gpointer user_data);
gboolean    gda_data_model_has_changed      (GdaDataModel *model);
gboolean    gda_data_model_begin_update     (GdaDataModel *model);
gboolean    gda_data_model_cancel_update    (GdaDataModel *model);
gboolean    gda_data_model_commit_update    (GdaDataModel *model);
gchar*      gda_data_model_to_text_separated
                                            (GdaDataModel *model,
                                             const gint *cols,
                                             gint nb_cols,
                                             gchar sep);
gchar*      gda_data_model_to_xml           (GdaDataModel *model,
                                             const gint *cols,
                                             gint nb_cols,
                                             const gchar *name);
xmlNodePtr  gda_data_model_to_xml_node      (GdaDataModel *model,
                                             const gint *cols,
                                             gint nb_cols,
                                             const gchar *name);
gboolean    gda_data_model_add_data_from_xml_node
                                            (GdaDataModel *model,
                                             xmlNodePtr node);
void        gda_data_model_dump             (GdaDataModel *model,
                                             FILE *to_stream);
gchar*      gda_data_model_dump_as_string   (GdaDataModel *model);

Object Hierarchy


  GInterface
   +----GdaDataModel

Prerequisites

GdaDataModel requires GObject.

Known Implementations

GdaDataModel is implemented by GdaSelect, GdaDataModelList, GdaDataModelArray, GdaDataModelHash and GdaDataModelBase.

Signals


"begin-update"
            void        user_function      (GdaDataModel *gdadatamodel,
                                            gpointer user_data);
"cancel-update"
            void        user_function      (GdaDataModel *gdadatamodel,
                                            gpointer user_data);
"changed"   void        user_function      (GdaDataModel *gdadatamodel,
                                            gpointer user_data);
"column-inserted"
            void        user_function      (GdaDataModel *gdadatamodel,
                                            gint arg1,
                                            gpointer user_data);
"column-removed"
            void        user_function      (GdaDataModel *gdadatamodel,
                                            gint arg1,
                                            gpointer user_data);
"column-updated"
            void        user_function      (GdaDataModel *gdadatamodel,
                                            gint arg1,
                                            gpointer user_data);
"commit-update"
            void        user_function      (GdaDataModel *gdadatamodel,
                                            gpointer user_data);
"row-inserted"
            void        user_function      (GdaDataModel *gdadatamodel,
                                            gint arg1,
                                            gpointer user_data);
"row-removed"
            void        user_function      (GdaDataModel *gdadatamodel,
                                            gint arg1,
                                            gpointer user_data);
"row-updated"
            void        user_function      (GdaDataModel *gdadatamodel,
                                            gint arg1,
                                            gpointer user_data);

Description

Details

GdaDataModel

typedef struct _GdaDataModel GdaDataModel;


gda_data_model_freeze ()

void        gda_data_model_freeze           (GdaDataModel *model);

Disables notifications of changes on the given data model. To re-enable notifications again, you should call the gda_data_model_thaw function.

model : a GdaDataModel object.

gda_data_model_thaw ()

void        gda_data_model_thaw             (GdaDataModel *model);

Re-enables notifications of changes on the given data model.

model : a GdaDataModel object.

gda_data_model_get_n_rows ()

gint        gda_data_model_get_n_rows       (GdaDataModel *model);

model : a GdaDataModel object.
Returns : the number of rows in the given data model.

gda_data_model_get_n_columns ()

gint        gda_data_model_get_n_columns    (GdaDataModel *model);

model : a GdaDataModel object.
Returns : the number of columns in the given data model.

gda_data_model_describe_column ()

GdaColumn*  gda_data_model_describe_column  (GdaDataModel *model,
                                             gint col);

Queries the underlying data model implementation for a description of a given column. That description is returned in the form of a GdaColumn structure, which contains all the information about the given column in the data model.

WARNING: the returned GdaColumn object belongs to the model model and and should not be destroyed.

model : a GdaDataModel object.
col : column number.
Returns : the description of the column.

gda_data_model_get_column_title ()

const gchar* gda_data_model_get_column_title
                                            (GdaDataModel *model,
                                             gint col);

model : a GdaDataModel object.
col : column number.
Returns : the title for the given column in a data model object.

gda_data_model_set_column_title ()

void        gda_data_model_set_column_title (GdaDataModel *model,
                                             gint col,
                                             const gchar *title);

Sets the title of the given col in model.

model : a GdaDataModel object.
col : column number
title : title for the given column.

gda_data_model_get_column_position ()

gint        gda_data_model_get_column_position
                                            (GdaDataModel *model,
                                             const gchar *title);

model :
title :
Returns :

gda_data_model_get_row ()

const GdaRow* gda_data_model_get_row        (GdaDataModel *model,
                                             gint row);

Retrieves a given row from a data model.

model : a GdaDataModel object.
row : row number.
Returns : a GdaRow object.

gda_data_model_get_value_at ()

const GdaValue* gda_data_model_get_value_at (GdaDataModel *model,
                                             gint col,
                                             gint row);

Retrieves the data stored in the given position (identified by the col and row parameters) on a data model.

This is the main function for accessing data in a model.

model : a GdaDataModel object.
col : column number.
row : row number.
Returns : a GdaValue containing the value stored in the given position, or NULL on error (out-of-bound position, etc).

gda_data_model_is_updatable ()

gboolean    gda_data_model_is_updatable     (GdaDataModel *model);

Checks whether the given data model can be updated or not.

model : a GdaDataModel object.
Returns : TRUE if it can be updated, FALSE if not.

gda_data_model_append_values ()

const GdaRow* gda_data_model_append_values  (GdaDataModel *model,
                                             const GList *values);

Appends a row to the given data model.

model : a GdaDataModel object.
values : GList of GdaValue* representing the row to add. The length must match model's column count. These GdaValue are value-copied. The user is still responsible for freeing them.
Returns : the added row.

gda_data_model_append_row ()

gboolean    gda_data_model_append_row       (GdaDataModel *model,
                                             GdaRow *row);

Appends a row to the data model. The 'number' attribute of row may be modified by the data model to represent the actual row position.

This function differs from the gda_data_model_append_values() method in that it is more coherent with the other gda_data_model_*_row() functions, and also is more adapted to GdaDataModel which don't manage themselves any GdaRow internally.

The row object is then referenced by the model model and can be safely unref'ed by the caller. A pointer to that row object can be obtained at any time using the gda_data_model_get_row() method.

model : a GdaDataModel object.
row : the GdaRow to be appended
Returns : TRUE if successful, FALSE otherwise.

gda_data_model_update_row ()

gboolean    gda_data_model_update_row       (GdaDataModel *model,
                                             const GdaRow *row);

Updates a row data model. This results in the underlying database row's values being changed.

NOTE: the row GdaRow must not be used again because it may or may not be used by the model model depending on model's implementation.

model : a GdaDataModel object.
row : the GdaRow to be updated.
Returns : TRUE if successful, FALSE otherwise.

gda_data_model_remove_row ()

gboolean    gda_data_model_remove_row       (GdaDataModel *model,
                                             const GdaRow *row);

Removes a row from the data model. This results in the underlying database row being removed in the database.

model : a GdaDataModel object.
row : the GdaRow to be removed.
Returns : TRUE if successful, FALSE otherwise.

gda_data_model_append_column ()

gboolean    gda_data_model_append_column    (GdaDataModel *model,
                                             const GdaColumn *attrs);

Appends a column to the given data model. If successful, the position of a pointer to a GdaColumn is returned (and its attributes can be updated)

model : a GdaDataModel object.
attrs : a GdaColumn describing the column to add.
Returns : a GdaColumn if successful, and NULL if the data model does not suppport this method.

gda_data_model_remove_column ()

gboolean    gda_data_model_remove_column    (GdaDataModel *model,
                                             gint col);

Removes a column from the data model. This means that all values attached to this column in the data model will be destroyed in the underlying database.

model : a GdaDataModel object.
col : the column to be removed.
Returns : TRUE if successful, FALSE if the data model cannot be modified of if it does not support that method.

GdaDataModelForeachFunc ()

gboolean    (*GdaDataModelForeachFunc)      (GdaDataModel *model,
                                             GdaRow *row,
                                             gpointer user_data);

model :
row :
user_data :
Returns :

gda_data_model_foreach ()

void        gda_data_model_foreach          (GdaDataModel *model,
                                             GdaDataModelForeachFunc func,
                                             gpointer user_data);

Calls the specified callback function for each row in the data model. This will just traverse all rows, and call the given callback function for each of them.

The callback function must have the following form:

gboolean foreach_func (GdaDataModel *model, GdaRow *row, gpointer user_data)

where "row" would be the row being read, and "user_data" the parameter specified in user_data in the call to gda_data_model_foreach. This callback function can return FALSE to stop the processing. If it returns TRUE, processing will continue until no rows remain.

model : a GdaDataModel object.
func : callback function.
user_data : context data for the callback function.

gda_data_model_has_changed ()

gboolean    gda_data_model_has_changed      (GdaDataModel *model);

Checks whether this data model is in updating mode or not. Updating mode is set to TRUE when gda_data_model_begin_update has been called successfully, and is not set back to FALSE until either gda_data_model_cancel_update or gda_data_model_commit_update have been called.

model : a GdaDataModel object.
Returns : TRUE if updating mode, FALSE otherwise.

gda_data_model_begin_update ()

gboolean    gda_data_model_begin_update     (GdaDataModel *model);

Starts update of this data model. This function should be the first called when modifying the data model.

model : a GdaDataModel object.
Returns : TRUE on success, FALSE if there was an error.

gda_data_model_cancel_update ()

gboolean    gda_data_model_cancel_update    (GdaDataModel *model);

Cancels update of this data model. This means that all changes will be discarded, and the old data put back in the model.

model : a GdaDataModel object.
Returns : TRUE on success, FALSE if there was an error.

gda_data_model_commit_update ()

gboolean    gda_data_model_commit_update    (GdaDataModel *model);

Approves all modifications and send them to the underlying data source/store.

model : a GdaDataModel object.
Returns : TRUE on success, FALSE if there was an error.

gda_data_model_to_text_separated ()

gchar*      gda_data_model_to_text_separated
                                            (GdaDataModel *model,
                                             const gint *cols,
                                             gint nb_cols,
                                             gchar sep);

Converts the given model into a char-separated series of rows. Examples of sep are ',' for comma separated export and '\t' for tab separated export

model : a GdaDataModel object.
cols : an array containing which columns of model will be exported, or NULL for all columns
nb_cols : the number of columns in cols
sep : a char separator
Returns : the representation of the model. You should free this string when you no longer need it.

gda_data_model_to_xml ()

gchar*      gda_data_model_to_xml           (GdaDataModel *model,
                                             const gint *cols,
                                             gint nb_cols,
                                             const gchar *name);

Converts the given model into a XML representation.

model : a GdaDataModel object.
cols : an array containing which columns of model will be exported, or NULL for all columns
nb_cols : the number of columns in cols
name :
Returns : the representation of the model. You should free this string when you no longer need it.

gda_data_model_to_xml_node ()

xmlNodePtr  gda_data_model_to_xml_node      (GdaDataModel *model,
                                             const gint *cols,
                                             gint nb_cols,
                                             const gchar *name);

Converts a GdaDataModel into a xmlNodePtr (as used in libxml).

model : a GdaDataModel object.
cols : an array containing which columns of model will be exported, or NULL for all columns
nb_cols : the number of columns in cols
name : name to use for the XML resulting table.
Returns : a xmlNodePtr representing the whole data model.

gda_data_model_add_data_from_xml_node ()

gboolean    gda_data_model_add_data_from_xml_node
                                            (GdaDataModel *model,
                                             xmlNodePtr node);

Adds the data from a XML node to the given data model.

model : a GdaDataModel.
node : a XML node representing a <data> XML node.
Returns : TRUE if successful, FALSE otherwise.

gda_data_model_dump ()

void        gda_data_model_dump             (GdaDataModel *model,
                                             FILE *to_stream);

Dumps a textual representation of the model to the to_stream stream

model : a GdaDataModel.
to_stream : where to dump the data model

gda_data_model_dump_as_string ()

gchar*      gda_data_model_dump_as_string   (GdaDataModel *model);

Dumps a textual representation of the model into a new string

model : a GdaDataModel.
Returns : a new string.

Signal Details

The "begin-update" signal

void        user_function                  (GdaDataModel *gdadatamodel,
                                            gpointer user_data);

gdadatamodel : the object which received the signal.
user_data : user data set when the signal handler was connected.

The "cancel-update" signal

void        user_function                  (GdaDataModel *gdadatamodel,
                                            gpointer user_data);

gdadatamodel : the object which received the signal.
user_data : user data set when the signal handler was connected.

The "changed" signal

void        user_function                  (GdaDataModel *gdadatamodel,
                                            gpointer user_data);

gdadatamodel : the object which received the signal.
user_data : user data set when the signal handler was connected.

The "column-inserted" signal

void        user_function                  (GdaDataModel *gdadatamodel,
                                            gint arg1,
                                            gpointer user_data);

gdadatamodel : the object which received the signal.
arg1 :
user_data : user data set when the signal handler was connected.

The "column-removed" signal

void        user_function                  (GdaDataModel *gdadatamodel,
                                            gint arg1,
                                            gpointer user_data);

gdadatamodel : the object which received the signal.
arg1 :
user_data : user data set when the signal handler was connected.

The "column-updated" signal

void        user_function                  (GdaDataModel *gdadatamodel,
                                            gint arg1,
                                            gpointer user_data);

gdadatamodel : the object which received the signal.
arg1 :
user_data : user data set when the signal handler was connected.

The "commit-update" signal

void        user_function                  (GdaDataModel *gdadatamodel,
                                            gpointer user_data);

gdadatamodel : the object which received the signal.
user_data : user data set when the signal handler was connected.

The "row-inserted" signal

void        user_function                  (GdaDataModel *gdadatamodel,
                                            gint arg1,
                                            gpointer user_data);

gdadatamodel : the object which received the signal.
arg1 :
user_data : user data set when the signal handler was connected.

The "row-removed" signal

void        user_function                  (GdaDataModel *gdadatamodel,
                                            gint arg1,
                                            gpointer user_data);

gdadatamodel : the object which received the signal.
arg1 :
user_data : user data set when the signal handler was connected.

The "row-updated" signal

void        user_function                  (GdaDataModel *gdadatamodel,
                                            gint arg1,
                                            gpointer user_data);

gdadatamodel : the object which received the signal.
arg1 :
user_data : user data set when the signal handler was connected.