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

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

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

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

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

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

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

`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`
Returns : | the value, or `NULL`

### 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`
`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 chaged 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
`error` : | a place to store errors, or `NULL`
Returns : | TRUE if value has been set

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

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

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

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`

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