GdaParameter

GdaParameter — Represents a GValue with various attributes

Synopsis




                    GdaParameter;
GdaParameter*       gda_parameter_new                   (GType type);
GdaParameter*       gda_parameter_new_copy              (GdaParameter *orig);
GdaParameter*       gda_parameter_new_string            (const gchar *name,
                                                         const gchar *str);
GdaParameter*       gda_parameter_new_boolean           (const gchar *name,
                                                         gboolean value);
GType               gda_parameter_get_g_type            (GdaParameter *param);
const GValue*       gda_parameter_get_value             (GdaParameter *param);
gchar*              gda_parameter_get_value_str         (GdaParameter *param);
void                gda_parameter_set_value             (GdaParameter *param,
                                                         const GValue *value);
gboolean            gda_parameter_set_value_str         (GdaParameter *param,
                                                         const gchar *value);
gchar*              gda_parameter_get_alphanum_name     (GdaParameter *param);
void                gda_parameter_declare_invalid       (GdaParameter *param);
gboolean            gda_parameter_is_valid              (GdaParameter *param);
const GValue*       gda_parameter_get_default_value     (GdaParameter *param);
void                gda_parameter_set_default_value     (GdaParameter *param,
                                                         const GValue *value);
gboolean            gda_parameter_get_exists_default_value
                                                        (GdaParameter *param);
void                gda_parameter_set_exists_default_value
                                                        (GdaParameter *param,
                                                         gboolean default_value_exists);
void                gda_parameter_set_not_null          (GdaParameter *param,
                                                         gboolean not_null);
gboolean            gda_parameter_get_not_null          (GdaParameter *param);
gboolean            gda_parameter_restrict_values       (GdaParameter *param,
                                                         GdaDataModel *model,
                                                         gint col,
                                                         GError **error);
gboolean            gda_parameter_has_restrict_values   (GdaParameter *param,
                                                         GdaDataModel **model,
                                                         gint *col);
void                gda_parameter_bind_to_param         (GdaParameter *param,
                                                         GdaParameter *bind_to);
GdaParameter*       gda_parameter_get_bind_param        (GdaParameter *param);

Object Hierarchy


  GObject
   +----GdaObject
         +----GdaParameter

Implemented Interfaces

GdaParameter implements GdaReferer.

Properties


  "entry-plugin"             gchararray            : Read / Write
  "full-bind"                GdaParameter          : Read / Write
  "g-type"                   gulong                : Read / Write / Construct Only
  "not-null"                 gboolean              : Read / Write
  "restrict-column"          gint                  : Read / Write
  "restrict-model"           GdaDataModel          : Read / Write
  "simple-bind"              GdaParameter          : Read / Write
  "use-default-value"        gboolean              : Read / Write

Signals


  "restrict-changed"                               : Run First

Description

A GdaParameter object basically is a specification for a value and can convey a value once one has been set.

The GdaParameter object offers other features such as:

  • keeping a list of objects which "are interested" (mentioned as "users" in the API) in the value placed in the parameter: this feature is usefull when parameters are created by objects and when these objects want to be reminded that the parameter has been created by them at a later time

  • aliasing (binding) to another parameter: this is an easy way to keep several parameters synchronized. There are two modes: one where parameters A and B will always have the same value and where parameter B will update itself whan A changes to mirror tha change but will be allowed to have its own changes afterwards.

  • values restrictions: a parameter can be told to choose a value among the values in a colmun in a GdaDataModel (beware that this is a declarative feature only and that no policy is enforced regarding values changes)

Details

GdaParameter

typedef struct _GdaParameter GdaParameter;


gda_parameter_new ()

GdaParameter*       gda_parameter_new                   (GType type);

Creates a new parameter of type type

type : the GType requested
Returns : a new GdaParameter object

gda_parameter_new_copy ()

GdaParameter*       gda_parameter_new_copy              (GdaParameter *orig);

Copy constructor.

orig : a GdaParameter object to copy
Returns : a new GdaParameter object

gda_parameter_new_string ()

GdaParameter*       gda_parameter_new_string            (const gchar *name,
                                                         const gchar *str);

Creates a new GdaParameter object of type G_TYPE_STRING

name : the name of the parameter to create
str : the contents of the parameter to create
Returns : a new GdaParameter object

gda_parameter_new_boolean ()

GdaParameter*       gda_parameter_new_boolean           (const gchar *name,
                                                         gboolean value);

Creates a new GdaParameter object of type G_TYPE_BOOLEAN

name : the name of the parameter to create
value : the value to give to the new parameter
Returns : a new GdaParameter object

gda_parameter_get_g_type ()

GType               gda_parameter_get_g_type            (GdaParameter *param);

Get the requested data type for param.

param : a GdaParameter object
Returns : the data type

gda_parameter_get_value ()

const GValue*       gda_parameter_get_value             (GdaParameter *param);

Get the value held into the parameter

param : a GdaParameter object
Returns : the value (a NULL value returns a GDA_TYPE_NULL GValue)

gda_parameter_get_value_str ()

gchar*              gda_parameter_get_value_str         (GdaParameter *param);

Get a string representation of the value stored in param. Calling gda_parameter_set_value_str() with this value will restore param's current state.

param : a GdaParameter object
Returns : a new string, or NULL if param's value is NULL

gda_parameter_set_value ()

void                gda_parameter_set_value             (GdaParameter *param,
                                                         const GValue *value);

param :
value :

gda_parameter_set_value_str ()

gboolean            gda_parameter_set_value_str         (GdaParameter *param,
                                                         const gchar *value);

Same function as gda_parameter_set_value() except that the value is provided as a string, and may return FALSE if the string did not represent a correct value for the data type of the parameter.

param : a GdaParameter object
value : a value to set the parameter to, as a string
Returns : TRUE if no error occurred

gda_parameter_get_alphanum_name ()

gchar*              gda_parameter_get_alphanum_name     (GdaParameter *param);

Get an "encoded" version of param's name. The "encoding" consists in replacing non alphanumeric character with the string "__gdaXX" where XX is the hex. representation of the non alphanumeric char.

This method is just a wrapper around the gda_text_to_alphanum() function.

param : a GdaParameter object
Returns : a new string

gda_parameter_declare_invalid ()

void                gda_parameter_declare_invalid       (GdaParameter *param);

Forces a parameter to be invalid; to set it valid again, a new value must be assigned to it using gda_parameter_set_value().

param : a GdaParameter object

gda_parameter_is_valid ()

gboolean            gda_parameter_is_valid              (GdaParameter *param);

Get the validity of param (that is, of the value held by param)

param : a GdaParameter object
Returns : TRUE if param's value can safely be used

gda_parameter_get_default_value ()

const GValue*       gda_parameter_get_default_value     (GdaParameter *param);

Get the default value held into the parameter. WARNING: the default value does not need to be of the same type as the one required by param.

param : a GdaParameter object
Returns : the default value

gda_parameter_set_default_value ()

void                gda_parameter_set_default_value     (GdaParameter *param,
                                                         const GValue *value);

param :
value :

gda_parameter_get_exists_default_value ()

gboolean            gda_parameter_get_exists_default_value
                                                        (GdaParameter *param);

param : a GdaParameter object
Returns : TRUE if param has a default value (which may be unspecified)

gda_parameter_set_exists_default_value ()

void                gda_parameter_set_exists_default_value
                                                        (GdaParameter *param,
                                                         gboolean default_value_exists);

Tells if param has default unspecified value. This function is usefull if one wants to inform that param has a default value but does not know what that default value actually is.

param :
default_value_exists :

gda_parameter_set_not_null ()

void                gda_parameter_set_not_null          (GdaParameter *param,
                                                         gboolean not_null);

Sets if the parameter can have a NULL value. If not_null is TRUE, then that won't be allowed

param : a GdaParameter object
not_null :

gda_parameter_get_not_null ()

gboolean            gda_parameter_get_not_null          (GdaParameter *param);

Get wether the parameter can be NULL or not

param : a GdaParameter object
Returns : TRUE if the parameter cannot be NULL

gda_parameter_restrict_values ()

gboolean            gda_parameter_restrict_values       (GdaParameter *param,
                                                         GdaDataModel *model,
                                                         gint col,
                                                         GError **error);

Sets a limit on the possible values for the param parameter: the value must be among the values contained in the col column of the model data model.

param : a GdaParameter object
model : a GdaDataModel object or NULL
col : the reference column in model
error : location to store error, or NULL
Returns : TRUE if no error occurred

gda_parameter_has_restrict_values ()

gboolean            gda_parameter_has_restrict_values   (GdaParameter *param,
                                                         GdaDataModel **model,
                                                         gint *col);

Tells if param has its values restricted by a GdaDataModel, and optionnaly allows to fetch the resteictions.

param : a GdaParameter
model : a place to store a pointer to the model restricting the parameter, or NULL
col : a place to store the column in the model restricting the parameter, or NULL
Returns : TRUE if param has its values restricted.

gda_parameter_bind_to_param ()

void                gda_parameter_bind_to_param         (GdaParameter *param,
                                                         GdaParameter *bind_to);

Sets param to change when bind_to changes (and does not make bind_to change when param changes)

param : a GdaParameter
bind_to : a GdaParameter or NULL

gda_parameter_get_bind_param ()

GdaParameter*       gda_parameter_get_bind_param        (GdaParameter *param);

Get the parameter which makes param change its value when the param's value is changed.

param : a GdaParameter
Returns : the GdaParameter or NULL

Property Details

The "entry-plugin" property

  "entry-plugin"             gchararray            : Read / Write

Default value: NULL


The "full-bind" property

  "full-bind"                GdaParameter          : Read / Write


The "g-type" property

  "g-type"                   gulong                : Read / Write / Construct Only


The "not-null" property

  "not-null"                 gboolean              : Read / Write

Default value: FALSE


The "restrict-column" property

  "restrict-column"          gint                  : Read / Write

Allowed values: >= 0

Default value: 0


The "restrict-model" property

  "restrict-model"           GdaDataModel          : Read / Write


The "simple-bind" property

  "simple-bind"              GdaParameter          : Read / Write


The "use-default-value" property

  "use-default-value"        gboolean              : Read / Write

Default value: FALSE

Signal Details

The "restrict-changed" signal

void                user_function                      (GdaParameter *gdaparameter,
                                                        gpointer      user_data)         : Run First

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