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"             gchar*                : 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);


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


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.


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

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"             gchar*                : 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.