GdaSet: libgda Reference 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 ()
#define | GDA_SET_GROUP()
GdaSetGroup * | gda_set_get_group ()

## Properties

char * | description | Read / Write
gpointer | holders | Write / Construct Only
char * | id | Read / Write
char * | 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

        GBoxed
        ├── GdaSetGroup
        ├── GdaSetNode
        ╰── GdaSetSource
        GObject
        ╰── GdaSet
            ╰── GdaDataModelIter

## Includes

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

## Description

The GdaSet object is a container for several values (as GdaHolder objects). 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`. | [nullable]

#### 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`. | [nullable]

#### 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`. | [nullable]

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

[nullable][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`. | [nullable]
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. | [transfer none]

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

    #define GDA_SET_GROUP(x) ((GdaSetGroup *)(x))

### 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 _GdaSet GdaSet;

### GdaSetNode

    typedef struct _GdaSetNode 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 _GdaSetSource 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 _GdaSetGroup 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”              char *

Description.

Owner: GdaSet

Flags: Read / Write

Default value: NULL

### The `“holders”` property

      “holders”                  gpointer

GdaHolder objects the set should contain.

Owner: GdaSet

Flags: Write / Construct Only

### The `“id”` property

      “id”                       char *

Id.

Owner: GdaSet

Flags: Read / Write

Default value: NULL

### The `“name”` property

      “name”                     char *

Name.

Owner: GdaSet

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.

Owner: GdaSet

Flags: Read / Write

Default value: TRUE

Since: 5.2.0

## Signal Details

### The `“holder-attr-changed”` signal

    void
    user_function (GdaSet    *set,
                   GdaHolder *holder,
                   char      *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