## 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);
    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_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.