GnomeDbDataModel

GnomeDbDataModel — Interface to improve the capabilities of the GdaDataModel interface

Synopsis




            GnomeDbDataModel;
enum        GnomeDbDataModelAttributes;
GType       gnome_db_data_model_get_type    (void);
GObject*    gnome_db_data_model_copy        (GnomeDbDataModel *iface,
                                             GHashTable *replacements);
guint       gnome_db_data_model_get_status  (GnomeDbDataModel *iface);
gboolean    gnome_db_data_model_refresh     (GnomeDbDataModel *iface,
                                             GError **error);
GnomeDbDataSet* gnome_db_data_model_get_params
                                            (GnomeDbDataModel *iface);
GnomeDbDataSet* gnome_db_data_model_get_new_data_set
                                            (GnomeDbDataModel *iface);
gboolean    gnome_db_data_model_sync_data_set
                                            (GnomeDbDataModel *iface,
                                             GnomeDbDataSet *data_set,
                                             gint row);
GnomeDbParameter* gnome_db_data_model_get_param_at_column
                                            (GnomeDbDataModel *iface,
                                             GnomeDbDataSet *data_set,
                                             gint column);
gint        gnome_db_data_model_get_column_at_param
                                            (GnomeDbDataModel *iface,
                                             GnomeDbDataSet *data_set,
                                             GnomeDbParameter *param);
GSList*     gnome_db_data_model_get_key_columns
                                            (GnomeDbDataModel *iface,
                                             GnomeDbDataSet *data_set);
gint        gnome_db_data_model_get_row_from_values
                                            (GnomeDbDataModel *model,
                                             GSList *values,
                                             gint *cols_index);

Object Hierarchy


  GInterface
   +----GnomeDbDataModel

Prerequisites

GnomeDbDataModel requires GnomeDbEntity, GdaDataModel and GnomeDbBase.

Known Implementations

GnomeDbDataModel is implemented by GnomeDbModelWrapper and GnomeDbResultSet.

Signals


"data-refreshed"
            void        user_function      (GnomeDbDataModel *dbdatamodel,
                                            gpointer          user_data)        : Run first

Description

This interface has a similar role to the GdaDataModel interface, but adds a few more capabilities such as support for parameters to the data contents, and a refresh() method for data models for which the contents can vary with the values of parameters (most notably the result of SELECT queries which depend on parameters).

This interface also makes it easy to create some kind of "iterators" using GnomeDbDataSet objects: a new data set can be created using the gnome_db_data_model_get_new_data_set() method, and all the values in the data set can be modified using gnome_db_data_model_sync_data_set().

The GnomeDbDataModel also may have a special GnomeDbDataSet object which list the values which are parameters controlling the actual contents of the data model. Changing any value in that data set makes the data stored in the data model change (an a "data_refreshed" signal emitted).

Any object which implement this interface must also implement the GdaDataModel and the GnomeDbEntity interfaces.

Details

GnomeDbDataModel

typedef struct _GnomeDbDataModel GnomeDbDataModel;


enum GnomeDbDataModelAttributes

typedef enum {
	GNOME_DB_DATA_MODEL_CAN_BE_REFRESHED   = 1 << 0,
	GNOME_DB_DATA_MODEL_NEEDS_INIT_REFRESH = 1 << 1
} GnomeDbDataModelAttributes;


gnome_db_data_model_get_type ()

GType       gnome_db_data_model_get_type    (void);

Returns :

gnome_db_data_model_copy ()

GObject*    gnome_db_data_model_copy        (GnomeDbDataModel *iface,
                                             GHashTable *replacements);

This is a generic copy constructor.

iface : an object implementing the GnomeDbDataModel interface
replacements : a place to store the sub-objects correspondance, or NULL
Returns : a new GnomeDbDataModel object, or NULL if the model can't be copied

gnome_db_data_model_get_status ()

guint       gnome_db_data_model_get_status  (GnomeDbDataModel *iface);

Get the status of the data within iface, as an ORed value of the GnomeDbDataModelAttributes enumerated

iface : an object implementing the GnomeDbDataModel interface
Returns : the status

gnome_db_data_model_refresh ()

gboolean    gnome_db_data_model_refresh     (GnomeDbDataModel *iface,
                                             GError **error);

Refresh the data in iface. If the data is statically defined, then nothing is done; if the contents is defined as the result of a SELECT query's execution, then the query is executed again.

iface : an object implementing the GnomeDbDataModel interface
error : place to store the error, or NULL
Returns : TRUE if no error occured

gnome_db_data_model_get_params ()

GnomeDbDataSet* gnome_db_data_model_get_params
                                            (GnomeDbDataModel *iface);

Get the GnomeDbDataSet object which contains all the parameters which control the contents of the data in the iface object (the data itself is accessible using the GdaDataModel interface).

iface : an object implementing the GnomeDbDataModel interface
Returns : the GnomeDbDataSet object for parameters

gnome_db_data_model_get_new_data_set ()

GnomeDbDataSet* gnome_db_data_model_get_new_data_set
                                            (GnomeDbDataModel *iface);

Creates a new GnomeDbDataSet object which can be used to retreive (or store) individual data rows of the data in the iface object. Using a GnomeDbDataSet object instead of having a direct access to the data through the GdaDataModel object has the advantage that the GnomeDbDataSet can be manipulated as a single 'row' object.

iface : an object implementing the GnomeDbDataModel interface
Returns : a new GnomeDbDataSet object

gnome_db_data_model_sync_data_set ()

gboolean    gnome_db_data_model_sync_data_set
                                            (GnomeDbDataModel *iface,
                                             GnomeDbDataSet *data_set,
                                             gint row);

iface :
data_set :
row :
Returns :

gnome_db_data_model_get_param_at_column ()

GnomeDbParameter* gnome_db_data_model_get_param_at_column
                                            (GnomeDbDataModel *iface,
                                             GnomeDbDataSet *data_set,
                                             gint column);

Fetch the column number in iface which corresponds to param in the data_set data set.

iface : an object implementing the GnomeDbDataModel interface
data_set : a GnomeDbDataSet object obtained using gnome_db_data_model_get_data_set()
column :
Returns : the column number, or -1 if an error occured

gnome_db_data_model_get_column_at_param ()

gint        gnome_db_data_model_get_column_at_param
                                            (GnomeDbDataModel *iface,
                                             GnomeDbDataSet *data_set,
                                             GnomeDbParameter *param);

Fetch the GbomeDbParameter in data_set which corresponds to the column column in the data_set data set.

iface : an object implementing the GnomeDbDataModel interface
data_set : a GnomeDbDataSet object obtained using gnome_db_data_model_get_data_set()
param :
Returns : the parameter, or NULL if an error occured

gnome_db_data_model_get_key_columns ()

GSList*     gnome_db_data_model_get_key_columns
                                            (GnomeDbDataModel *iface,
                                             GnomeDbDataSet *data_set);

Get a list of parameters which, taken together, hold values which are a key (unique and not NULL) for the data held in iface.

iface : an object implementing the GnomeDbDataModel interface
data_set : a GnomeDbDataSet object obtained using gnome_db_data_model_get_data_set()
Returns : a new list of GnomeDbParameter objects, or NULL

gnome_db_data_model_get_row_from_values ()

gint        gnome_db_data_model_get_row_from_values
                                            (GnomeDbDataModel *model,
                                             GSList *values,
                                             gint *cols_index);

Returns the first row where all the values in values at the columns identified at cols_index match. If the row can't be identified, then returns -1;

NOTE: the cols_index array MUST contain a column index for each value in values

model :
values : a list of GdaValue values
cols_index : an array of gint containing the column number to match each value of values
Returns : the requested row number, of -1 if not found

Signal Details

The "data-refreshed" signal

void        user_function                  (GnomeDbDataModel *dbdatamodel,
                                            gpointer          user_data)        : Run first

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