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
                                            (GnomeDbDataSet *dataset,
                                             const gchar *param_name);
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)      : Run first

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

GnomeDbParameter* gnome_db_data_set_find_parameter
                                            (GnomeDbDataSet *dataset,
                                             const gchar *param_name);

Finds a GnomeDbParameter using its name

dataset : a GnomeDbDataSet object
param_name : the name of the requested parameter
Returns : a GnomeDbParameter or NULL

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)      : Run first

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