GdaParameter

## GdaParameter GdaParameter — Represents a GdaValue with various attributes |

## Synopsis

                GdaParameter;
    GdaParameter* gda_parameter_new             (GdaValueType 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);
    GdaValueType gda_parameter_get_gda_type     (GdaParameter *param);
    void        gda_parameter_declare_param_user
                                                (GdaParameter *param,
                                                 GdaObject *user);
    GSList*     gda_parameter_get_param_users   (GdaParameter *param);
    const GdaValue* gda_parameter_get_value     (GdaParameter *param);
    void        gda_parameter_set_value         (GdaParameter *param,
                                                 const GdaValue *value);
    gboolean    gda_parameter_set_value_str     (GdaParameter *param,
                                                 const gchar *value);
    void        gda_parameter_declare_invalid   (GdaParameter *param);
    gboolean    gda_parameter_is_valid          (GdaParameter *param);
    const GdaValue* gda_parameter_get_default_value
                                                (GdaParameter *param);
    void        gda_parameter_set_default_value (GdaParameter *param,
                                                 const GdaValue *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_replace_param_users
                                                (GdaParameter *param,
                                                 GHashTable *replacements);
    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

      "full-bind"            gpointer              : Read / Write
      "gda-type"             gint                  : Read / Write / Construct Only
      "handler-plugin"       gchararray            : Read / Write
      "restrict-column"      gint                  : Read / Write
      "restrict-model"       gpointer              : Read / Write
      "simple-bind"          gpointer              : Read / Write
      "use-default-value"    gboolean              : Read / Write

## Signal Prototypes

    "restrict-changed"
                void        user_function      (GdaParameter *gdaparameter,
                                                gpointer user_data);

## 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             (GdaValueType type);

Creates a new parameter of type `type`

`type` : | the GdaValueType 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 GDA_VALUE_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 GDA_VALUE_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_gda_type ()

    GdaValueType gda_parameter_get_gda_type     (GdaParameter *param);

Get the requested data type for `param`.

`param` : | a GdaParameter object
Returns : | the data type

### gda_parameter_declare_param_user ()

    void        gda_parameter_declare_param_user
                                                (GdaParameter *param,
                                                 GdaObject *user);

Tells that `user` is potentially using `param`.

`param` : | a GdaParameter object
`user` : | the GdaObject object using that parameter for

### gda_parameter_get_param_users ()

    GSList*     gda_parameter_get_param_users   (GdaParameter *param);

Get the GdaEntityField objects which created `param` (and which will use its value)

`param` : | a GdaParameter object
Returns : | the list of GdaEntityField object; it must not be changed or free'd

### gda_parameter_get_value ()

    const GdaValue* 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_VALUE_TYPE_NULL GdaValue)

### gda_parameter_set_value ()

    void        gda_parameter_set_value         (GdaParameter *param,
                                                 const GdaValue *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 occured

### 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 GdaValue* 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 GdaValue *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_replace_param_users ()

    void        gda_parameter_replace_param_users
                                                (GdaParameter *param,
                                                 GHashTable *replacements);

For each declared parameter user in the `replacements` keys, declare the value stored in `replacements` also as a user of `param`.

`param` : | a GdaParameter object
`replacements` : | the (objects to be replaced, replacing object) pairs

### 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`

## Properties

### The "`full-bind`" property

      "full-bind"            gpointer              : Read / Write

### The "`gda-type`" property

      "gda-type"             gint                  : Read / Write / Construct Only

Allowed values: >= 0

Default value: 24

### The "`handler-plugin`" property

      "handler-plugin"       gchararray            : Read / Write

Default value: NULL

### The "`restrict-column`" property

      "restrict-column"      gint                  : Read / Write

Allowed values: >= 0

Default value: 0

### The "`restrict-model`" property

      "restrict-model"       gpointer              : Read / Write

### The "`simple-bind`" property

      "simple-bind"          gpointer              : Read / Write

### The "`use-default-value`" property

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

Default value: FALSE

## Signals

### The "restrict-changed" signal

    void        user_function                  (GdaParameter *gdaparameter,
                                                gpointer user_data);

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