Gnome::Gda::DataModel Class Reference

Abstract DataModel (Base class for all DataModels). More...

#include <datamodel.h>

Inheritance diagram for Gnome::Gda::DataModel:

Inheritance graph
[legend]
List of all members.

Public Member Functions

virtual ~DataModel ()
GdaDataModel* gobj ()
 Provides access to the underlying C GObject.
const GdaDataModel* gobj () const
 Provides access to the underlying C GObject.
void freeze ()
 Disables notifications of changes on the given data model.
void thaw ()
 Re-enables notifications of changes on the given data model.
int get_n_rows () const
int get_n_columns () const
Glib::RefPtr<Columndescribe_column (int col)
 Queries the underlying data model implementation for a description of a given column.
Glib::RefPtr<const Columndescribe_column (int col) const
 Queries the underlying data model implementation for a description of a given column.
int get_column_index (const Glib::ustring& name) const
 Get the index of the column named name in model.
Glib::ustring get_column_title (int col) const
void set_column_title (int col, const Glib::ustring& title)
 Sets the title of the given col in model .
Value get_value_at (int col, int row) const
Value get_value_at (const Glib::ustring& column_name, int row) const
ValueAttribute get_attributes_at (int col, int row)
 Get the attributes of the value stored at (row, col) in proxy , which is an ORed value of Gda::ValueAttribute flags.
Glib::RefPtr<DataModelItercreate_iter ()
 Creates a new iterator object Gda::DataModelIter object which can be used to iterate through rows in model .
bool set_value_at (int col, int row, const Value& value, std::auto_ptr<Glib::Error>& error)
bool is_updatable () const
 Tells if model can be modified.
DataModelAccessFlags get_access_flags () const
 Get the attributes of model such as how to access the data it contains if it's modifiable, etc.
int append_values (const ValueList& values, std::auto_ptr<Glib::Error>& error)
 Appends a row to the given data model.
bool append_row (std::auto_ptr<Glib::Error>& error)
 Appends a row to the data model.
bool remove_row (int row, std::auto_ptr<Glib::Error>& error)
 Removes a row from the data model.
void send_hint (DataModelHint hint, const Value& hint_value)
 Sends a hint to the data model.
bool import_from_string (const Glib::ustring& string, GHashTable* cols_trans, const Glib::RefPtr<const ParameterList>& options, std::auto_ptr<Glib::Error>& error)
 Loads the data from string into model .
bool import_from_file (const std::string& file, GHashTable* cols_trans, const Glib::RefPtr<const ParameterList>& options, std::auto_ptr<Glib::Error>& error)
 Imports data contained in the file file into model ; the format is detected.
Glib::ustring to_xml (const Glib::ArrayHandle<int>& cols, const Glib::StringArrayHandle& names) const
void dump (FILE* to_stream) const
 Dumps a textual representation of the model to the to_stream stream.
Glib::ustring dump_as_string () const
 Dumps a textual representation of the model into a new string.
void signal_emit_changed ()
 Notifies listeners of the given data model object of changes in the underlying data.
void row_inserted (int row)
 Emits the 'row_inserted' and 'changed' signals on model .
void row_updated (int row)
 Emits the 'row_updated' and 'changed' signals on model .
void row_removed (int row)
 Emits the 'row_removed' and 'changed' signal on model .
bool move_iter_at_row_default (const Glib::RefPtr<DataModelIter>& iter, int row)
bool move_iter_next_default (const Glib::RefPtr<DataModelIter>& iter)
bool move_iter_prev_default (const Glib::RefPtr<DataModelIter>& iter)
bool set_values (int row, const ValueList& values, std::auto_ptr<Glib::Error>& error)
 If any value in values is actually 0, then it is considered as a default value.
Glib::RefPtr<DataModelcopy (std::auto_ptr<Glib::Error>& error) const
 Makes a copy of src into a new Gda::DataModelArray object.
Glib::SignalProxy1< void,
int > 
signal_row_inserted ()
Glib::SignalProxy1< void,
int > 
signal_row_updated ()
Glib::SignalProxy1< void,
int > 
signal_row_removed ()

Static Public Member Functions

static void add_interface (GType gtype_implementer)

Related Functions

(Note that these are not member functions.)

Glib::RefPtr<Gnome::Gda::DataModelwrap (GdaDataModel* object, bool take_copy=false)

Detailed Description

Abstract DataModel (Base class for all DataModels).

A DataModel 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 DataModel 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 by using functions provided by the model. The actual operations that a data model permits can be discovered using the get_access_flags() method.

Again, depending on the real implementation, data retreival can be done either by accessing direct random values located by their row and column, or by using a DataModelIter cursor, or both. Use the get_access_flags() method to discover how the data model can be accessed. Note that a Datamodel 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 a 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 by using the get_value_at(), but they 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:


Constructor & Destructor Documentation

virtual Gnome::Gda::DataModel::~DataModel (  )  [virtual]


Member Function Documentation

static void Gnome::Gda::DataModel::add_interface ( GType  gtype_implementer  )  [static]

bool Gnome::Gda::DataModel::append_row ( std::auto_ptr< Glib::Error > &  error  ) 

Appends a row to the data model.

Parameters:
error A place to store errors, or 0.
Returns:
The number of the added row, or -1 if an error occurred.

int Gnome::Gda::DataModel::append_values ( const ValueList values,
std::auto_ptr< Glib::Error > &  error 
)

Appends a row to the given data model.

If any value in values is actually 0, then it is considered as a default value.

Parameters:
values G::List of G::Value* representing the row to add. The length must match model's column count. These G::Value are value-copied (the user is still responsible for freeing them).
error A place to store errors, or 0.
Returns:
The number of the added row, or -1 if an error occurred.

Glib::RefPtr<DataModel> Gnome::Gda::DataModel::copy ( std::auto_ptr< Glib::Error > &  error  )  const

Makes a copy of src into a new Gda::DataModelArray object.

Parameters:
error A place to store errors, or 0.
Returns:
A new data model, or 0 if an error occurred.

Glib::RefPtr<DataModelIter> Gnome::Gda::DataModel::create_iter (  ) 

Creates a new iterator object Gda::DataModelIter object which can be used to iterate through rows in model .

The row the returned Gda::DataModelIter represents is undefined. For models which can be accessed randomly the correspoding row can be set using move_iter_at_row(), and for models which are accessible sequentially only then the first row will be fetched using move_iter_next().

Returns:
A new Gda::DataModelIter object, or 0 if an error occurred.

Glib::RefPtr<const Column> Gnome::Gda::DataModel::describe_column ( int  col  )  const

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 impact the whole data model.

Parameters:
col Column number.
Returns:
The description of the column.

Glib::RefPtr<Column> Gnome::Gda::DataModel::describe_column ( int  col  ) 

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 impact the whole data model.

Parameters:
col Column number.
Returns:
The description of the column.

void Gnome::Gda::DataModel::dump ( FILE *  to_stream  )  const

Dumps a textual representation of the model to the to_stream stream.

Parameters:
to_stream Where to dump the data model.

Glib::ustring Gnome::Gda::DataModel::dump_as_string (  )  const

Dumps a textual representation of the model into a new string.

Returns:
A new string.

void Gnome::Gda::DataModel::freeze (  ) 

Disables notifications of changes on the given data model.

To re-enable notifications again, you should call the gda_data_model_thaw function.

DataModelAccessFlags Gnome::Gda::DataModel::get_access_flags (  )  const

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

Returns:
An ORed value of Gda::DataModelAccessFlags flags.

ValueAttribute Gnome::Gda::DataModel::get_attributes_at ( int  col,
int  row 
)

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

Parameters:
col A valid column number.
row A valid row number, or -1.
Returns:
The attributes as an ORed value of Gda::ValueAttribute.

int Gnome::Gda::DataModel::get_column_index ( const Glib::ustring name  )  const

Get the index of the column named name in model.

Parameters:
name A column name.
Returns:
The column index, or -1 if no column named name was found.

Glib::ustring Gnome::Gda::DataModel::get_column_title ( int  col  )  const

Parameters:
col Column number.
Returns:
The title for the given column in a data model object.

int Gnome::Gda::DataModel::get_n_columns (  )  const

Returns:
The number of columns in the given data model.

int Gnome::Gda::DataModel::get_n_rows (  )  const

Returns:
The number of rows in the given data model, or -1 if the number of rows is not known.

Value Gnome::Gda::DataModel::get_value_at ( const Glib::ustring column_name,
int  row 
) const

Value Gnome::Gda::DataModel::get_value_at ( int  col,
int  row 
) const

const GdaDataModel* Gnome::Gda::DataModel::gobj (  )  const [inline]

Provides access to the underlying C GObject.

Reimplemented from Glib::Interface.

Reimplemented in Gnome::Gda::DataModelArray, Gnome::Gda::DataModelFilterSQL, Gnome::Gda::DataModelHash, Gnome::Gda::DataModelImport, Gnome::Gda::DataModelQuery, Gnome::Gda::DataModelRow, and Gnome::Gda::DataProxy.

GdaDataModel* Gnome::Gda::DataModel::gobj (  )  [inline]

Provides access to the underlying C GObject.

Reimplemented from Glib::Interface.

Reimplemented in Gnome::Gda::DataModelArray, Gnome::Gda::DataModelFilterSQL, Gnome::Gda::DataModelHash, Gnome::Gda::DataModelImport, Gnome::Gda::DataModelQuery, Gnome::Gda::DataModelRow, and Gnome::Gda::DataProxy.

bool Gnome::Gda::DataModel::import_from_file ( const std::string &  file,
GHashTable *  cols_trans,
const Glib::RefPtr<const ParameterList>&  options,
std::auto_ptr< Glib::Error > &  error 
)

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

Parameters:
file The filename to import from.
cols_trans A G::HashTable for columns translating, or 0.
options List of options for the export.
error A place to store errors, or 0.
Returns:
true if no error occurred.

bool Gnome::Gda::DataModel::import_from_string ( const Glib::ustring string,
GHashTable *  cols_trans,
const Glib::RefPtr<const ParameterList>&  options,
std::auto_ptr< Glib::Error > &  error 
)

Loads the data from string into model .

Parameters:
string The string to import data from.
cols_trans A hash table containing which columns of model will be imported, or 0 for all columns.
options List of options for the export.
error A place to store errors, or 0.
Returns:
true if no error occurred.

bool Gnome::Gda::DataModel::is_updatable (  )  const

Tells if model can be modified.

Returns:
true if model can be modified.

bool Gnome::Gda::DataModel::move_iter_at_row_default ( const Glib::RefPtr<DataModelIter>&  iter,
int  row 
)

bool Gnome::Gda::DataModel::move_iter_next_default ( const Glib::RefPtr<DataModelIter>&  iter  ) 

bool Gnome::Gda::DataModel::move_iter_prev_default ( const Glib::RefPtr<DataModelIter>&  iter  ) 

bool Gnome::Gda::DataModel::remove_row ( int  row,
std::auto_ptr< Glib::Error > &  error 
)

Removes a row from the data model.

Parameters:
row The row number to be removed.
error A place to store errors, or 0.
Returns:
true if successful, false otherwise.

void Gnome::Gda::DataModel::row_inserted ( int  row  ) 

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

Parameters:
row Row number.

void Gnome::Gda::DataModel::row_removed ( int  row  ) 

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

Parameters:
row Row number.

void Gnome::Gda::DataModel::row_updated ( int  row  ) 

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

Parameters:
row Row number.

void Gnome::Gda::DataModel::send_hint ( DataModelHint  hint,
const Value 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

Parameters:
hint A hint to send to the model.
hint_value An optional value to specify the hint, or 0.

void Gnome::Gda::DataModel::set_column_title ( int  col,
const Glib::ustring title 
)

Sets the title of the given col in model .

Parameters:
col Column number.
title Title for the given column.

bool Gnome::Gda::DataModel::set_value_at ( int  col,
int  row,
const Value value,
std::auto_ptr< Glib::Error > &  error 
)

Parameters:
col Column number.
row Row number.
value A G::Value, or 0.
error A place to store errors, or 0.
Returns:
true if the value in the data model has been updated and no error occurred.

bool Gnome::Gda::DataModel::set_values ( int  row,
const ValueList values,
std::auto_ptr< Glib::Error > &  error 
)

If any value in values is actually 0, then it is considered as a default value.

Parameters:
row Row number.
values A list of G::Value, one for each n (<nb_cols) columns of model .
error A place to store errors, or 0.
Returns:
true if the value in the data model has been updated and no error occurred.

void Gnome::Gda::DataModel::signal_emit_changed (  ) 

Notifies listeners of the given data model object of changes in the underlying data.

Listeners usually will connect themselves to the "changed" signal in the Gda::DataModel class, thus being notified of any new data being appended or removed from the data model.

Glib::SignalProxy1< void,int > Gnome::Gda::DataModel::signal_row_inserted (  ) 

Prototype:
void row_inserted(int row)

Glib::SignalProxy1< void,int > Gnome::Gda::DataModel::signal_row_removed (  ) 

Prototype:
void row_removed(int row)

Glib::SignalProxy1< void,int > Gnome::Gda::DataModel::signal_row_updated (  ) 

Prototype:
void row_updated(int row)

void Gnome::Gda::DataModel::thaw (  ) 

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

Glib::ustring Gnome::Gda::DataModel::to_xml ( const Glib::ArrayHandle< int > &  cols,
const Glib::StringArrayHandle names 
) const


Friends And Related Function Documentation

Glib::RefPtr<Gnome::Gda::DataModel> wrap ( GdaDataModel *  object,
bool  take_copy = false 
) [related]

Parameters:
object The C instance
take_copy False if the result should take ownership of the C instance. True if it should take a new copy or ref.
Returns:
A C++ instance that wraps this C instance.


The documentation for this class was generated from the following file:
Generated on Sat Feb 10 20:06:31 2007 for libgdamm by  doxygen 1.4.7