gda.data_model_mixin

Module for [DataModel] interface mixin

Templates 2

tmplDataModelT()

Functions

bool addDataFromXmlNode(libxml2.types.NodePtr node)

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

Upon errors FALSE will be returned and error will be assigned a #GError from the #GDA_DATA_MODEL_ERROR domain.

Parameters

node an XML node representing a <gda_array_data> XML node.

Returns

true if successful, false otherwise.

Throws

[DataModelException]

int appendRow()

Appends a row to the data model (the new row will possibly have NULL values for all columns, or some other values depending on the data model implementation)

Upon errors -1 will be returned and error will be assigned a #GError from the #GDA_DATA_MODEL_ERROR domain.

Returns

the number of the added row, or -1 if an error occurred

Throws

[DataModelException]

int appendValues(gobject.value.Value[] values = null)

Appends a row to the given data model. If any value in values is actually null, then it is considered as a default value. If values is null then all values are set to their default value.

Upon errors -1 will be returned and error will be assigned a #GError from the #GDA_DATA_MODEL_ERROR domain.

Parameters

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

Returns

the number of the added row, or -1 if an error occurred

Throws

[DataModelException]

gda.data_model_array.DataModelArray arrayCopyModel()

Makes a copy of src into a new #GdaDataModelArray object

Returns

a new data model, or null if an error occurred

Throws

[DataModelException]

gda.data_model_array.DataModelArray arrayCopyModelExt(int[] cols)

Like [gda.data_model.DataModel.arrayCopyModel], makes a copy of src, but copies only some columns.

Parameters

cols array of src's columns to copy into the new array, not null

Returns

a new data model, or null if an error occurred

Throws

[DataModelException]

gda.data_model_iter.DataModelIter createIter()

Creates a new iterator object #GdaDataModelIter object which can be used to iterate through rows in model. The new #GdaDataModelIter does not hold any reference to model (ie. if model is destroyed at some point, the new iterator will become useless but in any case it will not prevent the data model from being destroyed).

Depending on the data model's implementation, a new #GdaDataModelIter object may be created, or a reference to an already existing #GdaDataModelIter may be returned. For example if model only supports being accessed using a forward moving cursor (say a the result of a SELECT executed by SQLite with a cursor access mode specified), then this method will always return the same iterator.

If a new #GdaDataModelIter is created, then the row it represents is undefined.

For models which can be accessed randomly, any row can be set using [gda.data_model_iter.DataModelIter.moveToRow], and for models which are accessible sequentially only then use [gda.data_model_iter.DataModelIter.moveNext] (and [gda.data_model_iter.DataModelIter.movePrev] if supported).

Note

for the #GdaDataProxy data model (which proxies any #GdaDataModel for modifications and

has twice the number of columns of the proxied data model), this method will create an iterator in which only the columns of the proxied data model appear. If you need to have a #GdaDataModelIter in which all the proxy's columns appear, create it using:

Returns

a #GdaDataModelIter object, or null if an error occurred

gda.column.Column describeColumn(int 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.

Parameters

col column number.

Returns

the description of the column.

void dump(void * toStream = null)

Dumps a textual representation of the model to the to_stream stream

The following environment variables can affect the resulting output:

<itemizedlist> <listitem><para>GDA_DATA_MODEL_DUMP_ROW_NUMBERS: if set, the first column of the output will contain row numbers</para></listitem> <listitem><para>GDA_DATA_MODEL_DUMP_ATTRIBUTES: if set, also dump the data model's columns' types and value's attributes</para></listitem> <listitem><para>GDA_DATA_MODEL_DUMP_TITLE: if set, also dump the data model's title</para></listitem> <listitem><para>GDA_DATA_MODEL_NULL_AS_EMPTY: if set, replace the 'NULL' string with an empty string for NULL values </para></listitem> <listitem><para>GDA_DATA_MODEL_DUMP_TRUNCATE: if set to a numeric value, truncates the output to the width specified by the value. If the value is -1 then the actual terminal size (if it can be determined) is used</para></listitem> </itemizedlist>

Parameters

toStream where to dump the data model

string dumpAsString()

Dumps a textual representation of the model into a new string. The main differences with [gda.data_model.DataModel.exportToString] are that the formatting options are passed using environment variables, and that the data is dumped regardless of the user locale (e.g. dates are not formatted according to the locale).

The following environment variables can affect the resulting output:

<itemizedlist> <listitem><para>GDA_DATA_MODEL_DUMP_ROW_NUMBERS: if set, the first column of the output will contain row numbers</para></listitem> <listitem><para>GDA_DATA_MODEL_DUMP_TITLE: if set, also dump the data model's title</para></listitem> <listitem><para>GDA_DATA_MODEL_NULL_AS_EMPTY: if set, replace the 'NULL' string with an empty string for NULL values </para></listitem> <listitem><para>GDA_DATA_MODEL_DUMP_TRUNCATE: if set to a numeric value, truncates the output to the width specified by the value. If the value is -1 then the actual terminal size (if it can be determined) is used</para></listitem> </itemizedlist>

Returns

a new string.

bool exportToFile(gda.types.DataModelIOFormat format, string file, int[] cols, int[] rows, gda.set.Set options)

Exports data contained in model to the file file; the format is specified using the format argument. Note that the date format used is the one used by the connection from which the data model has been made (as the result of a SELECT statement), or, for other kinds of data models, the default format (refer to [gda.data_handler.DataHandler.getDefault]) unless the "cnc" property has been set and points to a #GdaConnection to use that connection's date format.

Specifically, the parameters in the options list can be:

<itemizedlist> <listitem><para>"SEPARATOR": a string value of which the first character is used as a separator in case of CSV export </para></listitem> <listitem><para>"QUOTE": a string value of which the first character is used as a quote character in case of CSV export. The

default if not specified is the double quote character</para></listitem>

<listitem><para>"FIELD_QUOTE": a boolean value which can be set to FALSE if no quote around the individual fields

is requeted, in case of CSV export</para></listitem>

<listitem><para>"NAMES_ON_FIRST_LINE": a boolean value which, if set to true and in case of a CSV or GDA_DATA_MODEL_IO_TEXT_TABLE export, will add a first line with the name each exported field (note that "FIELDS_NAME" is also accepted as a synonym)</para></listitem> <listitem><para>"NAME": a string value used to name the exported data if the export format is XML or GDA_DATA_MODEL_IO_TEXT_TABLE</para></listitem> <listitem><para>"OVERWRITE": a boolean value which tells if the file must be over-written if it already exists.</para></listitem> <listitem><para>"NULL_AS_EMPTY": a boolean value which, if set to true and in case of a CSV or GDA_DATA_MODEL_IO_TEXT_TABLE export, will render and NULL value as the empty string (instead of the 'NULL' string)</para></listitem> <listitem><para>"INVALID_AS_NULL": a boolean value which, if set to true, considers any invalid data (for example for the date related values) as NULL</para></listitem> <listitem><para>"COLUMN_SEPARATORS": a boolean value which, if set to true, adds a separators lines between each column, if the export format is GDA_DATA_MODEL_IO_TEXT_TABLE </para></listitem> <listitem><para>"SEPARATOR_LINE": a boolean value which, if set to true, adds an horizontal line between column titles and values, if the export format is GDA_DATA_MODEL_IO_TEXT_TABLE </para></listitem> <listitem><para>"ROW_NUMBERS": a boolean value which, if set to true, prepends a column with row numbers, if the export format is GDA_DATA_MODEL_IO_TEXT_TABLE </para></listitem> <listitem><para>"MAX_WIDTH": an integer value which, if greater than 0, makes all the lines truncated to have at most that number of characters, if the export format is GDA_DATA_MODEL_IO_TEXT_TABLE </para></listitem> </itemizedlist>

Warning: this function uses a #GdaDataModelIter iterator, and if model does not offer a random access (check using [gda.data_model.DataModel.getAccessFlags]), the iterator will be the same as normally used to access data in model previously to calling this method, and this iterator will be moved (point to another row).

Upon errors false will be returned and error will be assigned a #GError from the #GDA_DATA_MODEL_ERROR domain.

Parameters

`format`	the format in which to export data
`file`	the filename to export to
`cols`	an array containing which columns of model will be exported, or null for all columns
`rows`	an array containing which rows of model will be exported, or null for all rows
`options`	list of options for the export

Returns

TRUE if no error occurred

Throws

[DataModelException]

string exportToString(gda.types.DataModelIOFormat format, int[] cols, int[] rows, gda.set.Set options)

Exports data contained in model to a string; the format is specified using the format argument, see the [gda.data_model.DataModel.exportToFile] documentation for more information about the options argument (except for the "OVERWRITE" option).

See also [gda.data_model.DataModel.dumpAsString];

Parameters

`format`	the format in which to export data
`cols`	an array containing which columns of model will be exported, or null for all columns
`rows`	an array containing which rows of model will be exported, or null for all rows
`options`	list of options for the export

Returns

a new string, use [glib.global.gfree] when no longer needed

void freeze()

Disables notifications of changes on the given data model. To re-enable notifications again, you should call the #gda_data_model_thaw function.

gda.types.DataModelAccessFlags getAccessFlags()

Get the attributes of model such as how to access the data it contains if it's modifiable, etc.

Returns

an ORed value of #GdaDataModelAccessFlags flags

gda.types.ValueAttribute getAttributesAt(int col, int row)

Get the attributes of the value stored at (row, col) in model, 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.

Parameters

`col`	a valid column number
`row`	a valid row number, or -1

Returns

the attributes as an ORed value of #GdaValueAttribute

int getColumnIndex(string name)

Get the index of the first column named name in model.

Parameters

name a column name

Returns

the column index, or -1 if no column named name was found

string getColumnName(int col)

string getColumnTitle(int col)

int getNColumns()

int getNRows()

bool getNotify()

Returns the status of notifications changes on the given data model.

Returns

gobject.value.Value getTypedValueAt(int col, int row, gobject.types.GType expectedType, bool nullok)

Upon errors null will be returned and error will be assigned a #GError from the #GDA_DATA_MODEL_ERROR domain.

This method is similar to [gda.data_model.DataModel.getValueAt], except that it also allows one to specify the expected #GType of the value to get: if the data model returned a #GValue of a type different than the expected one, then this method returns null and an error code.

Note

the same limitations and usage instructions apply as for [gda.data_model.DataModel.getValueAt].

Upon errors null will be returned and error will be assigned a #GError from the #GDA_DATA_MODEL_ERROR domain.

Parameters

`col`	a valid column number.
`row`	a valid row number.
`expectedType`	the expected data type of the returned value
`nullok`	if TRUE, then NULL values (value of type `GDA_TYPE_NULL`) will not generate any error

Returns

a #GValue containing the value stored in the given

position, or null on error (out-of-bound position, wrong data type, etc).

Throws

[DataModelException]

gobject.value.Value getValueAt(int col, int row)

Retrieves the data stored in the given position (identified by the col and row parameters) on a data model.

Upon errors null will be returned and error will be assigned a #GError from the #GDA_DATA_MODEL_ERROR domain.

This is the main function for accessing data in a model which allows random access to its data. To access data in a data model using a cursor, use a #GdaDataModelIter object, obtained using [gda.data_model.DataModel.createIter].

Note1: the returned #GValue must not be modified directly (unexpected behaviours may occur if you do so).

Note2: the returned value may become invalid as soon as any Libgda part is executed again, which means if you want to keep the value, a copy must be made, however it will remain valid as long as the only Libgda usage is calling [gda.data_model.DataModel.getValueAt] for different values of the same row.

If you want to modify a value stored in a #GdaDataModel, use the [gda.data_model.DataModel.setValueAt] or [gda.data_model.DataModel.setValues] methods.

Upon errors null will be returned and error will be assigned a #GError from the #GDA_DATA_MODEL_ERROR domain.

Parameters

`col`	a valid column number.
`row`	a valid row number.

Returns

a #GValue containing the value stored in the given

position, or null on error (out-of-bound position, etc).

Throws

[DataModelException]

bool iterAtRow(gda.data_model_iter.DataModelIter iter, int row)

Moves iter to the row number given by row.

Parameters

`iter`	a #GdaDataModelIter object.
`row`	a row to point to with iter

Returns

Deprecated

use [gda.data_model_iter.DataModelIter.moveToRow] instead

bool iterNext(gda.data_model_iter.DataModelIter iter)

Moves iter to the next row in model.

Parameters

iter a #GdaDataModelIter object.

Returns

Deprecated

use [gda.data_model_iter.DataModelIter.moveNext] instead

bool iterPrev(gda.data_model_iter.DataModelIter iter)

Moves iter to the next row in model.

Parameters

iter a #GdaDataModelIter object.

Returns

Deprecated

use [gda.data_model_iter.DataModelIter.movePrev] instead

bool iterSetValue(gda.data_model_iter.DataModelIter iter, int col, gobject.value.Value value)

Set value to the given column and row pointed by iter in the given model.

Parameters

`iter`	a #GdaDataModelIter object.
`col`	the number of column to set value to
`value`	the to use to set on

Returns

Throws

[DataModelException]

Deprecated

use [gda.data_model_iter.DataModelIter.setValueAt] instead

bool removeRow(int row)

Removes a row from the data model.

Upon errors FALSE will be returned and error will be assigned a #GError from the #GDA_DATA_MODEL_ERROR domain.

Parameters

row the row number to be removed.

Returns

true if successful, false otherwise.

Throws

[DataModelException]

void reset()

Emits the 'reset' and 'changed' signal on model.

void rowInserted(int row)

Emits the 'row_inserted' and 'changed' signals on model.

This method should only be used by #GdaDataModel implementations to signal that a row has been inserted.

Parameters

row row number.

void rowRemoved(int row)

Emits the 'row_removed' and 'changed' signal on model.

This method should only be used by #GdaDataModel implementations to signal that a row has been removed

Parameters

row row number.

void rowUpdated(int row)

Emits the 'row_updated' and 'changed' signals on model.

This method should only be used by #GdaDataModel implementations to signal that a row has been updated.

Parameters

row row number.

void sendHint(gda.types.DataModelHint hint, gobject.value.Value hintValue = null)

Sends a hint to the data model. The hint may or may not be handled by the data model, depending on its implementation

Parameters

`hint`	a hint to send to the model
`hintValue`	an optional value to specify the hint, or null

void setColumnName(int col, string name)

Sets the name of the given col in model, and if its title is not set, also sets the title to name.

Parameters

`col`	column number
`name`	name for the given column.

void setColumnTitle(int col, string title)

Sets the title of the given col in model.

Parameters

`col`	column number
`title`	title for the given column.

void setNotify(bool doNotifyChanges)

Enable or disable notifications changes on the given data model.

Parameters

doNotifyChanges Set to TRUE if you require notifications.

Deprecated

use [gda.data_model.DataModel.freeze] and [gda.data_model.DataModel.thaw] instead

bool setValueAt(int col, int row, gobject.value.Value value)

Modifies a value in model, at (col, row).

Upon errors FALSE will be returned and error will be assigned a #GError from the #GDA_DATA_MODEL_ERROR domain.

Parameters

`col`	column number.
`row`	row number.
`value`	a #GValue (not null)

Returns

TRUE if the value in the data model has been updated and no error occurred

Throws

[DataModelException]

bool setValues(int row, gobject.value.Value[] values = null)

In a similar way to [gda.data_model.DataModel.setValueAt], this method modifies a data model's contents by setting several values at once.

If any value in values is actually null, then the value in the corresponding column is left unchanged.

Upon errors FALSE will be returned and error will be assigned a #GError from the #GDA_DATA_MODEL_ERROR domain.

Parameters

`row`	row number.
`values`	a list of #GValue (or null), one for at most the number of columns of model

Returns

true if the value in the data model has been updated and no error occurred

Throws

[DataModelException]

void thaw()

Re-enables notifications of changes on the given data model.

gulong connectAccessChanged(T)(T callback, Flag!"After" after = No.After) if (isCallable!T && is(ReturnType!T == void) && (Parameters!T.length < 1 || (ParameterStorageClassTuple!T[0] == ParameterStorageClass.none && is(Parameters!T[0] : gda.data_model.DataModel))) && Parameters!T.length < 2)

Connect to AccessChanged signal.

Gets emitted when model's access flags have changed. Use [gda.data_model.DataModel.getAccessFlags] to get the access flags.

Parameters

`callback`	signal callback delegate or function to connect `void callback(gda.data_model.DataModel dataModel)` `dataModel` the instance the signal is connected to (optional)
`after`	Yes.After to execute callback after default handler, No.After to execute before (default)

Returns

Signal ID

gulong connectChanged(T)(T callback, Flag!"After" after = No.After) if (isCallable!T && is(ReturnType!T == void) && (Parameters!T.length < 1 || (ParameterStorageClassTuple!T[0] == ParameterStorageClass.none && is(Parameters!T[0] : gda.data_model.DataModel))) && Parameters!T.length < 2)

Connect to Changed signal.

Gets emitted when any value in model has been changed

Parameters

`callback`	signal callback delegate or function to connect `void callback(gda.data_model.DataModel dataModel)` `dataModel` the instance the signal is connected to (optional)
`after`	Yes.After to execute callback after default handler, No.After to execute before (default)

Returns

Signal ID

gulong connectReset(T)(T callback, Flag!"After" after = No.After) if (isCallable!T && is(ReturnType!T == void) && (Parameters!T.length < 1 || (ParameterStorageClassTuple!T[0] == ParameterStorageClass.none && is(Parameters!T[0] : gda.data_model.DataModel))) && Parameters!T.length < 2)

Connect to Reset signal.

Gets emitted when model's contents has been completely reset (the number and type of columns may also have changed)

Parameters

`callback`	signal callback delegate or function to connect `void callback(gda.data_model.DataModel dataModel)` `dataModel` the instance the signal is connected to (optional)
`after`	Yes.After to execute callback after default handler, No.After to execute before (default)

Returns

Signal ID

gulong connectRowInserted(T)(T callback, Flag!"After" after = No.After) if (isCallable!T && is(ReturnType!T == void) && (Parameters!T.length < 1 || (ParameterStorageClassTuple!T[0] == ParameterStorageClass.none && is(Parameters!T[0] == int))) && (Parameters!T.length < 2 || (ParameterStorageClassTuple!T[1] == ParameterStorageClass.none && is(Parameters!T[1] : gda.data_model.DataModel))) && Parameters!T.length < 3)

Connect to RowInserted signal.

Gets emitted when a row has been inserted in model

Parameters

`callback`	signal callback delegate or function to connect `void callback(int row, gda.data_model.DataModel dataModel)` `row` the row number (optional) `dataModel` the instance the signal is connected to (optional)
`after`	Yes.After to execute callback after default handler, No.After to execute before (default)

Returns

Signal ID

gulong connectRowRemoved(T)(T callback, Flag!"After" after = No.After) if (isCallable!T && is(ReturnType!T == void) && (Parameters!T.length < 1 || (ParameterStorageClassTuple!T[0] == ParameterStorageClass.none && is(Parameters!T[0] == int))) && (Parameters!T.length < 2 || (ParameterStorageClassTuple!T[1] == ParameterStorageClass.none && is(Parameters!T[1] : gda.data_model.DataModel))) && Parameters!T.length < 3)

Connect to RowRemoved signal.

Gets emitted when a row has been removed from model

Parameters

`callback`	signal callback delegate or function to connect `void callback(int row, gda.data_model.DataModel dataModel)` `row` the row number (optional) `dataModel` the instance the signal is connected to (optional)
`after`	Yes.After to execute callback after default handler, No.After to execute before (default)

Returns

Signal ID

gulong connectRowUpdated(T)(T callback, Flag!"After" after = No.After) if (isCallable!T && is(ReturnType!T == void) && (Parameters!T.length < 1 || (ParameterStorageClassTuple!T[0] == ParameterStorageClass.none && is(Parameters!T[0] == int))) && (Parameters!T.length < 2 || (ParameterStorageClassTuple!T[1] == ParameterStorageClass.none && is(Parameters!T[1] : gda.data_model.DataModel))) && Parameters!T.length < 3)

Connect to RowUpdated signal.

Gets emitted when a row has been modified in model

Parameters

`callback`	signal callback delegate or function to connect `void callback(int row, gda.data_model.DataModel dataModel)` `row` the row number (optional) `dataModel` the instance the signal is connected to (optional)
`after`	Yes.After to execute callback after default handler, No.After to execute before (default)

Returns

Signal ID

tmplDataModelGidBuilderT()