GdaParameterList

GdaParameterList — Manages a list of GdaParameter objects which contain individual values

Synopsis




            GdaParameterList;
enum        GdaParameterListParamHint;
            GdaParameterListNode;
            GdaParameterListGroup;
            GdaParameterListSource;
GdaParameterList* gda_parameter_list_new    (GSList *params);
GdaParameterList* gda_parameter_list_new_from_spec_string
                                            (GdaDict *dict,
                                             const gchar *xml_spec,
                                             GError **error);
guint       gda_parameter_list_get_length   (GdaParameterList *plist);
gchar*      gda_parameter_list_get_spec     (GdaParameterList *paramlist);
void        gda_parameter_list_add_param    (GdaParameterList *paramlist,
                                             GdaParameter *param);
GdaParameter* gda_parameter_list_add_param_from_string
                                            (GdaParameterList *paramlist,
                                             const gchar *name,
                                             GType type,
                                             const gchar *str);
GdaParameter* gda_parameter_list_add_param_from_value
                                            (GdaParameterList *paramlist,
                                             const gchar *name,
                                             GValue *value);
gboolean    gda_parameter_list_is_coherent  (GdaParameterList *paramlist,
                                             GError **error);
gboolean    gda_parameter_list_is_valid     (GdaParameterList *paramlist);
GdaParameter* gda_parameter_list_find_param (GdaParameterList *paramlist,
                                             const gchar *param_name);
GdaParameter* gda_parameter_list_find_param_for_user
                                            (GdaParameterList *paramlist,
                                             GdaObject *user);
GdaParameterListNode* gda_parameter_list_find_node_for_param
                                            (GdaParameterList *paramlist,
                                             GdaParameter *param);
GdaParameterListSource* gda_parameter_list_find_source_for_param
                                            (GdaParameterList *paramlist,
                                             GdaParameter *param);
GdaParameterListSource* gda_parameter_list_find_source
                                            (GdaParameterList *paramlist,
                                             GdaDataModel *model);
void        gda_parameter_list_set_param_default_value
                                            (GdaParameterList *paramlist,
                                             GdaParameter *param,
                                             const GValue *value);
void        gda_parameter_list_set_param_default_alias
                                            (GdaParameterList *paramlist,
                                             GdaParameter *param,
                                             GdaParameter *alias);
const GValue* gda_parameter_list_get_param_default_value
                                            (GdaParameterList *paramlist,
                                             GdaParameter *param);

Object Hierarchy


  GObject
   +----GdaObject
         +----GdaParameterList
               +----GdaDataModelIter

Signals


"param-changed"
            void        user_function      (GdaParameterList *gdaparameterlist,
                                            GObject          *arg1,
                                            gpointer          user_data)             : Run first
"public-data-changed"
            void        user_function      (GdaParameterList *gdaparameterlist,
                                            gpointer          user_data)             : Run first

Description

A GdaParameterList is in a way only a better than GList list of GdaParameter objects: it handles a list of GdaParameter objects (accessible directly using paramlist->parameters) but also creates other lists such as:

  • a list of GdaParameterListNode structures (the nodes_list attribute): for each parameter a such structure is created to show in a signle place all the information about each parameter: the GdaDataModel which may restrict the list of values along with the column number in it, and any hint for the parameter (a value made of GdaParameterListParamHint flags)

  • a list of GdaParameterListSource structures (the sources_list attribute): each GdaParameterListSource structure is complementary to the GdaParameterListNode structures listed in its "nodes" attribute: there is one such structure for each GdaDataModel which may restrict values of one or more parameters.

  • a list of GdaParameterListGroup structures (the groups_list attribute): there is one such structure for each _independant_ parameter (parameters which are constrained by the same data model all appear in the same GdaParameterListGroup structure)

Some queries require arguments before they can be executed. For such queries, the arguments are passed using GdaParameter objects (the list of parameters can be obtained using gda_query_get_parameters() or gda_query_get_parameters_boxed()).

Details

GdaParameterList

typedef struct _GdaParameterList GdaParameterList;


enum GdaParameterListParamHint

typedef enum {
	GDA_PARAMETER_LIST_PARAM_READ_ONLY = 1 << 0, /* param should not be affected by user modifications */
	GDA_PARAMETER_LIST_PARAM_HIDE      = 1 << 1  /* param should not be shown to the user */
} GdaParameterListParamHint;


GdaParameterListNode

typedef struct {
	GdaParameter   *param;         /* Can't be NULL */
	GdaDataModel   *source_model;  /* may be NULL if @param is free-fill */
	gint            source_column; /* unused is @source_model is NULL */
	guint           hint;
} GdaParameterListNode;


GdaParameterListGroup

typedef struct {
	GSList                 *nodes;        /* list of GdaParameterListNode, at least one entry */
	GdaParameterListSource *nodes_source; /* if NULL, then @nodes contains exactly one entry */
} GdaParameterListGroup;


GdaParameterListSource

typedef struct {
	GdaDataModel   *data_model;   /* Can't be NULL */
	GSList         *nodes;        /* list of #GdaParameterListNode for which source_model == @data_model */

	/* displayed columns in 'data_model' */
        gint            shown_n_cols;
        gint           *shown_cols_index;

        /* columns used as a reference (corresponding to PK values) in 'data_model' */
        gint            ref_n_cols;
        gint           *ref_cols_index;
} GdaParameterListSource;


gda_parameter_list_new ()

GdaParameterList* gda_parameter_list_new    (GSList *params);

Creates a new GdaParameterList 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).

params : a list of GdaParameter objects
Returns : a new GdaParameterList object

gda_parameter_list_new_from_spec_string ()

GdaParameterList* gda_parameter_list_new_from_spec_string
                                            (GdaDict *dict,
                                             const gchar *xml_spec,
                                             GError **error);

Creates a new GdaParameterList object from the xml_spec specifications

dict : a GdaDict object, or NULL
xml_spec : a string
error : a place to store the error, or NULL
Returns : a new object, or NULL if an error occurred

gda_parameter_list_get_length ()

guint       gda_parameter_list_get_length   (GdaParameterList *plist);

Get the number of GdaParameter objects in paramlist

plist :
Returns :

gda_parameter_list_get_spec ()

gchar*      gda_parameter_list_get_spec     (GdaParameterList *paramlist);

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

paramlist : a GdaParameterList object
Returns : a new string

gda_parameter_list_add_param ()

void        gda_parameter_list_add_param    (GdaParameterList *paramlist,
                                             GdaParameter *param);

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

paramlist : a GdaParameterList object
param : a GdaParameter object

gda_parameter_list_add_param_from_string ()

GdaParameter* gda_parameter_list_add_param_from_string
                                            (GdaParameterList *paramlist,
                                             const gchar *name,
                                             GType type,
                                             const gchar *str);

Creates and adds a new GdaParameter to paramlist. The ID and name of the new parameter are set as name. The parameter's value is set from str.

paramlist : a GdaParameterList object
name : the name to give to the new parameter
type : the type of parameter to add
str : the string representation of the parameter
Returns : the new GdaParameter for information, or NULL if an error occurred

gda_parameter_list_add_param_from_value ()

GdaParameter* gda_parameter_list_add_param_from_value
                                            (GdaParameterList *paramlist,
                                             const gchar *name,
                                             GValue *value);

Creates and adds a new GdaParameter to paramlist. The ID and name of the new parameter are set as name. The parameter's value is a copy of value.

paramlist : a GdaParameterList object
name : the name to give to the new parameter
value : the value to give to the new parameter, must not be NULL or of type null
Returns : the new GdaParameter for information, or NULL if an error occurred

gda_parameter_list_is_coherent ()

gboolean    gda_parameter_list_is_coherent  (GdaParameterList *paramlist,
                                             GError **error);

Checks that paramlist has a coherent public data structure

paramlist : a GdaParameterList object
error :
Returns : TRUE if paramlist is coherent

gda_parameter_list_is_valid ()

gboolean    gda_parameter_list_is_valid     (GdaParameterList *paramlist);

Tells if all the paramlist's parameters have valid data

paramlist : a GdaParameterList object
Returns : TRUE if the paramlist is valid

gda_parameter_list_find_param ()

GdaParameter* gda_parameter_list_find_param (GdaParameterList *paramlist,
                                             const gchar *param_name);

Finds a GdaParameter using its name

paramlist : a GdaParameterList object
param_name : the name of the requested parameter
Returns : a GdaParameter or NULL

gda_parameter_list_find_param_for_user ()

GdaParameter* gda_parameter_list_find_param_for_user
                                            (GdaParameterList *paramlist,
                                             GdaObject *user);

Finds a GdaParameter which is to be used by user

paramlist : a GdaParameterList object
user : a GdaObject object
Returns : a GdaParameter or NULL

gda_parameter_list_find_node_for_param ()

GdaParameterListNode* gda_parameter_list_find_node_for_param
                                            (GdaParameterList *paramlist,
                                             GdaParameter *param);

Finds a GdaParameterListNode holding information for param, don't modify the returned structure

paramlist : a GdaParameterList object
param : a GdaParameter object
Returns : a GdaParameterListNode or NULL

gda_parameter_list_find_source_for_param ()

GdaParameterListSource* gda_parameter_list_find_source_for_param
                                            (GdaParameterList *paramlist,
                                             GdaParameter *param);

Finds a GdaParameterListSource which contains the GdaDataModel restricting the possible values of param, don't modify the returned structure.

paramlist : a GdaParameterList object
param : a GdaParameter object
Returns : a GdaParameterListSource or NULL

gda_parameter_list_find_source ()

GdaParameterListSource* gda_parameter_list_find_source
                                            (GdaParameterList *paramlist,
                                             GdaDataModel *model);

Finds the GdaParameterListSource structure used in paramlist for which model is a the data model, don't modify the returned structure

paramlist : a GdaParameterList object
model : a GdaDataModel object
Returns : a GdaParameterListSource pointer or NULL.

gda_parameter_list_set_param_default_value ()

void        gda_parameter_list_set_param_default_value
                                            (GdaParameterList *paramlist,
                                             GdaParameter *param,
                                             const GValue *value);

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

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

paramlist : a GdaParameterList object
param : a GdaParameter object, managed by paramlist
value : a GValue, of the same type as param, or NULL

gda_parameter_list_set_param_default_alias ()

void        gda_parameter_list_set_param_default_alias
                                            (GdaParameterList *paramlist,
                                             GdaParameter *param,
                                             GdaParameter *alias);

paramlist :
param :
alias :

gda_parameter_list_get_param_default_value ()

const GValue* gda_parameter_list_get_param_default_value
                                            (GdaParameterList *paramlist,
                                             GdaParameter *param);

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

paramlist only offers to store the value using gda_parameter_list_set_param_default_value() or to store a GdaParameter reference from which to get a value using gda_parameter_list_set_param_default_alias().

paramlist : a GdaParameterList object
param : a GdaParameter object, managed by paramlist
Returns : a GValue, or NULL.

Signal Details

The "param-changed" signal

void        user_function                  (GdaParameterList *gdaparameterlist,
                                            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.

The "public-data-changed" signal

void        user_function                  (GdaParameterList *gdaparameterlist,
                                            gpointer          user_data)             : Run first

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