![]() |
![]() |
![]() |
Libgnomedb Reference Manual | ![]() |
---|---|---|---|---|
GnomeDbDataSetGnomeDbDataSet — Manages a list of GnomeDbParameter objects which contain individual values |
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);
"param-changed" void user_function (GnomeDbDataSet *dbdataset, GObject *arg1, gpointer user_data) : Run first
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.
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;
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;
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 |
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
|
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
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 |
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 |
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 |
gboolean gnome_db_data_set_is_coherent (GnomeDbDataSet *dataset, GError **error);
dataset : |
|
error : |
|
Returns : |
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 |
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 |
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
|
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
|
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
|
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
|
void gnome_db_data_set_set_param_default_alias (GnomeDbDataSet *dataset, GnomeDbParameter *param, GnomeDbParameter *alias);
dataset : |
|
param : |
|
alias : |
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 .
|
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. |