## GdaHolder

GdaHolder — Container for a single GValue

## Synopsis

                        GdaHolder;
    GdaHolder *         gda_holder_new                      (GType type);
    #define             gda_holder_new_string               (id,
                                                             str)
    #define             gda_holder_new_boolean              (id,
                                                             abool)
    #define             gda_holder_new_int                  (id,
                                                             anint)
    GdaHolder *         gda_holder_new_inline               (GType type,
                                                             const gchar *id,
                                                             ...);
    GdaHolder *         gda_holder_copy                     (GdaHolder *orig);
    GType               gda_holder_get_g_type               (GdaHolder *holder);
    const gchar *       gda_holder_get_id                   (GdaHolder *holder);
    const GValue *      gda_holder_get_value                (GdaHolder *holder);
    gchar *             gda_holder_get_value_str            (GdaHolder *holder,
                                                             GdaDataHandler *dh);
    gboolean            gda_holder_set_value                (GdaHolder *holder,
                                                             const GValue *value,
                                                             GError **error);
    gboolean            gda_holder_set_value_str            (GdaHolder *holder,
                                                             GdaDataHandler *dh,
                                                             const gchar *value,
                                                             GError **error);
    gboolean            gda_holder_take_value               (GdaHolder *holder,
                                                             GValue *value,
                                                             GError **error);
    GValue *            gda_holder_take_static_value        (GdaHolder *holder,
                                                             const GValue *value,
                                                             gboolean *value_changed,
                                                             GError **error);
    const GValue *      gda_holder_get_default_value        (GdaHolder *holder);
    void                gda_holder_set_default_value        (GdaHolder *holder,
                                                             const GValue *value);
    gboolean            gda_holder_set_value_to_default     (GdaHolder *holder);
    gboolean            gda_holder_value_is_default         (GdaHolder *holder);
    void                gda_holder_force_invalid            (GdaHolder *holder);
    gboolean            gda_holder_is_valid                 (GdaHolder *holder);
    void                gda_holder_set_not_null             (GdaHolder *holder,
                                                             gboolean not_null);
    gboolean            gda_holder_get_not_null             (GdaHolder *holder);
    gboolean            gda_holder_set_source_model         (GdaHolder *holder,
                                                             GdaDataModel *model,
                                                             gint col,
                                                             GError **error);
    GdaDataModel *      gda_holder_get_source_model         (GdaHolder *holder,
                                                             gint *col);
    gboolean            gda_holder_set_bind                 (GdaHolder *holder,
                                                             GdaHolder *bind_to,
                                                             GError **error);
    GdaHolder *         gda_holder_get_bind                 (GdaHolder *holder);
    const GValue *      gda_holder_get_attribute            (GdaHolder *holder,
                                                             const gchar *attribute);
    #define             gda_holder_set_attribute_static     (holder,
                                                             attribute,
                                                             value)
    void                gda_holder_set_attribute            (GdaHolder *holder,
                                                             const gchar *attribute,
                                                             const GValue *value,
                                                             GDestroyNotify destroy);

## Object Hierarchy

      GObject
       +----GdaHolder

## Properties

      "description"              gchar*                : Read / Write
      "full-bind"                GdaHolder*            : Read / Write
      "g-type"                   GType*                : Read / Write / Construct
      "id"                       gchar*                : Read / Write
      "name"                     gchar*                : Read / Write
      "not-null"                 gboolean              : Read / Write
      "simple-bind"              GdaHolder*            : Read / Write
      "source-column"            gint                  : Read / Write
      "source-model"             GdaDataModel*         : Read / Write

## Signals

      "attribute-changed"                              : Run First
      "changed"                                        : Run First
      "source-changed"                                 : Run First
      "validate-change"                                : Run Last

## Description

The GdaHolder is a container for a single GValue value. It also specifies various attributes of the contained value (default value, ...)

The type of a GdaHolder has to be set and cannot be modified, except if it's initialized with a GDA_TYPE_NULL GType (representing NULL values) where it can be changed once to a real GType.

## Details

### GdaHolder

    typedef struct _GdaHolder GdaHolder;

### gda_holder_new ()

    GdaHolder *         gda_holder_new                      (GType type);

Creates a new holder of type `type`

`type` : | the GType requested. [transfer none]
Returns : | a new GdaHolder object

### gda_holder_new_string()

    #define gda_holder_new_string(id,str) gda_holder_new_inline (G_TYPE_STRING, (id), (str))

Creates a new boolean GdaHolder object with an ID set to `id`, and a value initialized to `str`.

`id` : | a string
`str` : | a string
Returns : | a new GdaHolder

### gda_holder_new_boolean()

    #define gda_holder_new_boolean(id,abool) gda_holder_new_inline (G_TYPE_BOOLEAN, (id), (abool))

Creates a new boolean GdaHolder object with an ID set to `id`, and a value initialized to `abool`.

`id` : | a string
`abool` : | a boolean value
Returns : | a new GdaHolder

### gda_holder_new_int()

    #define gda_holder_new_int(id,anint) gda_holder_new_inline (G_TYPE_INT, (id), (anint))

Creates a new boolean GdaHolder object with an ID set to `id`, and a value initialized to `anint`.

`id` : | a string
`anint` : | an int value
Returns : | a new GdaHolder

### gda_holder_new_inline ()

    GdaHolder *         gda_holder_new_inline               (GType type,
                                                             const gchar *id,
                                                             ...);

Creates a new GdaHolder object with an ID set to `id`, of type `type`, and containing the value passed as the last argument.

Note that this function is a utility function and that only a limited set of types are supported. Trying to use an unsupported type will result in a warning, and the returned value holder holding a safe default value.

`type` : | a valid GLib type
`id` : | the id of the holder to create, or `NULL`
`...` : | value to set
Returns : | a new GdaHolder object

### gda_holder_copy ()

    GdaHolder *         gda_holder_copy                     (GdaHolder *orig);

Copy constructor.

Note1: if `orig` is set with a static value (see `gda_holder_take_static_value()`) its copy will have a fresh new allocated GValue, so that user should free it when done.

`orig` : | a GdaHolder object to copy
Returns : | a new GdaHolder object. [transfer full]

### gda_holder_get_g_type ()

    GType               gda_holder_get_g_type               (GdaHolder *holder);

Get `holder`'s type

`holder` : | a GdaHolder object
Returns : | the data type. [transfer none]

### gda_holder_get_id ()

    const gchar *       gda_holder_get_id                   (GdaHolder *holder);

Get the ID of `holder`. The ID can be set using `holder`'s "id" property

`holder` : | a GdaHolder object
Returns : | the ID (don't modify the string).

### gda_holder_get_value ()

    const GValue *      gda_holder_get_value                (GdaHolder *holder);

Get the value held into the holder. If `holder` is set to use its default value and that default value is not of the same type as `holder`, then `NULL` is returned.

If `holder` is set to NULL, then the returned value is a GDA_TYPE_NULL GValue.

If `holder` is invalid, then the returned value is `NULL`.

`holder` : | a GdaHolder object
Returns : | the value, or `NULL`

### gda_holder_get_value_str ()

    gchar *             gda_holder_get_value_str            (GdaHolder *holder,
                                                             GdaDataHandler *dh);

Same functionality as `gda_holder_get_value()` except that it returns the value as a string (the conversion is done using `dh` if not `NULL`, or the default data handler otherwise).

`holder` : | a GdaHolder object
`dh` : | a GdaDataHandler to use, or `NULL`. [allow-none]
Returns : | the value, or `NULL`. [transfer full]

### gda_holder_set_value ()

    gboolean            gda_holder_set_value                (GdaHolder *holder,
                                                             const GValue *value,
                                                             GError **error);

Sets the value within the holder. If `holder` is an alias for another holder, then the value is also set for that other holder.

On success, the action of any call to `gda_holder_force_invalid()` is cancelled as soon as this method is called (even if `holder`'s value does not actually change)

If the value is not different from the one already contained within `holder`, then `holder` is not changed and no signal is emitted.

Note1: the `value` argument is treated the same way if it is `NULL` or if it is a GDA_TYPE_NULL value

Note2: if `holder` can't accept the `value` value, then this method returns FALSE, and `holder` will be left in an invalid state.

Note3: before the change is accepted by `holder`, the "validate-change" signal will be emitted (the value of which can prevent the change from happening) which can be connected to to have a greater control of which values `holder` can have, or implement some business rules.

`holder` : | a GdaHolder object
`value` : | a value to set the holder to, or `NULL`. [allow-none]
`error` : | a place to store errors, or `NULL`
Returns : | TRUE if value has been set

### gda_holder_set_value_str ()

    gboolean            gda_holder_set_value_str            (GdaHolder *holder,
                                                             GdaDataHandler *dh,
                                                             const gchar *value,
                                                             GError **error);

Same functionality as `gda_holder_set_value()` except that it uses a string representation of the value to set, which will be converted into a GValue first (using default data handler if `dh` is `NULL`).

Note1: if `value` is `NULL` or is the "NULL" string, then `holder`'s value is set to `NULL`. Note2: if `holder` can't accept the `value` value, then this method returns FALSE, and `holder` will be left in an invalid state.

`holder` : | a GdaHolder object
`dh` : | a GdaDataHandler to use, or `NULL`
`value` : | a value to set the holder to, as a string
`error` : | a place to store errors, or `NULL`
Returns : | TRUE if value has been set

### gda_holder_take_value ()

    gboolean            gda_holder_take_value               (GdaHolder *holder,
                                                             GValue *value,
                                                             GError **error);

Sets the value within the holder. If `holder` is an alias for another holder, then the value is also set for that other holder.

On success, the action of any call to `gda_holder_force_invalid()` is cancelled as soon as this method is called (even if `holder`'s value does not actually change).

If the value is not different from the one already contained within `holder`, then `holder` is not changed and no signal is emitted.

Note1: if `holder` can't accept the `value` value, then this method returns FALSE, and `holder` will be left in an invalid state.

Note2: before the change is accepted by `holder`, the "validate-change" signal will be emitted (the value of which can prevent the change from happening) which can be connected to to have a greater control of which values `holder` can have, or implement some business rules.

Note3: if user previously set this holder with `gda_holder_take_static_value()` the GValue stored internally will be forgiven and replaced by the `value`. User should then take care of the 'old' static GValue.

`holder` : | a GdaHolder object
`value` : | a value to set the holder to. [transfer full]
`error` : | a place to store errors, or `NULL`
Returns : | TRUE if value has been set

### gda_holder_take_static_value ()

    GValue *            gda_holder_take_static_value        (GdaHolder *holder,
                                                             const GValue *value,
                                                             gboolean *value_changed,
                                                             GError **error);

Sets the const value within the holder. If `holder` is an alias for another holder, then the value is also set for that other holder.

The value will not be freed, and user should take care of it, either for its freeing or for its correct value at the moment of query.

If the value is not different from the one already contained within `holder`, then `holder` is not changed and no signal is emitted.

Note1: if `holder` can't accept the `value` value, then this method returns NULL, and `holder` will be left in an invalid state.

Note2: before the change is accepted by `holder`, the "validate-change" signal will be emitted (the value of which can prevent the change from happening) which can be connected to to have a greater control of which values `holder` can have, or implement some business rules.

`holder` : | a GdaHolder object
`value` : | a const value to set the holder to
`value_changed` : | a boolean set with TRUE if the value changes, FALSE elsewhere.
`error` : | a place to store errors, or `NULL`
Returns : | NULL if an error occurred or if the previous GValue was NULL itself. It returns the static GValue user set previously, so that he can free it. [transfer none]

### gda_holder_get_default_value ()

    const GValue *      gda_holder_get_default_value        (GdaHolder *holder);

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

`holder` : | a GdaHolder object
Returns : | the default value

### gda_holder_set_default_value ()

    void                gda_holder_set_default_value        (GdaHolder *holder,
                                                             const GValue *value);

Sets the default value within the holder. If `value` is `NULL` then `holder` won't have a default value anymore. To set a default value to `NULL`, then pass a GValue created using `gda_value_new_null()`.

NOTE: the default value does not need to be of the same type as the one required by `holder`.

`holder` : | a GdaHolder object
`value` : | a value to set the holder's default value, or `NULL`

### gda_holder_set_value_to_default ()

    gboolean            gda_holder_set_value_to_default     (GdaHolder *holder);

Set `holder`'s value to its default value.

`holder` : | a GdaHolder object
Returns : | TRUE if `holder` has got a default value

### gda_holder_value_is_default ()

    gboolean            gda_holder_value_is_default         (GdaHolder *holder);

Tells if `holder`'s current value is the default one.

`holder` : | a GdaHolder object
Returns : | TRUE if `holder` `holder`'s current value is the default one

### gda_holder_force_invalid ()

    void                gda_holder_force_invalid            (GdaHolder *holder);

Forces a holder to be invalid; to set it valid again, a new value must be assigned to it using `gda_holder_set_value()` or `gda_holder_take_value()`.

`holder`'s value is set to `NULL`.

`holder` : | a GdaHolder object

### gda_holder_is_valid ()

    gboolean            gda_holder_is_valid                 (GdaHolder *holder);

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

`holder` : | a GdaHolder object
Returns : | TRUE if `holder`'s value can safely be used

### gda_holder_set_not_null ()

    void                gda_holder_set_not_null             (GdaHolder *holder,
                                                             gboolean not_null);

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

`holder` : | a GdaHolder object
`not_null` : | TRUE if `holder` should not accept `NULL` values

### gda_holder_get_not_null ()

    gboolean            gda_holder_get_not_null             (GdaHolder *holder);

Get wether the holder can be NULL or not

`holder` : | a GdaHolder object
Returns : | TRUE if the holder cannot be NULL

### gda_holder_set_source_model ()

    gboolean            gda_holder_set_source_model         (GdaHolder *holder,
                                                             GdaDataModel *model,
                                                             gint col,
                                                             GError **error);

Sets an hint that `holder`'s values should be restricted among the values contained in the `col` column of the `model` data model. Note that this is just a hint, meaning this policy is not enforced by `holder`'s implementation.

If `model` is `NULL`, then the effect is to cancel ant previous call to `gda_holder_set_source_model()` where `model` was not `NULL`.

`holder` : | a GdaHolder 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_holder_get_source_model ()

    GdaDataModel *      gda_holder_get_source_model         (GdaHolder *holder,
                                                             gint *col);

If `gda_holder_set_source_model()` has been used to provide a hint that `holder`'s value should be among the values contained in a column of a data model, then this method returns which data model, and if `col` is not `NULL`, then it is set to the restricting column as well.

Otherwise, this method returns `NULL`, and if `col` is not `NULL`, then it is set to 0.

`holder` : | a GdaHolder
`col` : | a place to store the column in the model sourcing the holder, or `NULL`
Returns : | a pointer to a GdaDataModel, or `NULL`. [transfer none]

### gda_holder_set_bind ()

    gboolean            gda_holder_set_bind                 (GdaHolder *holder,
                                                             GdaHolder *bind_to,
                                                             GError **error);

Sets `holder` to change when `bind_to` changes (and does not make `bind_to` change when `holder` changes). For the operation to succeed, the GType of `holder` and `bind_to` must be the same, with the exception that any of them can have a `GDA_TYPE_NULL` type (in this situation, the GType of the two GdaHolder objects involved is set to match the other when any of them sets its type to something different than GDA_TYPE_NULL).

If `bind_to` is `NULL`, then `holder` will not be bound anymore.

`holder` : | a GdaHolder
`bind_to` : | a GdaHolder or `NULL`
`error` : | a place to store errors, or `NULL`
Returns : | TRUE if no error occurred

### gda_holder_get_bind ()

    GdaHolder *         gda_holder_get_bind                 (GdaHolder *holder);

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

`holder` : | a GdaHolder
Returns : | the GdaHolder or `NULL`. [transfer none]

### gda_holder_get_attribute ()

    const GValue *      gda_holder_get_attribute            (GdaHolder *holder,
                                                             const gchar *attribute);

Get the value associated to a named attribute.

Attributes can have any name, but Libgda proposes some default names, see this section.

`holder` : | a GdaHolder
`attribute` : | attribute name as a string
Returns : | a read-only GValue, or `NULL` if not attribute named `attribute` has been set for `holder`

### gda_holder_set_attribute_static()

    #define gda_holder_set_attribute_static(holder,attribute,value) gda_holder_set_attribute((holder),(attribute),(value),NULL)

This function is similar to `gda_holder_set_attribute()` but for static strings

`holder` : | a GdaHolder
`attribute` : | attribute's name
`value` : | a GValue, or `NULL`

### gda_holder_set_attribute ()

    void                gda_holder_set_attribute            (GdaHolder *holder,
                                                             const gchar *attribute,
                                                             const GValue *value,
                                                             GDestroyNotify destroy);

Set the value associated to a named attribute. The `attribute` string is 'stolen' by this method, and the memory it uses will be freed using the `destroy` function when no longer needed (if `destroy` is `NULL`, then the string will not be freed at all).

Attributes can have any name, but Libgda proposes some default names, see this section.

For example one would use it as:

`gda_holder_set_attribute (holder, g_strdup (my_attribute), g_free, my_value); gda_holder_set_attribute (holder, GDA_ATTRIBUTE_NAME, NULL, my_value);`

If there is already an attribute named `attribute` set, then its value is replaced with the new value (`value` is copied), except if `value` is `NULL`, in which case the attribute is removed.

`holder` : | a GdaHolder
`attribute` : | attribute name
`value` : | a GValue, or `NULL`
`destroy` : | a function to be called when `attribute` is not needed anymore, or `NULL`

## Property Details

### The `"description"` property

      "description"              gchar*                : Read / Write

Holder's description.

Default value: NULL

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

      "full-bind"                GdaHolder*            : Read / Write

Make value holder follow other GdaHolder's changes and the other way around.

### The `"g-type"` property

      "g-type"                   GType*                : Read / Write / Construct

Holder's GType.

### The `"id"` property

      "id"                       gchar*                : Read / Write

Holder's ID.

Default value: NULL

### The `"name"` property

      "name"                     gchar*                : Read / Write

Holder's name.

Default value: NULL

### The `"not-null"` property

      "not-null"                 gboolean              : Read / Write

Can the value holder be NULL?.

Default value: FALSE

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

      "simple-bind"              GdaHolder*            : Read / Write

Make value holder follow other GdaHolder's changes.

### The `"source-column"` property

      "source-column"            gint                  : Read / Write

Column number to use in coordination with the source-model property.

Allowed values: >= 0

Default value: 0

### The `"source-model"` property

      "source-model"             GdaDataModel*         : Read / Write

Data model among which the holder's value should be.

## Signal Details

### The `"attribute-changed"` signal

    void                user_function                      (GdaHolder *holder,
                                                            gchar     *att_name,
                                                            GValue    *att_value,
                                                            gpointer   user_data)      : Run First

Gets emitted when any `holder`'s attribute has changed

`holder` : | the GdaHolder
`att_name` : | attribute's name
`att_value` : | attribute's value
`user_data` : | user data set when the signal handler was connected.

### The `"changed"` signal

    void                user_function                      (GdaHolder *holder,
                                                            gpointer   user_data)      : Run First

Gets emitted when `holder`'s value has changed

`holder` : | the GdaHolder
`user_data` : | user data set when the signal handler was connected.

### The `"source-changed"` signal

    void                user_function                      (GdaHolder *holder,
                                                            gpointer   user_data)      : Run First

Gets emitted when the data model in which `holder`'s values should be has changed

`holder` : | the GdaHolder
`user_data` : | user data set when the signal handler was connected.

### The `"validate-change"` signal

    GdaError*           user_function                      (GdaHolder *holder,
                                                            GValue    *new_value,
                                                            gpointer   user_data)      : Run Last

Gets emitted when `holder` is going to change its value. One can connect to this signal to control which values `holder` can have (for example to implement some business rules)

`holder` : | the object which received the signal
`new_value` : | the proposed new value for `holder`
`user_data` : | user data set when the signal handler was connected.
Returns : | NULL if `holder` is allowed to change its value to `new_value`, or a GError otherwise.