## MgParameter

MgParameter — Represents a parameter when needed to execute a query

## Synopsis

    struct      MgParameter;
    guint       mg_parameter_get_type           (void);
    GObject*    mg_parameter_new                (MgConf *conf,
                                                 MgServerDataType *type);
    GObject*    mg_parameter_new_copy           (MgParameter *orig);
    GObject*    mg_parameter_new_with_dest_field
                                                (MgQfield *field,
                                                 MgServerDataType *type);
    void        mg_parameter_add_dest_field     (MgParameter *param,
                                                 MgQfield *field);
    GSList*     mg_parameter_get_dest_fields    (MgParameter *param);
    MgServerDataType* mg_parameter_get_data_type
                                                (MgParameter *param);
    const GdaValue* mg_parameter_get_value      (MgParameter *param);
    void        mg_parameter_set_value          (MgParameter *param,
                                                 const GdaValue *value);
    void        mg_parameter_declare_invalid    (MgParameter *param);
    gboolean    mg_parameter_is_valid           (MgParameter *param);
    const GdaValue* mg_parameter_get_default_value
                                                (MgParameter *param);
    void        mg_parameter_set_default_value  (MgParameter *param,
                                                 const GdaValue *value);
    void        mg_parameter_set_not_null       (MgParameter *param,
                                                 gboolean not_null);
    gboolean    mg_parameter_get_not_null       (MgParameter *param);
    gboolean    mg_parameter_set_source_field   (MgParameter *param,
                                                 MgQfield *field,
                                                 GError **error);
    MgQfield*   mg_parameter_get_source_field   (MgParameter *param);
    void        mg_parameter_add_dependency     (MgParameter *param,
                                                 MgParameter *depend_on);
    void        mg_parameter_del_dependency     (MgParameter *param,
                                                 MgParameter *depend_on);
    GSList*     mg_parameter_get_dependencies   (MgParameter *param);
    void        mg_parameter_replace_ref        (MgParameter *param,
                                                 GHashTable *replacements);
    void        mg_parameter_bind_to_param      (MgParameter *param,
                                                 MgParameter *bind_to);
    MgParameter* mg_parameter_get_bind_param    (MgParameter *param);
    gboolean    mg_parameter_requires_user_input
                                                (MgParameter *param);
    void        mg_parameter_set_user_input_required
                                                (MgParameter *param,
                                                 gboolean input_required);

## Object Hierarchy

      GObject
       +----MgBase
             +----MgParameter

## Implemented Interfaces

MgParameter implements MgReferer.

## Properties

      "full-bind"            gpointer             : Read / Write
      "handler-plugin"       gchararray           : Read / Write
      "simple-bind"          gpointer             : Read / Write
      "use-default-value"    gboolean             : Read / Write

## Description

A MgParameter object basically conveys a value (as a GdaValue) and several attributes specifying the value itself.

Parameters are usually used in conjunction with queries when they are required before the queries can be executed, but they can also be created by hand when a value is requested from the user.

Also a parameter can be set to an alias of another parameter, in which case that parameter and the one of which it is an alias will always be synchronized regarding their value and attributes. This feature is usefull when a parameter required by a query needs to be synchronized to an already existing parameter.

## Details

### struct MgParameter

    struct MgParameter;

### mg_parameter_get_type ()

    guint       mg_parameter_get_type           (void);

Returns : |

### mg_parameter_new ()

    GObject*    mg_parameter_new                (MgConf *conf,
                                                 MgServerDataType *type);

Creates a new parameter of type `type`

`conf` : | a MgConf object
`type` : | the MgServerDataType requested
Returns : | a new MgParameter object

### mg_parameter_new_copy ()

    GObject*    mg_parameter_new_copy           (MgParameter *orig);

Copy constructor.

`orig` : | a MgParameter object to copy
Returns : | a new MgParameter object

### mg_parameter_new_with_dest_field ()

    GObject*    mg_parameter_new_with_dest_field
                                                (MgQfield *field,
                                                 MgServerDataType *type);

Creates a new parameter to be passed to `field` for the operations where a parameter is required; other MgQfield can also be added by using the `mg_parameter_add_dest_field()` method.

`field` : | the MgQfield object the parameter is for
`type` : | the MgServerDataType requested
Returns : | a new MgParameter object

### mg_parameter_add_dest_field ()

    void        mg_parameter_add_dest_field     (MgParameter *param,
                                                 MgQfield *field);

Adds a MgQfield object for which the parameter is for

`param` : | a MgParameter object
`field` : | the MgQfield object the parameter is for

### mg_parameter_get_dest_fields ()

    GSList*     mg_parameter_get_dest_fields    (MgParameter *param);

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

`param` : | a MgParameter object
Returns : | the list of MgQfield object

### mg_parameter_get_data_type ()

    MgServerDataType* mg_parameter_get_data_type
                                                (MgParameter *param);

Get the requested data type for `param`.

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

### mg_parameter_get_value ()

    const GdaValue* mg_parameter_get_value      (MgParameter *param);

Get the value held into the parameter

`param` : | a MgParameter object
Returns : | the value (a NULL value returns a GDA_VALUE_TYPE_NULL GdaValue)

### mg_parameter_set_value ()

    void        mg_parameter_set_value          (MgParameter *param,
                                                 const GdaValue *value);

`param` : |
`value` : |

### mg_parameter_declare_invalid ()

    void        mg_parameter_declare_invalid    (MgParameter *param);

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

`param` : | a MgParameter object

### mg_parameter_is_valid ()

    gboolean    mg_parameter_is_valid           (MgParameter *param);

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

`param` : | a MgParameter object
Returns : | TRUE if `param`'s value can safely be used

### mg_parameter_get_default_value ()

    const GdaValue* mg_parameter_get_default_value
                                                (MgParameter *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 MgParameter object
Returns : | the default value

### mg_parameter_set_default_value ()

    void        mg_parameter_set_default_value  (MgParameter *param,
                                                 const GdaValue *value);

`param` : |
`value` : |

### mg_parameter_set_not_null ()

    void        mg_parameter_set_not_null       (MgParameter *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 MgParameter object
`not_null` : |

### mg_parameter_get_not_null ()

    gboolean    mg_parameter_get_not_null       (MgParameter *param);

Get wether the parameter can be NULL or not

`param` : | a MgParameter object
Returns : | TRUE if the parameter cannot be NULL

### mg_parameter_set_source_field ()

    gboolean    mg_parameter_set_source_field   (MgParameter *param,
                                                 MgQfield *field,
                                                 GError **error);

Sets a limit on the possible values for the `param` parameter: they must be among the values of `field` when the SELECT query to which `field` belongs is executed. `field` must be of the same type as the requested type for `param`.

`field` is not copied, just referenced (maybe it'd better to make a copy of it...)

`param` : | a MgParameter object
`field` : | a MgQfield object or NULL
`error` : | location to store error, or `NULL`
Returns : | TRUE if no error occurred

### mg_parameter_get_source_field ()

    MgQfield*   mg_parameter_get_source_field   (MgParameter *param);

`param` : |
Returns : |

### mg_parameter_add_dependency ()

    void        mg_parameter_add_dependency     (MgParameter *param,
                                                 MgParameter *depend_on);

Tell `param` that its value will depend on the value of `depend_on`

`param` : | a MgParameter object
`depend_on` : | a MgParameter object

### mg_parameter_del_dependency ()

    void        mg_parameter_del_dependency     (MgParameter *param,
                                                 MgParameter *depend_on);

Remove the `depend_on` dependency from `param`

`param` : | a MgParameter object
`depend_on` : | a MgParameter object

### mg_parameter_get_dependencies ()

    GSList*     mg_parameter_get_dependencies   (MgParameter *param);

Get the list of MgParameter `param` depends on

`param` : | a MgParameter object
Returns : | the list of parameters

### mg_parameter_replace_ref ()

    void        mg_parameter_replace_ref        (MgParameter *param,
                                                 GHashTable *replacements);

Replace references to some objects by references to some other objects, as listed in `replacements`.

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

### mg_parameter_bind_to_param ()

    void        mg_parameter_bind_to_param      (MgParameter *param,
                                                 MgParameter *bind_to);

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

`param` : | a MgParameter
`bind_to` : | a MgParameter or `NULL`

### mg_parameter_get_bind_param ()

    MgParameter* mg_parameter_get_bind_param    (MgParameter *param);

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

`param` : | a MgParameter
Returns : | the MgParameter or `NULL`

### mg_parameter_requires_user_input ()

    gboolean    mg_parameter_requires_user_input
                                                (MgParameter *param);

Tells if the parameter is configured in a way that even if there is a value, it requires that the user at least validates that value, or change it.

`param` : | a MgParameter
Returns : | TRUE if user input is required

### mg_parameter_set_user_input_required ()

    void        mg_parameter_set_user_input_required
                                                (MgParameter *param,
                                                 gboolean input_required);

Sets if the user input is required for `param` (even though it may already have a value) and be valid.

`param` : | a MgParameter
`input_required` : |

## Properties

"`full-bind`" (gpointer : Read / Write) |
"`handler-plugin`" (gchararray : Read / Write) |
"`simple-bind`" (gpointer : Read / Write) |
"`use-default-value`" (gboolean : Read / Write) |