## GnomeDbDataModel

GnomeDbDataModel — Interface to improve the capabilities of the GdaDataModel interface

##

# Synopsis

    struct      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.

## Signal Prototypes

    "data-refreshed"
                void        user_function      (GnomeDbDataModel *dbdatamodel,
                                                gpointer user_data);

## 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

### struct GnomeDbDataModel

    struct 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

## Signals

### The "data-refreshed" signal

    void        user_function                  (GnomeDbDataModel *dbdatamodel,
                                                gpointer user_data);

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