GdaHolder

GdaHolder — Container for a single GValue

Stability Level

Stable, unless otherwise indicated

Properties

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

Signals

void attribute-changed Run First
void changed Run First
void source-changed Run First
GError* validate-change Run Last

Types and Values

Object Hierarchy

    GObject
    ╰── GdaHolder

Implemented Interfaces

GdaHolder implements GdaLockable.

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.

Each GdaHolder object is thread safe.

Functions

gda_holder_new ()

GdaHolder *
gda_holder_new (GType type);

Creates a new holder of type type

Parameters

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 .

Parameters

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 .

Parameters

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 .

Parameters

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.

Parameters

type

a valid GLib type

 

id

the id of the holder to create, or NULL.

[allow-none]

...

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.

Parameters

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

Parameters

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

Parameters

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.

Parameters

holder

a GdaHolder object

 

Returns

the value, or NULL.

[allow-none][transfer none]


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

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.


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 .

Parameters

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 .

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

holder

a GdaHolder object

 

gda_holder_force_invalid_e ()

void
gda_holder_force_invalid_e (GdaHolder *holder,
                            GError *error);

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.

Parameters

holder

a GdaHolder object

 

error

a GError explaining why holder is declared invalid, or NULL.

[allow-none][transfer full]

Since 4.2.10


gda_holder_is_valid ()

gboolean
gda_holder_is_valid (GdaHolder *holder);

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

Parameters

holder

a GdaHolder object

 

Returns

TRUE if holder 's value can safely be used


gda_holder_is_valid_e ()

gboolean
gda_holder_is_valid_e (GdaHolder *holder,
                       GError **error);

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

Parameters

holder

a GdaHolder object

 

error

a place to store invalid error, or NULL.

[allow-none]

Returns

TRUE if holder 's value can safely be used

Since 4.2.10


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

Parameters

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

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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

Parameters

holder

a GdaHolder

 

attribute

attribute's name

 

value

a GValue, or NULL.

[allow-none]

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), my_value, g_free);gda_holder_set_attribute (holder, GDA_ATTRIBUTE_NAME, my_value, NULL);

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.

Parameters

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

 

Types and Values

GdaHolder

typedef struct _GdaHolder GdaHolder;

Property Details

The “description” property

  “description”              gchar *

Holder's description.

Flags: Read / Write

Default value: NULL


The “full-bind” property

  “full-bind”                GdaHolder *

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

Flags: Read / Write


The “g-type” property

  “g-type”                   GType *

Holder's GType.

Flags: Read / Write / Construct

Allowed values: void


The “id” property

  “id”                       gchar *

Holder's ID.

Flags: Read / Write

Default value: NULL


The “name” property

  “name”                     gchar *

Holder's name.

Flags: Read / Write

Default value: NULL


The “not-null” property

  “not-null”                 gboolean

Can the value holder be NULL?.

Flags: Read / Write

Default value: FALSE


The “simple-bind” property

  “simple-bind”              GdaHolder *

Make value holder follow other GdaHolder's changes.

Flags: Read / Write


The “source-column” property

  “source-column”            gint

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

Flags: Read / Write

Allowed values: >= 0

Default value: 0


The “source-model” property

  “source-model”             GdaDataModel *

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

Flags: Read / Write


The “validate-changes” property

  “validate-changes”         gboolean

Defines if the "validate-change" signal gets emitted when the holder's value changes.

Flags: Read / Write

Default value: TRUE

Since 5.2.0

Signal Details

The “attribute-changed” signal

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

Gets emitted when any holder 's attribute has changed

Parameters

holder

the GdaHolder

 

att_name

attribute's name

 

att_value

attribute's value

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First


The “changed” signal

void
user_function (GdaHolder *holder,
               gpointer   user_data)

Gets emitted when holder 's value has changed

Parameters

holder

the GdaHolder

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First


The “source-changed” signal

void
user_function (GdaHolder *holder,
               gpointer   user_data)

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

Parameters

holder

the GdaHolder

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First


The “validate-change” signal

GError*
user_function (GdaHolder *holder,
               GValue    *new_value,
               gpointer   user_data)

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)

Parameters

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.

Flags: Run Last

See Also

The GdaSet object which "groups" several GdaHolder objects