GdaSet: GNOME Data Access 5 manual

## GdaSet GdaSet — Container for several values |

## Stability Level

Stable, unless otherwise indicated

## Functions

GdaSet * | gda_set_new ()
GdaSet * | gda_set_new_read_only ()
GdaSet * | gda_set_copy ()
GdaSet * | gda_set_new_inline ()
GdaSet * | gda_set_new_from_spec_string ()
GdaSet * | gda_set_new_from_spec_node ()
gboolean | gda_set_is_valid ()
const GValue * | gda_set_get_holder_value ()
gboolean | gda_set_set_holder_value ()
GdaHolder * | gda_set_get_holder ()
GdaHolder * | gda_set_get_nth_holder ()
gboolean | gda_set_add_holder ()
void | gda_set_remove_holder ()
void | gda_set_merge_with_set ()
void | gda_set_replace_source_model ()
GdaSetNode * | gda_set_get_node ()
GdaSetSource * | gda_set_get_source_for_model ()
GdaSetSource * | gda_set_get_source ()
GdaSetGroup * | gda_set_get_group ()

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

| GdaSet
| GdaSetNode
| GdaSetSource
| GdaSetGroup

## Object Hierarchy

        GObject
        ╰── GdaSet
            ╰── GdaDataModelIter

## Includes

    #include <libgda-report/gda-report-engine.h>

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

[skip]

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

[skip]

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