Gda.DataModel¶

Implementations:: Gda.DataAccessWrapper, Gda.DataModelArray, Gda.DataModelDir, Gda.DataModelImport, Gda.DataPivot, Gda.DataProxy, Gda.DataSelect

Methods¶

class	`error_quark` ()
	`add_data_from_xml_node` (node)
	`append_row` ()
	`append_values` (values)
	`array_copy_model` ()
	`array_copy_model_ext` (cols)
	`create_iter` ()
	`describe_column` (col)
	`dump` (to_stream)
	`dump_as_string` ()
	`export_to_file` (format, file, cols, rows, options)
	`export_to_string` (format, cols, rows, options)
	`freeze` ()
	`get_access_flags` ()
	`get_attributes_at` (col, row)
	`get_column_index` (name)
	`get_column_name` (col)
	`get_column_title` (col)
	`get_n_columns` ()
	`get_n_rows` ()
	`get_notify` ()
	`get_row_from_values` (values, cols_index)
	`get_typed_value_at` (col, row, expected_type, nullok)
	`get_value_at` (col, row)
	`import_from_file` (file, cols_trans, options)
	`import_from_model` (from_, overwrite, cols_trans)
	`import_from_string` (string, cols_trans, options)
	`iter_at_row` (iter, row)
	`iter_next` (iter)
	`iter_prev` (iter)
	`iter_set_value` (iter, col, value)
	`remove_row` (row)
	`reset` ()
	`row_inserted` (row)
	`row_removed` (row)
	`row_updated` (row)
	`send_hint` (hint, hint_value)
	`set_column_name` (col, name)
	`set_column_title` (col, title)
	`set_notify` (do_notify_changes)
	`set_value_at` (col, row, value)
	`set_values` (row, values)
	`thaw` ()

Virtual Methods¶

	`do_access_changed` ()
	`do_changed` ()
	`do_i_append_row` ()
	`do_i_append_values` (values)
	`do_i_create_iter` ()
	`do_i_describe_column` (col)
	`do_i_find_row` (values, cols_index)
	`do_i_get_access_flags` ()
	`do_i_get_attributes_at` (col, row)
	`do_i_get_exceptions` ()
	`do_i_get_n_columns` ()
	`do_i_get_n_rows` ()
	`do_i_get_notify` ()
	`do_i_get_value_at` (col, row)
	`do_i_iter_at_row` (iter, row)
	`do_i_iter_next` (iter)
	`do_i_iter_prev` (iter)
	`do_i_iter_set_value` (iter, col, value)
	`do_i_remove_row` (row)
	`do_i_send_hint` (hint, hint_value)
	`do_i_set_notify` (do_notify_changes)
	`do_i_set_value_at` (col, row, value)
	`do_i_set_values` (row, values)
	`do_reset` ()
	`do_row_inserted` (row)
	`do_row_removed` (row)
	`do_row_updated` (row)

Properties¶

None

Signals¶

Name	Short Description
`access-changed`	Gets emitted when model's access flags have changed.
`changed`	Gets emitted when any value in model has been changed
`reset`	Gets emitted when model's contents has been completely reset (the number and type of columns may also have changed)
`row-inserted`	Gets emitted when a row has been inserted in model
`row-removed`	Gets emitted when a row has been removed from model
`row-updated`	Gets emitted when a row has been modified in model

Fields¶

None

Class Details¶

class Gda.DataModel¶

Bases:: GObject.GInterface
Structure:: Gda.DataModelIface

classmethod error_quark()¶

Return type:: int

add_data_from_xml_node(node)¶

Parameters:: node (libxml2.NodePtr) – an XML node representing a <gda_array_data> XML node.
Raises:: GLib.Error
Returns:: True if successful, False otherwise.
Return type:: bool

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 GLib.Error from the #GDA_DATA_MODEL_ERROR domain.

append_row()¶

Raises:: GLib.Error
Returns:: the number of the added row, or -1 if an error occurred
Return type:: int

Appends a row to the data model (the new row will possibly have None 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 GLib.Error from the #GDA_DATA_MODEL_ERROR domain.

append_values(values)¶

Parameters:: values ([GObject.Value] or None) – GLib.List of GObject.Value representing the row to add. The length must match model’s column count. These GObject.Value are value-copied (the user is still responsible for freeing them).
Raises:: GLib.Error
Returns:: the number of the added row, or -1 if an error occurred
Return type:: int

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

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

array_copy_model()¶

Raises:: GLib.Error
Returns:: a new data model, or None if an error occurred
Return type:: Gda.DataModelArray or None

Makes a copy of self into a new Gda.DataModelArray object

array_copy_model_ext(cols)¶

Parameters:: cols ([int]) – array of self's columns to copy into the new array, not None
Raises:: GLib.Error
Returns:: a new data model, or None if an error occurred
Return type:: Gda.DataModelArray or None

Like Gda.DataModel.array_copy_model(), makes a copy of self, but copies only some columns.

New in version 5.2.0.

create_iter()¶

Returns:: a Gda.DataModelIter object, or None if an error occurred
Return type:: Gda.DataModelIter

Creates a new iterator object Gda.DataModelIter object which can be used to iterate through rows in self. The new Gda.DataModelIter does not hold any reference to self (ie. if self 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 Gda.DataModelIter object may be created, or a reference to an already existing Gda.DataModelIter may be returned. For example if self 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 Gda.DataModelIter is created, then the row it represents is undefined.

For models which can be accessed randomly, any row can be set using Gda.DataModelIter.move_to_row(), and for models which are accessible sequentially only then use Gda.DataModelIter.move_next() (and Gda.DataModelIter.move_prev() if supported).

Note: for the Gda.DataProxy data model (which proxies any Gda.DataModel 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 Gda.DataModelIter in which all the proxy’s columns appear, create it using:

iter = g_object_new (GDA_TYPE_DATA_MODEL_ITER, "data-model", proxy, NULL);

describe_column(col)¶

Parameters:: col (int) – column number.
Returns:: the description of the column.
Return type:: Gda.Column or None

Queries the underlying data model implementation for a description of a given column. That description is returned in the form of a Gda.Column structure, which contains all the information about the given column in the data model.

WARNING: the returned Gda.Column object belongs to the self model and and should not be destroyed; any modification will affect the whole data model.

dump(to_stream)¶

Parameters:: to_stream (object or None) – where to dump the data model

Dumps a textual representation of the self to the to_stream stream

The following environment variables can affect the resulting output:

GDA_DATA_MODEL_DUMP_ROW_NUMBERS: if set, the first column of the output will contain row numbers
GDA_DATA_MODEL_DUMP_ATTRIBUTES: if set, also dump the data model’s columns’ types and value’s attributes
GDA_DATA_MODEL_DUMP_TITLE: if set, also dump the data model’s title
GDA_DATA_MODEL_NULL_AS_EMPTY: if set, replace the ‘None' string with an empty string for None values
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

dump_as_string()¶

Returns:: a new string.
Return type:: str

Dumps a textual representation of the self into a new string. The main differences with Gda.DataModel.export_to_string() 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:

GDA_DATA_MODEL_DUMP_ROW_NUMBERS: if set, the first column of the output will contain row numbers
GDA_DATA_MODEL_DUMP_TITLE: if set, also dump the data model’s title
GDA_DATA_MODEL_NULL_AS_EMPTY: if set, replace the ‘None' string with an empty string for None values
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

export_to_file(format, file, cols, rows, options)¶

Parameters:

format (Gda.DataModelIOFormat) – the format in which to export data
file (str) – the filename to export to
cols ([int] or None) – an array containing which columns of self will be exported, or None for all columns
rows ([int] or None) – an array containing which rows of self will be exported, or None for all rows
options (Gda.Set) – list of options for the export

Raises:

GLib.Error

Returns:

True if no error occurred

Return type:

bool

Exports data contained in self 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.DataHandler.get_default()) unless the “cnc” property has been set and points to a Gda.Connection to use that connection’s date format.

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
“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
“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
“NAMES_ON_FIRST_LINE”: a boolean value which, if set to True and in case of a CSV or Gda.DataModelIOFormat.TEXT_TABLE export, will add a first line with the name each exported field (note that “FIELDS_NAME” is also accepted as a synonym)
“NAME”: a string value used to name the exported data if the export format is XML or Gda.DataModelIOFormat.TEXT_TABLE
“OVERWRITE”: a boolean value which tells if the file must be over-written if it already exists.
“NULL_AS_EMPTY”: a boolean value which, if set to True and in case of a CSV or Gda.DataModelIOFormat.TEXT_TABLE export, will render and None value as the empty string (instead of the ‘None' string)
“INVALID_AS_NULL”: a boolean value which, if set to True, considers any invalid data (for example for the date related values) as None
“COLUMN_SEPARATORS”: a boolean value which, if set to True, adds a separators lines between each column, if the export format is Gda.DataModelIOFormat.TEXT_TABLE
“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.DataModelIOFormat.TEXT_TABLE
“ROW_NUMBERS”: a boolean value which, if set to True, prepends a column with row numbers, if the export format is Gda.DataModelIOFormat.TEXT_TABLE
“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.DataModelIOFormat.TEXT_TABLE

Warning: this function uses a Gda.DataModelIter iterator, and if self does not offer a random access (check using Gda.DataModel.get_access_flags()), the iterator will be the same as normally used to access data in self 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 GLib.Error from the #GDA_DATA_MODEL_ERROR domain.

export_to_string(format, cols, rows, options)¶

Parameters:

format (Gda.DataModelIOFormat) – the format in which to export data
cols ([int] or None) – an array containing which columns of self will be exported, or None for all columns
rows ([int] or None) – an array containing which rows of self will be exported, or None for all rows
options (Gda.Set) – list of options for the export

Returns:

a new string, use GLib.free() when no longer needed

Return type:

str

Exports data contained in self to a string; the format is specified using the format argument, see the Gda.DataModel.export_to_file() documentation for more information about the options argument (except for the “OVERWRITE” option).

Warning: this function uses a Gda.DataModelIter iterator, and if self does not offer a random access (check using Gda.DataModel.get_access_flags()), the iterator will be the same as normally used to access data in self previously to calling this method, and this iterator will be moved (point to another row).

freeze()¶: Disables notifications of changes on the given data model. To re-enable notifications again, you should call the Gda.DataModel.thaw function.

get_access_flags()¶

Returns:: an ORed value of Gda.DataModelAccessFlags flags
Return type:: Gda.DataModelAccessFlags

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

get_attributes_at(col, row)¶

Parameters:

col (int) – a valid column number
row (int) – a valid row number, or -1

Returns:

the attributes as an ORed value of Gda.ValueAttribute

Return type:

Gda.ValueAttribute

Get the attributes of the value stored at (row, col) in self, which is an ORed value of Gda.ValueAttribute 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 self.

get_column_index(name)¶

Parameters:: name (str) – a column name
Returns:: the column index, or -1 if no column named name was found
Return type:: int

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

get_column_name(col)¶

Parameters:: col (int) – column number.
Returns:: the name for the given column in a data model object.
Return type:: str

New in version 3.2.

get_column_title(col)¶

Parameters:: col (int) – column number.
Returns:: the title for the given column in a data model object.
Return type:: str

get_n_columns()¶

Returns:: the number of columns in the given data model, or -1 if unknown.
Return type:: int

get_n_rows()¶

Returns:: the number of rows in the given data model, or -1 if the number of rows is not known
Return type:: int

get_notify()¶

Return type:: bool

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

get_row_from_values(values, cols_index)¶

Parameters:

values ([GObject.Value]) – a list of GObject.Value values (no None is allowed)
cols_index ([int]) – an array of int containing the column number to match each value of values

Returns:

the requested row number, of -1 if not found

Return type:

int

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

get_typed_value_at(col, row, expected_type, nullok)¶

Parameters:

col (int) – a valid column number.
row (int) – a valid row number.
expected_type (GObject.GType) – the expected data type of the returned value
nullok (bool) – if True, then None values (value of type %GDA_TYPE_NULL) will not generate any error

Raises:

GLib.Error

Returns:

a GObject.Value containing the value stored in the given position, or None on error (out-of-bound position, wrong data type, etc).

Return type:

GObject.Value or None

Upon errors None will be returned and error will be assigned a GLib.Error from the #GDA_DATA_MODEL_ERROR domain.

This method is similar to Gda.DataModel.get_value_at(), except that it also allows one to specify the expected GObject.GType of the value to get: if the data model returned a GObject.Value of a type different than the expected one, then this method returns None and an error code.

Note: the same limitations and usage instructions apply as for Gda.DataModel.get_value_at().

Upon errors None will be returned and error will be assigned a GLib.Error from the #GDA_DATA_MODEL_ERROR domain.

get_value_at(col, row)¶

Parameters:

col (int) – a valid column number.
row (int) – a valid row number.

Raises:

GLib.Error

Returns:

a GObject.Value containing the value stored in the given position, or None on error (out-of-bound position, etc).

Return type:

GObject.Value or None

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

Upon errors None will be returned and error will be assigned a GLib.Error 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 Gda.DataModelIter object, obtained using Gda.DataModel.create_iter().

Note1: the returned GObject.Value 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.DataModel.get_value_at() for different values of the same row.

If you want to modify a value stored in a Gda.DataModel, use the Gda.DataModel.set_value_at() or Gda.DataModel.set_values() methods.

Upon errors None will be returned and error will be assigned a GLib.Error from the #GDA_DATA_MODEL_ERROR domain.

import_from_file(file, cols_trans, options)¶

Parameters:

file (str) – the filename to import from
cols_trans ({int: int} or None) – a GLib.HashTable for columns translating, or None, see Gda.DataModel.import_from_model()
options (Gda.Set) – list of options for the export

Raises:

GLib.Error

Returns:

True if no error occurred

Return type:

bool

Imports data contained in the file file into self; the format is detected.

Upon errors False will be returned and error will be assigned a GLib.Error from the #GDA_DATA_MODEL_ERROR domain.

import_from_model(from_, overwrite, cols_trans)¶

Parameters:

from (Gda.DataModel) – the source Gda.DataModel
overwrite (bool) – True if self is completely overwritten by from's data, and False if from's data is appended to self
cols_trans ({int: int} or None) – a GLib.HashTable for columns translating, or None

Raises:

GLib.Error

Returns:

True if no error occurred.

Return type:

bool

Copy the contents of the from data model to the self data model. The copy stops as soon as an error orrurs.

The cols_trans is a hash table for which keys are self columns numbers and the values are the corresponding column numbers in the from data model. To set the values of a column in self to None, create an entry in the hash table with a negative value. For example:

GHashTable *hash;
gint *ptr;
hash = g_hash_table_new_full (g_int_hash, g_int_equal, g_free, NULL);
ptr = g_new (gint, 1);
*ptr = 2;
g_hash_table_insert (hash, ptr, GINT_TO_POINTER (3));
gda_data_model_import_from_model (...);
g_hash_table_free (hash);

Upon errors False will be returned and error will be assigned a GLib.Error from the #GDA_DATA_MODEL_ERROR domain.

import_from_string(string, cols_trans, options)¶

Parameters:

string (str) – the string to import data from
cols_trans ({int: int} or None) – a hash table containing which columns of self will be imported, or None for all columns, see Gda.DataModel.import_from_model()
options (Gda.Set) – list of options for the export

Raises:

GLib.Error

Returns:

True if no error occurred.

Return type:

bool

Loads the data from string into self.

Upon errors False will be returned and error will be assigned a GLib.Error from the #GDA_DATA_MODEL_ERROR domain.

iter_at_row(iter, row)¶

Parameters:

iter (Gda.DataModelIter) – a Gda.DataModelIter object.
row (int) – a row to point to with iter

Return type:

bool

Moves iter to the row number given by row.

Deprecated since version 5.2: use Gda.DataModelIter.move_to_row() instead

iter_next(iter)¶

Parameters:: iter (Gda.DataModelIter) – a Gda.DataModelIter object.
Return type:: bool

Moves iter to the next row in self.

Deprecated since version 5.2: use Gda.DataModelIter.move_next() instead

iter_prev(iter)¶

Parameters:: iter (Gda.DataModelIter) – a Gda.DataModelIter object.
Return type:: bool

Moves iter to the next row in self.

Deprecated since version 5.2: use Gda.DataModelIter.move_prev() instead

iter_set_value(iter, col, value)¶

Parameters:

iter (Gda.DataModelIter) – a Gda.DataModelIter object.
col (int) – the number of column to set value to
value (GObject.Value) – the to use to set on

Raises:

GLib.Error

Return type:

bool

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

Deprecated since version 5.2: use Gda.DataModelIter.set_value_at() instead

remove_row(row)¶

Parameters:: row (int) – the row number to be removed.
Raises:: GLib.Error
Returns:: True if successful, False otherwise.
Return type:: bool

Removes a row from the data model.

Upon errors False will be returned and error will be assigned a GLib.Error from the #GDA_DATA_MODEL_ERROR domain.

reset()¶: Emits the ‘reset’ and ‘changed’ signal on self.

row_inserted(row)¶

Parameters:: row (int) – row number.

Emits the ‘row_inserted’ and ‘changed’ signals on self.

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

row_removed(row)¶

Parameters:: row (int) – row number.

Emits the ‘row_removed’ and ‘changed’ signal on self.

This method should only be used by Gda.DataModel implementations to signal that a row has been removed

row_updated(row)¶

Parameters:: row (int) – row number.

Emits the ‘row_updated’ and ‘changed’ signals on self.

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

send_hint(hint, hint_value)¶

Parameters:

hint (Gda.DataModelHint) – a hint to send to the model
hint_value (GObject.Value or None) – an optional value to specify the hint, or None

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

set_column_name(col, name)¶

Parameters:

col (int) – column number
name (str) – name for the given column.

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

New in version 3.2.

set_column_title(col, title)¶

Parameters:

col (int) – column number
title (str) – title for the given column.

Sets the title of the given col in self.

set_notify(do_notify_changes)¶

Parameters:: do_notify_changes (bool) – Set to True if you require notifications.

Enable or disable notifications changes on the given data model.

Deprecated since version 5.2: use Gda.DataModel.freeze() and Gda.DataModel.thaw() instead

set_value_at(col, row, value)¶

Parameters:

col (int) – column number.
row (int) – row number.
value (GObject.Value) – a GObject.Value (not None)

Raises:

GLib.Error

Returns:

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

Return type:

bool

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

Upon errors False will be returned and error will be assigned a GLib.Error from the #GDA_DATA_MODEL_ERROR domain.

set_values(row, values)¶

Parameters:

row (int) – row number.
values ([GObject.Value] or None) – a list of GObject.Value (or None), one for at most the number of columns of self

Raises:

GLib.Error

Returns:

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

Return type:

bool

In a similar way to Gda.DataModel.set_value_at(), this method modifies a data model’s contents by setting several values at once.

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

Upon errors False will be returned and error will be assigned a GLib.Error from the #GDA_DATA_MODEL_ERROR domain.

thaw()¶: Re-enables notifications of changes on the given data model.

do_access_changed() virtual¶

do_changed() virtual¶

do_i_append_row() virtual¶

Returns:: the number of the added row, or -1 if an error occurred
Return type:: int

Appends a row to the data model (the new row will possibly have None 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 GLib.Error from the #GDA_DATA_MODEL_ERROR domain.

do_i_append_values(values) virtual¶

Parameters:: values ([GObject.Value] or None) – GLib.List of GObject.Value representing the row to add. The length must match model’s column count. These GObject.Value are value-copied (the user is still responsible for freeing them).
Returns:: the number of the added row, or -1 if an error occurred
Return type:: int

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

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

do_i_create_iter() virtual¶

Returns:: a Gda.DataModelIter object, or None if an error occurred
Return type:: Gda.DataModelIter

Creates a new iterator object Gda.DataModelIter object which can be used to iterate through rows in model. The new Gda.DataModelIter 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 Gda.DataModelIter object may be created, or a reference to an already existing Gda.DataModelIter 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 Gda.DataModelIter is created, then the row it represents is undefined.

For models which can be accessed randomly, any row can be set using Gda.DataModelIter.move_to_row(), and for models which are accessible sequentially only then use Gda.DataModelIter.move_next() (and Gda.DataModelIter.move_prev() if supported).

Note: for the Gda.DataProxy data model (which proxies any Gda.DataModel 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 Gda.DataModelIter in which all the proxy’s columns appear, create it using:

iter = g_object_new (GDA_TYPE_DATA_MODEL_ITER, "data-model", proxy, NULL);

do_i_describe_column(col) virtual¶

Parameters:: col (int) – column number.
Returns:: the description of the column.
Return type:: Gda.Column or None

Queries the underlying data model implementation for a description of a given column. That description is returned in the form of a Gda.Column structure, which contains all the information about the given column in the data model.

WARNING: the returned Gda.Column object belongs to the model model and and should not be destroyed; any modification will affect the whole data model.

do_i_find_row(values, cols_index) virtual¶

Parameters:

values ([GObject.Value]) – a list of GObject.Value values (no None is allowed)
cols_index ([int]) – an array of int containing the column number to match each value of values

Returns:

the requested row number, of -1 if not found

Return type:

int

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

do_i_get_access_flags() virtual¶

Returns:: an ORed value of Gda.DataModelAccessFlags flags
Return type:: Gda.DataModelAccessFlags

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

do_i_get_attributes_at(col, row) virtual¶

Parameters:

col (int) – a valid column number
row (int) – a valid row number, or -1

Returns:

the attributes as an ORed value of Gda.ValueAttribute

Return type:

Gda.ValueAttribute

Get the attributes of the value stored at (row, col) in model, which is an ORed value of Gda.ValueAttribute 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.

do_i_get_exceptions() virtual¶

Returns:: a pointer to a None terminated array of GLib.Error, or None.
Return type:: [GLib.Error]

Get the global data model exception(s) that occurred when using model. This is useful for example for the LDAP related data models where some rows may be missing because the LDAP search has reached a limit imposed by the LDAP server.

New in version 4.2.6.

do_i_get_n_columns() virtual¶

Returns:: the number of columns in the given data model, or -1 if unknown.
Return type:: int

do_i_get_n_rows() virtual¶

Returns:: the number of rows in the given data model, or -1 if the number of rows is not known
Return type:: int

do_i_get_notify() virtual¶

Return type:: bool

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

do_i_get_value_at(col, row) virtual¶

Parameters:

col (int) – a valid column number.
row (int) – a valid row number.

Returns:

a GObject.Value containing the value stored in the given position, or None on error (out-of-bound position, etc).

Return type:

GObject.Value or None

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

Upon errors None will be returned and error will be assigned a GLib.Error 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 Gda.DataModelIter object, obtained using Gda.DataModel.create_iter().

Note1: the returned GObject.Value 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.DataModel.get_value_at() for different values of the same row.

If you want to modify a value stored in a Gda.DataModel, use the Gda.DataModel.set_value_at() or Gda.DataModel.set_values() methods.

Upon errors None will be returned and error will be assigned a GLib.Error from the #GDA_DATA_MODEL_ERROR domain.

do_i_iter_at_row(iter, row) virtual¶

Parameters:

iter (Gda.DataModelIter) – a Gda.DataModelIter object.
row (int) – a row to point to with iter

Return type:

bool

Moves iter to the row number given by row.

Deprecated since version 5.2: use Gda.DataModelIter.move_to_row() instead

do_i_iter_next(iter) virtual¶

Parameters:: iter (Gda.DataModelIter) – a Gda.DataModelIter object.
Return type:: bool

Moves iter to the next row in model.

Deprecated since version 5.2: use Gda.DataModelIter.move_next() instead

do_i_iter_prev(iter) virtual¶

Parameters:: iter (Gda.DataModelIter) – a Gda.DataModelIter object.
Return type:: bool

Moves iter to the next row in model.

Deprecated since version 5.2: use Gda.DataModelIter.move_prev() instead

do_i_iter_set_value(iter, col, value) virtual¶

Parameters:

iter (Gda.DataModelIter) – a Gda.DataModelIter object.
col (int) – the number of column to set value to
value (GObject.Value) – the to use to set on

Return type:

bool

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

Deprecated since version 5.2: use Gda.DataModelIter.set_value_at() instead

do_i_remove_row(row) virtual¶

Parameters:: row (int) – the row number to be removed.
Returns:: True if successful, False otherwise.
Return type:: bool

Removes a row from the data model.

Upon errors False will be returned and error will be assigned a GLib.Error from the #GDA_DATA_MODEL_ERROR domain.

do_i_send_hint(hint, hint_value) virtual¶

Parameters:

hint (Gda.DataModelHint) – a hint to send to the model
hint_value (GObject.Value or None) – an optional value to specify the hint, or None

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

do_i_set_notify(do_notify_changes) virtual¶

Parameters:: do_notify_changes (bool) – Set to True if you require notifications.

Enable or disable notifications changes on the given data model.

Deprecated since version 5.2: use Gda.DataModel.freeze() and Gda.DataModel.thaw() instead

do_i_set_value_at(col, row, value) virtual¶

Parameters:

col (int) – column number.
row (int) – row number.
value (GObject.Value) – a GObject.Value (not None)

Returns:

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

Return type:

bool

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

Upon errors False will be returned and error will be assigned a GLib.Error from the #GDA_DATA_MODEL_ERROR domain.

do_i_set_values(row, values) virtual¶

Parameters:

row (int) – row number.
values ([GObject.Value] or None) – a list of GObject.Value (or None), 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

Return type:

bool

In a similar way to Gda.DataModel.set_value_at(), this method modifies a data model’s contents by setting several values at once.

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

Upon errors False will be returned and error will be assigned a GLib.Error from the #GDA_DATA_MODEL_ERROR domain.

do_reset() virtual¶: Emits the ‘reset’ and ‘changed’ signal on model.

do_row_inserted(row) virtual¶

Parameters:: row (int) – row number.

Emits the ‘row_inserted’ and ‘changed’ signals on model.

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

do_row_removed(row) virtual¶

Parameters:: row (int) – row number.

Emits the ‘row_removed’ and ‘changed’ signal on model.

This method should only be used by Gda.DataModel implementations to signal that a row has been removed

do_row_updated(row) virtual¶

Parameters:: row (int) – row number.

Emits the ‘row_updated’ and ‘changed’ signals on model.

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

Signal Details¶

Gda.DataModel.signals.access_changed(data_model)¶

Signal Name:: access-changed
Flags:: RUN_LAST
Parameters:: data_model (Gda.DataModel) – The object which received the signal

Gets emitted when model's access flags have changed. Use Gda.DataModel.get_access_flags() to get the access flags.

Gda.DataModel.signals.changed(data_model)¶

Signal Name:: changed
Flags:: RUN_LAST
Parameters:: data_model (Gda.DataModel) – The object which received the signal

Gets emitted when any value in model has been changed

Gda.DataModel.signals.reset(data_model)¶

Signal Name:: reset
Flags:: RUN_LAST
Parameters:: data_model (Gda.DataModel) – The object which received the signal

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

Gda.DataModel.signals.row_inserted(data_model, row)¶

Signal Name:

row-inserted

Flags:

RUN_LAST

Parameters:

data_model (Gda.DataModel) – The object which received the signal
row (int) – the row number

Gets emitted when a row has been inserted in model

Gda.DataModel.signals.row_removed(data_model, row)¶

Signal Name:

row-removed

Flags:

RUN_LAST

Parameters:

data_model (Gda.DataModel) – The object which received the signal
row (int) – the row number

Gets emitted when a row has been removed from model

Gda.DataModel.signals.row_updated(data_model, row)¶

Signal Name:

row-updated

Flags:

RUN_LAST

Parameters:

data_model (Gda.DataModel) – The object which received the signal
row (int) – the row number

Gets emitted when a row has been modified in model