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);
void                gda_holder_set_attribute            (GdaHolder *holder,
                                                         const gchar *attribute,
                                                         const GValue *value);

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

id :

str :


gda_holder_new_boolean()

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

id :

abool :


gda_holder_new_int()

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

id :

anint :


gda_holder_new_inline ()

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

Creates a new GdaHolder object named name, 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 :


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 a limit on the possible values for the holder holder: the value must be among the values contained in the col column of the model data model.

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

Tells if holder has its values sourceed by a GdaDataModel, and optionnaly allows to fetch the resteictions.

holder :

a GdaHolder

col :

a place to store the column in the model sourceing the holder, or NULL

Returns :

a pointer to the GdaDataModel source for holder

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 :

Returns :


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

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

Set the value associated to a named attribute.

Attributes can have any name, but Libgda proposes some default names, see this section. If there is already an attribute named attribute set, then its value is replaced with the new value, except if value is NULL, in which case the attribute is removed.

Warning: sttribute should be a static string (no copy of it is made), so the string should exist as long as the holder object exists.

holder :

a GdaHolder

attribute :

attribute name as a static string

value :

a GValue, or NULL

Property Details

The "description" property

  "description"              gchar*                : Read / Write

Default value: NULL


The "full-bind" property

  "full-bind"                GdaHolder*            : Read / Write


The "g-type" property

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


The "id" property

  "id"                       gchar*                : Read / Write

Default value: NULL


The "name" property

  "name"                     gchar*                : Read / Write

Default value: NULL


The "not-null" property

  "not-null"                 gboolean              : Read / Write

Default value: FALSE


The "simple-bind" property

  "simple-bind"              GdaHolder*            : Read / Write


The "source-column" property

  "source-column"            gint                  : Read / Write

Allowed values: >= 0

Default value: 0


The "source-model" property

  "source-model"             GdaDataModel*         : Read / Write

Signal Details

The "attribute-changed" signal

void                user_function                      (GdaHolder *gdaholder,
                                                        gchar     *arg1,
                                                        GValue    *arg2,
                                                        gpointer   user_data)      : Run First

gdaholder :

the object which received the signal.

arg1 :

arg2 :

user_data :

user data set when the signal handler was connected.

The "changed" signal

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

gdaholder :

the object which received the signal.

user_data :

user data set when the signal handler was connected.

The "source-changed" signal

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

gdaholder :

the object which received the signal.

user_data :

user data set when the signal handler was connected.

The "validate-change" signal

GdaError*           user_function                      (GdaHolder *gdaholder,
                                                        GValue    *arg1,
                                                        gpointer   user_data)      : Run Last

gdaholder :

the object which received the signal.

arg1 :

user_data :

user data set when the signal handler was connected.

Returns :