![]() |
![]() |
![]() |
GNOME Data Access 4 manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy | Properties | Signals |
GdaSet; GdaSet * gda_set_new (GSList *holders); GdaSet * gda_set_copy (GdaSet *set); GdaSet * gda_set_new_inline (gint nb, ...); GdaSet * gda_set_new_from_spec_string (const gchar *xml_spec, GError **error); GdaSet * gda_set_new_from_spec_node (xmlNodePtr xml_spec, GError **error); gboolean gda_set_is_valid (GdaSet *set, GError **error); const GValue * gda_set_get_holder_value (GdaSet *set, const gchar *holder_id); gboolean gda_set_set_holder_value (GdaSet *set, GError **error, const gchar *holder_id, ...); GdaHolder * gda_set_get_holder (GdaSet *set, const gchar *holder_id); GdaHolder * gda_set_get_nth_holder (GdaSet *set, gint pos); gboolean gda_set_add_holder (GdaSet *set, GdaHolder *holder); void gda_set_remove_holder (GdaSet *set, GdaHolder *holder); void gda_set_merge_with_set (GdaSet *set, GdaSet *set_to_merge); GdaSetNode; GdaSetNode * gda_set_get_node (GdaSet *set, GdaHolder *holder); GdaSetSource; GdaSetSource * gda_set_get_source_for_model (GdaSet *set, GdaDataModel *model); GdaSetSource * gda_set_get_source (GdaSet *set, GdaHolder *holder); GdaSetGroup; GdaSetGroup * gda_set_get_group (GdaSet *set, GdaHolder *holder);
"description" gchar* : Read / Write "holders" gpointer : Write / Construct Only "id" gchar* : Read / Write "name" gchar* : Read / Write
"holder-attr-changed" : Run First "holder-changed" : Run First "public-data-changed" : Run First "validate-holder-change" : Run Last "validate-set" : Run Last
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.
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;
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.
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.
GdaSet * gda_set_new_from_spec_string (const gchar *xml_spec, GError **error);
Creates a new GdaSet object from the xml_spec
specifications
|
a string |
|
a place to store the error, or NULL
|
Returns : |
a new object, or NULL if an error occurred
|
GdaSet * gda_set_new_from_spec_node (xmlNodePtr xml_spec, GError **error);
Creates a new GdaSet object from the xml_spec
specifications
|
a xmlNodePtr for a <holders> tag |
|
a place to store the error, or NULL
|
Returns : |
a new object, or NULL if an error occurred
|
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.
|
a GdaSet object |
|
a place to store validation errors, or NULL
|
Returns : |
TRUE if the set is valid |
const GValue * gda_set_get_holder_value (GdaSet *set, const gchar *holder_id);
Get the value of the GdaHolder which ID is holder_id
|
a GdaSet object |
|
the ID of the holder to set the value |
Returns : |
the requested GValue, or NULL (see gda_holder_get_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
|
a GdaSet object |
|
a place to store errors, or NULL
|
|
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 |
GdaHolder * gda_set_get_holder (GdaSet *set, const gchar *holder_id);
Finds a GdaHolder using its ID
GdaHolder * gda_set_get_nth_holder (GdaSet *set, gint pos);
Finds a GdaHolder using its position
|
a GdaSet object |
|
the position of the requested GdaHolder, starting at 0
|
Returns : |
a GdaHolder or NULL
|
Since 4.2
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
).
void gda_set_remove_holder (GdaSet *set, GdaHolder *holder);
|
|
|
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
.
typedef struct { GdaHolder *holder; /* Can't be NULL */ GdaDataModel *source_model; /* may be NULL */ gint source_column; /* unused if @source_model is NULL */ /* Padding for future expansion */ gpointer _gda_reserved1; gpointer _gda_reserved2; } GdaSetNode;
For each GdaHolder object in the GdaSet object, there is a GdaSetNode structure which sums up all the information for each GdaHolder. Contains public fields, which must not be modified.
GdaHolder * |
a GdaHolder in the GdaSet |
GdaDataModel * |
if gda_holder_set_source_model() has been used with holder , the GdaDataModel used, or NULL
|
gint |
if gda_holder_set_source_model() has been used with holder , the column used, or 0
|
gpointer |
|
gpointer |
GdaSetNode * gda_set_get_node (GdaSet *set, GdaHolder *holder);
Finds a GdaSetNode holding information for holder
, don't modify the returned structure
|
a GdaSet object |
|
a GdaHolder object |
Returns : |
a GdaSetNode or NULL
|
typedef struct { GdaDataModel *data_model; /* Can't be NULL */ GSList *nodes; /* list of #GdaSetNode for which source_model == @data_model */ /* Padding for future expansion */ gpointer _gda_reserved1; gpointer _gda_reserved2; gpointer _gda_reserved3; gpointer _gda_reserved4; } GdaSetSource;
There is a GdaSetSource structure for each GdaDataModel which restricts at least one GdaHolder in the GdaSet object.
GdaDataModel * |
the GdaDataModel |
GSList * |
the list of GdaSetNode where the source_model attribute equals data_model
|
gpointer |
|
gpointer |
|
gpointer |
|
gpointer |
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).
|
a GdaSet object |
|
a GdaDataModel object |
Returns : |
a GdaSetSource pointer or NULL .
|
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.
|
a GdaSet object |
|
a GdaHolder object |
Returns : |
a GdaSetSource or NULL
|
typedef struct { GSList *nodes; /* list of GdaSetNode, at least one entry */ GdaSetSource *nodes_source; /* if NULL, then @nodes contains exactly one entry */ /* Padding for future expansion */ gpointer _gda_reserved1; gpointer _gda_reserved2; } GdaSetGroup;
There is one GdaSetGroup structure for each _independent_ GdaHolder (those which have the same restricting data model all appear in the same GdaSetGroup structure).
GSList * |
a list of GdaSetNode structures, at least one entry |
GdaSetSource * |
a GdaSetSource pointer where the nodes attribute lists the same GdaHolder objects as nodes
|
gpointer |
|
gpointer |
GdaSetGroup * gda_set_get_group (GdaSet *set, GdaHolder *holder);
Finds a GdaSetGroup which lists a GdaSetNode containing holder
,
don't modify the returned structure.
|
a GdaSet object |
|
a GdaHolder object |
Returns : |
a GdaSetGroup or NULL
|
"holders"
property"holders" gpointer : Write / Construct Only
GdaHolder objects the set should contain.
"holder-attr-changed"
signalvoid user_function (GdaSet *set, GdaHolder *holder, gchar *attr_name, GValue *attr_value, gpointer user_data) : Run First
Gets emitted when an attribute for any of the GdaHolder objects managed by set
has changed
|
the GdaSet |
|
the GdaHolder for which an attribute changed |
|
attribute's name |
|
attribute's value |
|
user data set when the signal handler was connected. |
"holder-changed"
signalvoid user_function (GdaSet *gdaset, GdaHolder *arg1, gpointer user_data) : Run First
|
the object which received the signal. |
|
|
|
user data set when the signal handler was connected. |
"public-data-changed"
signalvoid user_function (GdaSet *set, gpointer user_data) : Run First
Gets emitted when set
's public data (GdaSetNode, GdaSetGroup or GdaSetSource values) have changed
|
the GdaSet |
|
user data set when the signal handler was connected. |
"validate-holder-change"
signalGdaError* user_function (GdaSet *set, GdaHolder *holder, GValue *new_value, gpointer user_data) : Run Last
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)
"validate-set"
signalGdaError* user_function (GdaSet *set, gpointer user_data) : Run Last
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)