GdaSet

GdaSet — Container for several values

Stability Level

Stable, unless otherwise indicated

Properties

gchar * description Read / Write
gpointer holders Write / Construct Only
gchar * id Read / Write
gchar * name Read / Write
gboolean validate-changes Read / Write

Signals

void holder-attr-changed Run First
void holder-changed Run First
void holder-type-set Run First
void public-data-changed Run First
void source-model-changed Run First
GError* validate-holder-change Run Last
GError* validate-set Run Last

Types and Values

Object Hierarchy

    GObject
    ╰── GdaSet
        ╰── GdaDataModelIter

Description

The GdaSet object is a container for several values (as GdaHolder objects). The list of GdaHolder objects is publicly accessible (and should not be modified), using the "holders" attribute. Each GdaSet object also maintains some publicly accessible information about the GdaHolder objects, through the GdaSetNode, GdaSetSource and GdaSetGroup structures (see gda_set_get_node(), gda_set_get_source() and gda_set_get_group()).

It is possible to control the values a GdaHolder can have in the GdaSet by connecting to the

"before-holder-change" signal.

Functions

gda_set_new ()

GdaSet *
gda_set_new (GSList *holders);

Creates a new GdaSet object, and populates it with the list given as argument. The list can then be freed as it is copied. All the value holders in holders are referenced counted and modified, so they should not be used anymore afterwards.

Parameters

holders

a list of GdaHolder objects.

[element-type Gda.Holder][transfer none]

Returns

a new GdaSet object


gda_set_new_read_only ()

GdaSet *
gda_set_new_read_only (GSList *holders);

Creates a new GdaSet like gda_set_new(), but does not allow modifications to any of the GdaHolder object in holders . This function is used for Libgda's database providers' implementation.

Parameters

holders

a list of GdaHolder objects.

[element-type Gda.Holder][transfer none]

Returns

a new GdaSet object

Since 4.2


gda_set_copy ()

GdaSet *
gda_set_copy (GdaSet *set);

Creates a new GdaSet object, copy of set

Parameters

set

a GdaSet object

 

Returns

a new GdaSet object.

[transfer full]


gda_set_new_inline ()

GdaSet *
gda_set_new_inline (gint nb,
                    ...);

Creates a new GdaSet containing holders defined by each triplet in ... For each triplet (id, Glib type and value), the value must be of the correct type (gchar * if type is G_STRING, ...)

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

nb

the number of value holders which will be contained in the new GdaSet

 

...

a serie of a (const gchar*) id, (GType) type, and value

 

Returns

a new GdaSet object.

[transfer full]


gda_set_new_from_spec_string ()

GdaSet *
gda_set_new_from_spec_string (const gchar *xml_spec,
                              GError **error);

Creates a new GdaSet object from the xml_spec specifications

Parameters

xml_spec

a string

 

error

a place to store the error, or NULL.

[allow-none]

Returns

a new object, or NULL if an error occurred.

[transfer full]


gda_set_new_from_spec_node ()

GdaSet *
gda_set_new_from_spec_node (xmlNodePtr xml_spec,
                            GError **error);

Creates a new GdaSet object from the xml_spec specifications

Parameters

xml_spec

a xmlNodePtr for a <parameters> tag

 

error

a place to store the error, or NULL.

[allow-none]

Returns

a new object, or NULL if an error occurred.

[transfer full]


gda_set_is_valid ()

gboolean
gda_set_is_valid (GdaSet *set,
                  GError **error);

This method tells if all set 's GdaHolder objects are valid, and if they represent a valid combination of values, as defined by rules external to Libgda: the "validate-set" signal is emitted and if none of the signal handlers return an error, then the returned value is TRUE, otherwise the return value is FALSE as soon as a signal handler returns an error.

Parameters

set

a GdaSet object

 

error

a place to store validation errors, or NULL.

[allow-none]

Returns

TRUE if the set is valid


gda_set_get_holder_value ()

const GValue *
gda_set_get_holder_value (GdaSet *set,
                          const gchar *holder_id);

Get the value of the GdaHolder which ID is holder_id

Parameters

set

a GdaSet object

 

holder_id

the ID of the holder to set the value

 

Returns

the requested GValue, or NULL (see gda_holder_get_value()).

[allow-none][transfer none]


gda_set_set_holder_value ()

gboolean
gda_set_set_holder_value (GdaSet *set,
                          GError **error,
                          const gchar *holder_id,
                          ...);

Set the value of the GdaHolder which ID is holder_id to a specified value

Parameters

set

a GdaSet object

 

error

a place to store errors, or NULL.

[allow-none]

holder_id

the ID of the holder to set the value

 

...

value, of the correct type, depending on the requested holder's type (not NULL)

 

Returns

TRUE if no error occurred and the value was set correctly


gda_set_get_holder ()

GdaHolder *
gda_set_get_holder (GdaSet *set,
                    const gchar *holder_id);

Finds a GdaHolder using its ID

Parameters

set

a GdaSet object

 

holder_id

the ID of the requested value holder

 

Returns

the requested GdaHolder or NULL.

[transfer none]


gda_set_get_nth_holder ()

GdaHolder *
gda_set_get_nth_holder (GdaSet *set,
                        gint pos);

Finds a GdaHolder using its position

Parameters

set

a GdaSet object

 

pos

the position of the requested GdaHolder, starting at 0

 

Returns

the requested GdaHolder or NULL.

[transfer none]

Since 4.2


gda_set_add_holder ()

gboolean
gda_set_add_holder (GdaSet *set,
                    GdaHolder *holder);

Adds holder to the list of holders managed within set .

NOTE: if set already has a GdaHolder with the same ID as holder , then holder will not be added to the set (even if holder 's type or value is not the same as the one already in set ).

Parameters

set

a GdaSet object

 

holder

a GdaHolder object

 

Returns

TRUE if holder has been added to set (and FALSE if it has not been added because there is another GdaHolder with the same ID)


gda_set_remove_holder ()

void
gda_set_remove_holder (GdaSet *set,
                       GdaHolder *holder);

Removes a GdaHolder from the list of holders managed by set

Parameters

set

a GdaSet object

 

holder

the GdaHolder to remove from set

 

gda_set_merge_with_set ()

void
gda_set_merge_with_set (GdaSet *set,
                        GdaSet *set_to_merge);

Add to set all the holders of set_to_merge . Note1: only the GdaHolder of set_to_merge for which no holder in set has the same ID are merged Note2: all the GdaHolder merged in set are still used by set_to_merge .

Parameters

set

a GdaSet object

 

set_to_merge

a GdaSet object

 

gda_set_replace_source_model ()

void
gda_set_replace_source_model (GdaSet *set,
                              GdaSetSource *source,
                              GdaDataModel *model);

Replaces source->data_model with model , which must have the same characteristics as source->data_model (same column types)

Also for each GdaHolder for which source->data_model is a source model, this method calls gda_holder_set_source_model() with model to replace the source by the new model

Parameters

set

a GdaSet object

 

source

a pointer to a GdaSetSource in set

 

model

a GdaDataModel

 

Since 4.2


gda_set_get_node ()

GdaSetNode *
gda_set_get_node (GdaSet *set,
                  GdaHolder *holder);

Finds a GdaSetNode holding information for holder , don't modify the returned structure

Parameters

set

a GdaSet object

 

holder

a GdaHolder object

 

Returns

the requested GdaSetNode or NULL.

[transfer none]


gda_set_get_source_for_model ()

GdaSetSource *
gda_set_get_source_for_model (GdaSet *set,
                              GdaDataModel *model);

Finds the GdaSetSource structure used in set for which model is a the data model (the returned structure should not be modified).

Parameters

set

a GdaSet object

 

model

a GdaDataModel object

 

Returns

the requested GdaSetSource pointer or NULL.

[transfer none]


gda_set_get_source ()

GdaSetSource *
gda_set_get_source (GdaSet *set,
                    GdaHolder *holder);

Finds a GdaSetSource which contains the GdaDataModel restricting the possible values of holder , don't modify the returned structure.

Parameters

set

a GdaSet object

 

holder

a GdaHolder object

 

Returns

the requested GdaSetSource or NULL.

[transfer none]


gda_set_get_group ()

GdaSetGroup *
gda_set_get_group (GdaSet *set,
                   GdaHolder *holder);

Finds a GdaSetGroup which lists a GdaSetNode containing holder , don't modify the returned structure.

Parameters

set

a GdaSet object

 

holder

a GdaHolder object

 

Returns

the requested GdaSetGroup or NULL.

[transfer none]

Types and Values

GdaSet

typedef struct {
	GSList         *holders;   /* list of GdaHolder objects */
	GSList         *nodes_list;   /* list of GdaSetNode */
        GSList         *sources_list; /* list of GdaSetSource */
	GSList         *groups_list;  /* list of GdaSetGroup */
} GdaSet;

Members

GSList *holders;

list of GdaHolder objects.

[element-type Gda.Holder]

GSList *nodes_list;

list of GdaSetNode.

[element-type Gda.SetNode]

GSList *sources_list;

list of GdaSetSource.

[element-type Gda.SetSource]

GSList *groups_list;

list of GdaSetGroup.

[element-type Gda.SetGroup]

GdaSetNode

typedef struct {
	GdaHolder*    GSEAL(holder);
	GdaDataModel* GSEAL(source_model);
	gint          GSEAL(source_column);
} GdaSetNode;

Since 5.2, you must consider this struct as opaque. Any access to its internal must use public API. Don't try to use gda_set_node_free on a struct that was created manually.

Members


GdaSetSource

typedef struct {
	GdaDataModel*   GSEAL(data_model);   /* Can't be NULL */
	GSList*         GSEAL(nodes);        /* list of #GdaSetNode for which source_model == @data_model */
} GdaSetSource;

Since 5.2, you must consider this struct as opaque. Any access to its internal must use public API. Don't try to use gda_set_source_free on a struct that was created manually.

Members


GdaSetGroup

typedef struct {
	GSList*       GSEAL(nodes);       /* list of GdaSetNode, at least one entry */
	GdaSetSource* GSEAL(nodes_source); /* if NULL, then @nodes contains exactly one entry */
} GdaSetGroup;

Since 5.2, you must consider this struct as opaque. Any access to its internal must use public API. Don't try to use gda_set_group_free on a struct that was created manually.

Members

Property Details

The “description” property

  “description”              gchar *

Description.

Flags: Read / Write

Default value: NULL


The “holders” property

  “holders”                  gpointer

GdaHolder objects the set should contain.

Flags: Write / Construct Only


The “id” property

  “id”                       gchar *

Id.

Flags: Read / Write

Default value: NULL


The “name” property

  “name”                     gchar *

Name.

Flags: Read / Write

Default value: NULL


The “validate-changes” property

  “validate-changes”         gboolean

Defines if the "validate-set" signal gets emitted when any holder in the data set changes. This property also affects the GdaHolder:validate-changes property.

Flags: Read / Write

Default value: TRUE

Since 5.2.0

Signal Details

The “holder-attr-changed” signal

void
user_function (GdaSet    *set,
               GdaHolder *holder,
               gchar     *attr_name,
               GValue    *attr_value,
               gpointer   user_data)

Gets emitted when an attribute for any of the GdaHolder objects managed by set has changed

Parameters

set

the GdaSet

 

holder

the GdaHolder for which an attribute changed

 

attr_name

attribute's name

 

attr_value

attribute's value

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First


The “holder-changed” signal

void
user_function (GdaSet    *gdaset,
               GdaHolder *arg1,
               gpointer   user_data)

Flags: Run First


The “holder-type-set” signal

void
user_function (GdaSet    *set,
               GdaHolder *holder,
               gpointer   user_data)

Gets emitted when holder in set has its type finally set, in case it was GDA_TYPE_NULL

Parameters

set

the GdaSet

 

holder

the GdaHolder for which the GType has been set

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First

Since 4.2


The “public-data-changed” signal

void
user_function (GdaSet  *set,
               gpointer user_data)

Gets emitted when set 's public data (GdaSetNode, GdaSetGroup or GdaSetSource values) have changed

Parameters

set

the GdaSet

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First


The “source-model-changed” signal

void
user_function (GdaSet  *set,
               gpointer source,
               gpointer user_data)

Gets emitted when the data model in source has changed

Parameters

set

the GdaSet

 

source

the GdaSetSource for which the data_model attribute has changed

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First

Since 4.2


The “validate-holder-change” signal

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

Gets emitted when a GdaHolder's in set 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

set

the GdaSet

 

holder

the GdaHolder which is going to change

 

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


The “validate-set” signal

GError*
user_function (GdaSet  *set,
               gpointer user_data)

Gets emitted when gda_set_is_valid() is called, use this signal to control which combination of values set 's holder can have (for example to implement some business rules)

Parameters

set

the GdaSet

 

user_data

user data set when the signal handler was connected.

 

Returns

NULL if set 's contents has been validated, or a GError otherwise.

Flags: Run Last

See Also

GdaHolder