## GnomeDbDataSet

GnomeDbDataSet — Manages a list of GnomeDbParameter objects which contain individual values

## Synopsis

                GnomeDbDataSet;
                GnomeDbDataSetNode;
    enum        GnomeDbDataSetParamHint;
    GType       gnome_db_data_set_get_type      (void);
    GObject*    gnome_db_data_set_new           (GnomeDbDict *dict,
                                                 GSList *params);
    GObject*    gnome_db_data_set_new_copy      (GnomeDbDataSet *orig,
                                                 GHashTable *replacements);
    GObject*    gnome_db_data_set_new_from_spec (GnomeDbDict *dict,
                                                 const gchar *xml_spec,
                                                 GError **error);
    gchar*      gnome_db_data_set_get_spec      (GnomeDbDataSet *dataset);
    void        gnome_db_data_set_add_param     (GnomeDbDataSet *dataset,
                                                 GnomeDbParameter *param);
    void        gnome_db_data_set_merge_dataset_params
                                                (GnomeDbDataSet *dataset,
                                                 GnomeDbDataSet *dataset_to_merge);
    gboolean    gnome_db_data_set_is_coherent   (GnomeDbDataSet *dataset,
                                                 GError **error);
    gboolean    gnome_db_data_set_is_valid      (GnomeDbDataSet *dataset);
    gboolean    gnome_db_data_set_needs_user_input
                                                (GnomeDbDataSet *dataset);
    GnomeDbParameter* gnome_db_data_set_find_parameter_for_field
                                                (GnomeDbDataSet *dataset,
                                                 GnomeDbField *for_field);
    GnomeDbDataSetNode* gnome_db_data_set_find_node_for_param
                                                (GnomeDbDataSet *dataset,
                                                 GnomeDbParameter *param);
    void        gnome_db_data_set_set_param_default_value
                                                (GnomeDbDataSet *dataset,
                                                 GnomeDbParameter *param,
                                                 const GdaValue *value);
    void        gnome_db_data_set_set_param_default_alias
                                                (GnomeDbDataSet *dataset,
                                                 GnomeDbParameter *param,
                                                 GnomeDbParameter *alias);
    const GdaValue* gnome_db_data_set_get_param_default_value
                                                (GnomeDbDataSet *dataset,
                                                 GnomeDbParameter *param);

## Object Hierarchy

      GObject
       +----GnomeDbBase
             +----GnomeDbDataSet

## Properties

      "prop"                 gpointer              : Read / Write

## Signals

    "param-changed"
                void        user_function      (GnomeDbDataSet *dbdataset,
                                                GObject *arg1,
                                                gpointer user_data);

## Description

In general way, the GnomeDbDataSet is used in conjunction with the objects which implement the GnomeDbDataModel; the list of data which it represents is basically a "row" of the data contained in a GnomeDbDataModel object. As it can be considered as a simple list of values (as GnomeDbParameter objects), it is also used a lot when dealing with queries which require parameters.

Some queries require arguments before they can be executed. For such queries, the arguments are passed using GnomeDbParameter objects (the list of parameters can be obtained using `gnome_db_entity_get_parameters()`). The GnomeDbDataSet object removes the hassle of managing these GnomeDbParameter objects. For a query, a GnomeDbDataSet can be obtained using the `gnome_db_entity_get_exec_context()` function.

Each GnomeDbDataSet object then provides two lists to be used by the programmer: the 'parameters' list which is a simple copy of the parameters list given as argument to `gnome_db_data_set_new()`, and the 'nodes' list which is a list of GnomeDbDataSetNode structures created by the GnomeDbDataSet object. These two lists should not be modified.

## Details

### GnomeDbDataSet

    typedef struct _GnomeDbDataSet GnomeDbDataSet;

### GnomeDbDataSetNode

    typedef struct {
    	/* this GnomeDbDataSetNode is only for one parameter, free fill */
            GnomeDbParameter *param;

    	/* this GnomeDbDataSetNode is for one or more parameters, listed in 'params' and the params values
    	   depend on the data in 'data_for_param' */
            GSList           *params;
            GnomeDbDataModel *data_for_param;
    	GHashTable       *pos_for_param; /* key=param value=column in 'data_for_param' where its source field is */
    } GnomeDbDataSetNode;

### enum GnomeDbDataSetParamHint

    typedef enum {
    	GNOME_DB_DATA_SET_PARAM_READ_ONLY = 1 << 0, /* param should not be affected by user modifications */
    	GNOME_DB_DATA_SET_PARAM_HIDE      = 1 << 1  /* param should not be shown to the user */
    } GnomeDbDataSetParamHint;

### gnome_db_data_set_get_type ()

    GType       gnome_db_data_set_get_type      (void);

Returns : |

### gnome_db_data_set_new ()

    GObject*    gnome_db_data_set_new           (GnomeDbDict *dict,
                                                 GSList *params);

Creates a new GnomeDbDataSet object, and populates it with the list given as argument. The list can then be freed as it gets copied. All the parameters in `params` are referenced counted and modified, so they should not be used anymore afterwards, and the `params` list gets copied (so it should be freed by the caller).

`dict` : | a GnomeDbDict object
`params` : | a list of GnomeDbParameter objects
Returns : | a new GnomeDbDataSet object

### gnome_db_data_set_new_copy ()

    GObject*    gnome_db_data_set_new_copy      (GnomeDbDataSet *orig,
                                                 GHashTable *replacements);

Copy constructor. `replacements` is used and modified only if `copy_params` is TRUE.

`orig` : | a GnomeDbDataSet to make a copy of
`replacements` : | a place where to store the parameters and queries replacements, or `NULL`
Returns : | a the new copy of `orig`

### gnome_db_data_set_new_from_spec ()

    GObject*    gnome_db_data_set_new_from_spec (GnomeDbDict *dict,
                                                 const gchar *xml_spec,
                                                 GError **error);

Creates a new GnomeDbDataSet object from the `xml_spec` specifications

`dict` : |
`xml_spec` : | a string
`error` : | a place to store the error, or `NULL`
Returns : | a new object, or `NULL` if an error occured

### gnome_db_data_set_get_spec ()

    gchar*      gnome_db_data_set_get_spec      (GnomeDbDataSet *dataset);

Get the specification as an XML string. See the `gnome_db_data_set_new_from_spec()` form more information about the XML specification string format.

`dataset` : | a GnomeDbDataSet object
Returns : | a new string

### gnome_db_data_set_add_param ()

    void        gnome_db_data_set_add_param     (GnomeDbDataSet *dataset,
                                                 GnomeDbParameter *param);

Adds `param` to the list of parameters managed within `dataset`. WARNING: the dataset may decide not to use the `param` parameter, but to modify another parameter already present within the dataset. The publicly available lists from the `dataset` object may also be changed in the process.

`dataset` : | a GnomeDbDataSet object
`param` : | a GnomeDbParameter object

### gnome_db_data_set_merge_dataset_params ()

    void        gnome_db_data_set_merge_dataset_params
                                                (GnomeDbDataSet *dataset,
                                                 GnomeDbDataSet *dataset_to_merge);

Add to `dataset` all the parameters of `dataset_to_merge`.

`dataset` : | a GnomeDbDataSet object
`dataset_to_merge` : | a GnomeDbDataSet object

### gnome_db_data_set_is_coherent ()

    gboolean    gnome_db_data_set_is_coherent   (GnomeDbDataSet *dataset,
                                                 GError **error);

`dataset` : |
`error` : |
Returns : |

### gnome_db_data_set_is_valid ()

    gboolean    gnome_db_data_set_is_valid      (GnomeDbDataSet *dataset);

Tells if all the dataset's parameters have valid data

`dataset` : | a GnomeDbDataSet object
Returns : | TRUE if the dataset is valid

### gnome_db_data_set_needs_user_input ()

    gboolean    gnome_db_data_set_needs_user_input
                                                (GnomeDbDataSet *dataset);

Tells if the dataset needs the user to provide some values for some parameters. This is the case when either the dataset is invalid, or the dataset is valid and contains some GnomeDbParameter objects which are valid but are defined to require a user input.

Note: this function may return TRUE even though `dataset` is valid.

`dataset` : | a GnomeDbDataSet object
Returns : | TRUE if a user input is required for the dataset

### gnome_db_data_set_find_parameter_for_field ()

    GnomeDbParameter* gnome_db_data_set_find_parameter_for_field
                                                (GnomeDbDataSet *dataset,
                                                 GnomeDbField *for_field);

Finds a GnomeDbParameter which is to be used by `for_field`

`dataset` : | a GnomeDbDataSet object
`for_field` : | a GnomeDbField object
Returns : | a GnomeDbParameter or `NULL`

### gnome_db_data_set_find_node_for_param ()

    GnomeDbDataSetNode* gnome_db_data_set_find_node_for_param
                                                (GnomeDbDataSet *dataset,
                                                 GnomeDbParameter *param);

Finds a GnomeDbDataSetNode which is for `param`

`dataset` : | a GnomeDbDataSet object
`param` : | a GnomeDbParameter object
Returns : | a GnomeDbDataSetNode or `NULL`

### gnome_db_data_set_set_param_default_value ()

    void        gnome_db_data_set_set_param_default_value
                                                (GnomeDbDataSet *dataset,
                                                 GnomeDbParameter *param,
                                                 const GdaValue *value);

Stores `value` in `dataset` to make it possible for `dataset`'s users to find a default value for `param` when one is required, instead of `NULL`.

`dataset` only provides a storage functionnality, the way the value obtained with `gnome_db_data_set_get_param_default_value()` is used is up to `dataset`'s user.

`dataset` : | a GnomeDbDataSet object
`param` : | a GnomeDbParameter object, managed by `dataset`
`value` : | a GdaValue, of the same type as `param`, or `NULL`

### gnome_db_data_set_set_param_default_alias ()

    void        gnome_db_data_set_set_param_default_alias
                                                (GnomeDbDataSet *dataset,
                                                 GnomeDbParameter *param,
                                                 GnomeDbParameter *alias);

`dataset` : |
`param` : |
`alias` : |

### gnome_db_data_set_get_param_default_value ()

    const GdaValue* gnome_db_data_set_get_param_default_value
                                                (GnomeDbDataSet *dataset,
                                                 GnomeDbParameter *param);

Retreives a prefered default value to be used by `dataset`'s users when necessary. The usage of such values is decided by `dataset`'s users.

`dataset` only offers to store the value using `gnome_db_data_set_set_param_default_value()` or to store a GnomeDbParameter reference from which to get a value using `gnome_db_data_set_set_param_default_alias()`.

`dataset` : | a GnomeDbDataSet object
`param` : | a GnomeDbParameter object, managed by `dataset`
Returns : | a GdaValue, or `NULL`.

## Property Details

### The "`prop`" property

      "prop"                 gpointer              : Read / Write

## Signal Details

### The "param-changed" signal

    void        user_function                  (GnomeDbDataSet *dbdataset,
                                                GObject *arg1,
                                                gpointer user_data);

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