Top | ![]() |
![]() |
![]() |
![]() |
void | reset | Run Last |
void | row-inserted | Run Last |
void | row-removed | Run Last |
void | row-updated | Run Last |
GdaDataModel | |
enum | GdaDataModelAccessFlags |
enum | GdaDataModelHint |
enum | GdaDataModelIOFormat |
GdaDataModel is implemented by GdaDataAccessWrapper, GdaDataModelArray, GdaDataModelFilterSQL, GdaDataModelHash, GdaDataModelImport, GdaDataModelQuery, GdaDataModelRow and GdaDataProxy.
A GdaDataMode represents an array of values organized in rows and columns. All the data in the same column have the same type, and all the data in each row have the same semantic meaning. The GdaDataModel is actually an interface implemented by other objects to support various kinds of data storage and operations.
Depending on the real implementation, the contents of data models may be modified by the user using functions
provided by the model. The actual operations a data model permits can be known using the
gda_data_model_get_access_flags()
method.
Again, depending on the real implementation, data retreiving can be done either accessing direct random
values located by their row and column, or using a GdaDataModelIter cursor, or both. Use the
gda_data_model_get_access_flags()
method to know how the data model can be accessed. Note that a GdaDatamodel
which can be accessed in a random way can also be accessed using cursors (and several cusrors may be used at the same
time), whereas data model which can only be accessed using cursors can only have one cursor for iterating.
Random access data models are easier to use since picking a value is very simple using the gda_data_model_get_value_at()
,
but consume more memory since all the accessible values must generally be present in memory even if they are not used.
Thus if a data model must handle large quantities of data, it is generally wiser to use a data model which can be
only accessed using a cursor.
As a side note there are also data models which wrap other data models such as:
The GdaDataProxy data model which stores temporary modifications and shows only some parts of the wrapped data model
The GdaDataAccessWrapper data model which offers a memory-efficient random access on top of a wrapped cursor based access data model
void gda_data_model_row_inserted (GdaDataModel *model
,gint row
);
Emits the 'row_inserted' and 'changed' signals on model
.
void gda_data_model_row_updated (GdaDataModel *model
,gint row
);
Emits the 'row_updated' and 'changed' signals on model
.
void gda_data_model_row_removed (GdaDataModel *model
,gint row
);
Emits the 'row_removed' and 'changed' signal on model
.
void
gda_data_model_freeze (GdaDataModel *model
);
Disables notifications of changes on the given data model. To re-enable notifications again, you should call the gda_data_model_thaw function.
void
gda_data_model_thaw (GdaDataModel *model
);
Re-enables notifications of changes on the given data model.
GdaDataModelAccessFlags
gda_data_model_get_access_flags (GdaDataModel *model
);
Get the attributes of model
such as how to access the data it contains if it's modifiable, etc.
GdaColumn * gda_data_model_describe_column (GdaDataModel *model
,gint col
);
Queries the underlying data model implementation for a description of a given column. That description is returned in the form of a GdaColumn structure, which contains all the information about the given column in the data model.
WARNING: the returned GdaColumn object belongs to the model
model and
and should not be destroyed; any modification will affect the whole data model.
gint gda_data_model_get_column_index_by_name (GdaDataModel *model
,const gchar *name
);
Get the index of the column named name
in model
const gchar * gda_data_model_get_column_title (GdaDataModel *model
,gint col
);
void gda_data_model_set_column_title (GdaDataModel *model
,gint col
,const gchar *title
);
Sets the title
of the given col
in model
.
GdaValueAttribute gda_data_model_get_attributes_at (GdaDataModel *model
,gint col
,gint row
);
Get the attributes of the value stored at (row, col) in proxy
, which
is an ORed value of GdaValueAttribute flags. As a special case, if
row
is -1, then the attributes returned correspond to a "would be" value
if a row was added to model
.
const GValue * gda_data_model_get_value_at (GdaDataModel *model
,gint col
,gint row
);
Retrieves the data stored in the given position (identified by
the col
and row
parameters) on a data model.
This is the main function for accessing data in a model.
Note that the returned GValue must not be modified directly (unexpected behaviours may
occur if you do so). If you want to
modify a value stored in a GdaDataModel, use the gda_data_model_set_value()
method.
a GValue containing the value stored in the given
position, or NULL
on error (out-of-bound position, etc).
const GValue * gda_data_model_get_value_at_col_name (GdaDataModel *model
,const gchar *column_name
,gint row
);
Retrieves the data stored in the given position (identified by
the col_name
column and row
parameters) on a data model.
See also gda_data_model_get_value_at()
.
a GValue containing the value stored in the given
position, or NULL
on error (out-of-bound position, etc).
gboolean gda_data_model_set_value_at (GdaDataModel *model
,gint col
,gint row
,const GValue *value
,GError **error
);
model |
a GdaDataModel object. |
|
col |
column number. |
|
row |
row number. |
|
value |
a GValue, or |
|
error |
a place to store errors, or |
gboolean gda_data_model_set_values (GdaDataModel *model
,gint row
,GList *values
,GError **error
);
If any value in values
is actually NULL
, then
it is considered as a default value.
model |
a GdaDataModel object. |
|
row |
row number. |
|
values |
a list of GValue, one for each n (<nb_cols) columns of |
|
error |
a place to store errors, or |
GdaDataModelIter *
gda_data_model_create_iter (GdaDataModel *model
);
Creates a new iterator object GdaDataModelIter object which can be used to iterate through
rows in model
.
The row the returned GdaDataModelIter represents is undefined. For models which can be accessed
randomly the correspoding row can be set using gda_data_model_move_iter_at_row()
,
and for models which are accessible sequentially only then the first row will be
fetched using gda_data_model_move_iter_next()
.
gint gda_data_model_append_values (GdaDataModel *model
,const GList *values
,GError **error
);
Appends a row to the given data model. If any value in values
is actually NULL
, then
it is considered as a default value.
model |
a GdaDataModel object. |
|
values |
GList of GValue* representing the row to add. The length must match model's column count. These GValue are value-copied (the user is still responsible for freeing them). |
|
error |
a place to store errors, or |
gint gda_data_model_append_row (GdaDataModel *model
,GError **error
);
Appends a row to the data model.
gboolean gda_data_model_remove_row (GdaDataModel *model
,gint row
,GError **error
);
Removes a row from the data model.
model |
a GdaDataModel object. |
|
row |
the row number to be removed. |
|
error |
a place to store errors, or |
gint gda_data_model_get_row_from_values (GdaDataModel *model
,GSList *values
,gint *cols_index
);
Returns the first row where all the values in values
at the columns identified at
cols_index
match. If the row can't be identified, then returns -1;
NOTE: the cols_index
array MUST contain a column index for each value in values
model |
a GdaDataModel object. |
|
values |
a list of GValue values |
|
cols_index |
an array of gint containing the column number to match each value of |
void gda_data_model_send_hint (GdaDataModel *model
,GdaDataModelHint hint
,const GValue *hint_value
);
Sends a hint to the data model. The hint may or may not be handled by the data model, depending on its implementation
model |
||
hint |
a hint to send to the model |
|
hint_value |
an optional value to specify the hint, or |
gchar * gda_data_model_export_to_string (GdaDataModel *model
,GdaDataModelIOFormat format
,const gint *cols
,gint nb_cols
,const gint *rows
,gint nb_rows
,GdaParameterList *options
);
Exports data contained in model
to a string; the format is specified using the format
argument.
Specifically, the parameters in the options
list can be:
"SEPARATOR": a string value of which the first character is used as a separator in case of CSV export
"NAME": a string value used to name the exported data if the export format is XML
model |
||
format |
the format in which to export data |
|
cols |
an array containing which columns of |
|
nb_cols |
the number of columns in |
|
rows |
an array containing which rows of |
|
nb_rows |
the number of rows in |
|
options |
list of options for the export |
gboolean gda_data_model_export_to_file (GdaDataModel *model
,GdaDataModelIOFormat format
,const gchar *file
,const gint *cols
,gint nb_cols
,const gint *rows
,gint nb_rows
,GdaParameterList *options
,GError **error
);
Exports data contained in model
to the file
file; the format is specified using the format
argument.
Specifically, the parameters in the options
list can be:
"SEPARATOR": a string value of which the first character is used as a separator in case of CSV export
"NAME": a string value used to name the exported data if the export format is XML
"OVERWRITE": a boolean value which tells if the file must be over-written if it already exists.
model |
||
format |
the format in which to export data |
|
file |
the filename to export to |
|
cols |
an array containing which columns of |
|
nb_cols |
the number of columns in |
|
rows |
an array containing which rows of |
|
nb_rows |
the number of rows in |
|
options |
list of options for the export |
|
error |
a place to store errors, or |
gboolean gda_data_model_add_data_from_xml_node (GdaDataModel *model
,xmlNodePtr node
,GError **error
);
Adds the data from an XML node to the given data model (see the DTD for that node in the $prefix/share/libgda/dtd/libgda-array.dtd file).
gboolean gda_data_model_import_from_model (GdaDataModel *to
,GdaDataModel *from
,gboolean overwrite
,GHashTable *cols_trans
,GError **error
);
Copy the contents of the from
data model to the to
data model. The copy stops as soon as an error
orrurs.
The cols_trans
is a hash table for which keys are to
columns numbers and the values are
the corresponding column numbers in the from
data model. To set the values of a column in to
to NULL,
create an entry in the hash table with a negative value.
to |
the destination GdaDataModel |
|
from |
the source GdaDataModel |
|
overwrite |
TRUE if |
|
cols_trans |
a GHashTable for columns translating, or |
|
error |
a place to store errors, or |
gboolean gda_data_model_import_from_string (GdaDataModel *model
,const gchar *string
,GHashTable *cols_trans
,GdaParameterList *options
,GError **error
);
Loads the data from string
into model
.
gboolean gda_data_model_import_from_file (GdaDataModel *model
,const gchar *file
,GHashTable *cols_trans
,GdaParameterList *options
,GError **error
);
Imports data contained in the file
file into model
; the format is detected.
void gda_data_model_dump (GdaDataModel *model
,FILE *to_stream
);
Dumps a textual representation of the model
to the to_stream
stream
gchar *
gda_data_model_dump_as_string (GdaDataModel *model
);
Dumps a textual representation of the model
into a new string
“reset”
signalvoid user_function (GdaDataModel *gdadatamodel, gpointer user_data)
gdadatamodel |
the object which received the signal. |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last
“row-inserted”
signalvoid user_function (GdaDataModel *gdadatamodel, gint arg1, gpointer user_data)
gdadatamodel |
the object which received the signal. |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last
“row-removed”
signalvoid user_function (GdaDataModel *gdadatamodel, gint arg1, gpointer user_data)
gdadatamodel |
the object which received the signal. |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last
“row-updated”
signalvoid user_function (GdaDataModel *gdadatamodel, gint arg1, gpointer user_data)
gdadatamodel |
the object which received the signal. |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last