libgdamm: Gnome::Gda::DataSelect Class Reference

libgdamm 4.99.8

- Main Page
- Related Pages
- Modules
- Namespaces
- Classes

- Class List
- Class Index
- Class Hierarchy
- Class Members

Public Member Functions | Static Public Member Functions | Related Functions | List of all members
Gnome::Gda::DataSelect Class Reference
Data Models

Data models returned by the execution of a SELECT statement. More...

Inheritance diagram for Gnome::Gda::DataSelect:
[legend]
Collaboration diagram for Gnome::Gda::DataSelect:
[legend]

## Public Member Functions
virtual | ~DataSelect ()
GdaDataSelect* | gobj ()
| Provides access to the underlying C GObject. More...
const GdaDataSelect* | gobj () const
| Provides access to the underlying C GObject. More...
GdaDataSelect* | gobj_copy ()
| Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs. More...
bool | set_row_selection_condition_sql (const Glib::ustring& sql_where)
| Specifies the SQL condition corresponding to the WHERE part of a SELECT statement which would return only 1 row (the expression of the primary key). More...
void | compute_row_selection_condition ()
| Offers the same features as set_row_selection_condition() but the expression is computed from the meta data associated to the connection being used when model was created. More...
void | set_modification_statement (const Glib::RefPtr< Statement >& mod_stmt)
| Informs model that it should allow modifications to the data in some columns and some rows using mod_stmt to propagate those modifications into the database. More...
void | set_modification_statement_sql (const Glib::ustring& sql)
| Offers the same feature as set_modification_statement() but using an SQL statement. More...
void | compute_modification_statements ()
| Makes model try to compute INSERT, UPDATE and DELETE statements to be used when modifying model's contents. More...
void | compute_columns_attributes ()
| Computes correct attributes for each of model's columns, which includes the "NOT <tt>0</tt>" attribute, the default value, the precision and scale for numeric values. More...
Glib::RefPtr< Connection > | get_connection ()
| Get a pointer to the Gda::Connection object which was used when model was created (and which may be used internally by model). More...
void | rerun ()
| Requests that model be re-run to have an updated result. More...
Glib::PropertyProxy< bool > | property_auto_reset ()
| Automatically re-run the SELECT statement if any parameter has changed since it was first executed. More...
Glib::PropertyProxy_ReadOnly < bool > | property_auto_reset () const
| Automatically re-run the SELECT statement if any parameter has changed since it was first executed. More...
Glib::PropertyProxy< bool > | property_store_all_rows ()
| Tells if model has analyzed all the rows. More...
Glib::PropertyProxy_ReadOnly < bool > | property_store_all_rows () const
| Tells if model has analyzed all the rows. More...
Glib::PropertyProxy_ReadOnly < Glib::RefPtr< Connection > > | property_connection () const
| Connection from which this data model is created. More...
Glib::PropertyProxy < Glib::RefPtr< Statement > > | property_delete_stmt ()
| DELETE Statement to be executed to remove data. More...
Glib::PropertyProxy_ReadOnly < Glib::RefPtr< Statement > > | property_delete_stmt () const
| DELETE Statement to be executed to remove data. More...
Glib::PropertyProxy < Glib::RefPtr< Statement > > | property_insert_stmt ()
| INSERT Statement to be executed to add data. More...
Glib::PropertyProxy_ReadOnly < Glib::RefPtr< Statement > > | property_insert_stmt () const
| INSERT Statement to be executed to add data. More...
Glib::PropertyProxy < Glib::RefPtr< Statement > > | property_prepared_stmt ()
| Associated prepared statement (for internal usage). More...
Glib::PropertyProxy_ReadOnly < Glib::RefPtr< Statement > > | property_prepared_stmt () const
| Associated prepared statement (for internal usage). More...
Glib::PropertyProxy < Glib::RefPtr< Statement > > | property_update_stmt ()
| UPDATE Statement to be executed to update data. More...
Glib::PropertyProxy_ReadOnly < Glib::RefPtr< Statement > > | property_update_stmt () const
| UPDATE Statement to be executed to update data. More...
Glib::PropertyProxy_ReadOnly < Glib::RefPtr< Set > > | property_exec_params () const
| GdaSet used when the SELECT statement was executed. More...
Glib::PropertyProxy_ReadOnly < guint > | property_model_usage () const
| Determines how the data model may be used. More...
Public Member Functions inherited from Gnome::Gda::DataModel
virtual | ~DataModel ()
GdaDataModel* | gobj ()
| Provides access to the underlying C GObject. More...
const GdaDataModel* | gobj () const
| Provides access to the underlying C GObject. More...
void | freeze ()
| Disables notifications of changes on the given data model. More...
void | thaw ()
| Re-enables notifications of changes on the given data model. More...
int | get_n_rows () const
int | get_n_columns () const
int | get_column_index (const Glib::ustring& name)
| Get the index of the first column named name in model. More...
Glib::RefPtr< Column > | describe_column (int col)
| Queries the underlying data model implementation for a description of a given column. More...
Glib::RefPtr< const Column > | describe_column (int col) const
| Queries the underlying data model implementation for a description of a given column. More...
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. More...
Value | get_value_at (int col, int row) const
| Retrieves the data stored in the given position (identified by the col and row parameters) on a data model. More...
Value | get_typed_value_at (int col, int row, GType expected_type, bool nullok) const
| Upon errors `0` will be returned and error will be assigned a Error from the Gda::DATA_MODEL_ERROR domain. More...
ValueAttribute | get_attributes_at (int col, int row)
| Get the attributes of the value stored at (row, col) in model, which is an ORed value of Gda::ValueAttribute flags. More...
Glib::RefPtr< DataModelIter > | create_iter ()
| Creates a new iterator object Gda::DataModelIter object which can be used to iterate through rows in model. More...
bool | set_value_at (int col, int row, const Value& value)
| Modifies a value in model, at ( col, row). More...
bool | set_values (int row, const std::vector< Value >& values)
| In a similar way to set_value_at(), this method modifies a data model's contents by setting several values at once. More...
DataModelAccessFlags | get_access_flags () const
| Get the attributes of model such as how to access the data it contains if it's modifiable, etc. More...
int | append_values (const std::vector< Value >& values)
| Appends a row to the given data model. More...
bool | append_row ()
| Appends a row to the data model (the new row will possibly have `0` values for all columns, or some other values depending on the data model implementation) More...
bool | remove_row (int row)
| Removes a row from the data model. More...
int | get_row_from_values (const ValueVector& values, const std::vector< int >& cols_index)
| Returns the first row where all the values in values at the columns identified at cols_index match. More...
void | send_hint (DataModelHint hint, const Value& hint_value)
| Sends a hint to the data model. More...
Glib::ustring | export_to_string (DataModelIOFormat format, const std::vector< int >& cols, const std::vector< int >& rows, const Glib::RefPtr< Set >& options)
| Exports data contained in model to the a string; the format is specified using the format argument. More...
bool | export_to_file (DataModelIOFormat format, const std::string& file, const std::vector< int >& cols, const std::vector< int >& rows, const Glib::RefPtr< Set >& options)
| Exports data contained in model to the file; the format is specified using the format argument. More...
bool | import_from_model (const Glib::RefPtr< DataModel >& from, bool overwrite, GHashTable* cols_trans)
| Copy the contents of the from data model to the to data model. More...
bool | import_from_string (const Glib::ustring&string, GHashTable* cols_trans, const Glib::RefPtr< const Set >& options)
| Loads the data from string into model. More...
bool | import_from_file (const std::string& file, GHashTable* cols_trans, const Glib::RefPtr< const Set >& options)
| Imports data contained in the file file into model; the format is detected. More...
void | dump (FILE* to_stream) const
| Dumps a textual representation of the model to the to_stream stream. More...
Glib::ustring | dump_as_string () const
| Dumps a textual representation of the model into a new string. More...
void | set_column_name (int col, const Glib::ustring& name)
| Sets the name of the given col in model, and if its title is not set, also sets the title to name. More...
Glib::ustring | get_column_name (int col) const
bool | iter_move_next_default (const Glib::RefPtr< DataModelIter >& iter)
bool | iter_move_prev_default (const Glib::RefPtr< DataModelIter >& iter)
bool | iter_move_to_row_default (const Glib::RefPtr< DataModelIter >& iter, int row)
Glib::SignalProxy1< void, int > | signal_row_inserted ()
Glib::SignalProxy1< void, int > | signal_row_updated ()
Glib::SignalProxy1< void, int > | signal_row_removed ()
Glib::SignalProxy0< void > | signal_reset ()
Glib::SignalProxy0< void > | signal_changed ()

## Static Public Member Functions
static GType | get_type ()
| Get the GType for this class, for use with the underlying GObject type system. More...
Static Public Member Functions inherited from Gnome::Gda::DataModel
static void | add_interface (GType gtype_implementer)
static GType | get_type ()
| Get the GType for this class, for use with the underlying GObject type system. More...

## Related Functions
(Note that these are not member functions.)
Glib::RefPtr < Gnome::Gda::DataSelect > | wrap (GdaDataSelect* object, bool take_copy=false)
| A Glib::wrap() method for this object. More...
Related Functions inherited from Gnome::Gda::DataModel
Glib::RefPtr < Gnome::Gda::DataModel > | wrap (GdaDataModel* object, bool take_copy=false)
| A Glib::wrap() method for this object. More...

## Additional Inherited Members
Public Types inherited from Gnome::Gda::DataModel
typedef std::vector< Value > | ValueVector
Protected Member Functions inherited from Gnome::Gda::DataModel
| DataModel ()
| You should derive from this class to use it. More...
virtual void | on_row_inserted (int row)
| This is a default handler for the signal signal_row_inserted(). More...
virtual void | on_row_updated (int row)
| This is a default handler for the signal signal_row_updated(). More...
virtual void | on_row_removed (int row)
| This is a default handler for the signal signal_row_removed(). More...
virtual void | on_reset ()
| This is a default handler for the signal signal_reset(). More...
virtual void | on_changed ()
| This is a default handler for the signal signal_changed(). More...

## Detailed Description

Data models returned by the execution of a SELECT statement.

This data model implements the Gda::DataModel interface and is the required base object when database providers implement a data model returned when a SELECT statement has been executed. As the GdaDataModel interface is implemented, consult the API to access and modify the data held in a GdaDataSelect object.

The default behaviour however is to disallow modifications, and this section documents how to characterize a Gda::DataSelect to allow modifications. Once this is done, any modification done to the data model whill be propagated to the modified table in the database using INSERT, UPDATE or DELETE statements.

After any modification, it is still possible to read values from the data model (even values for rows which have been modified or inserted). The data model might then execute some SELECT statement to fetch some actualized values. Note: there is a corner case where a modification made to a row would make the row not selected at first in the data model (for example is the original SELECT statement included a clause "WHERE id < 100" and the modification sets the "id" value to 110), then the row will still be in the data model even though it would not be if the SELECT statement which execution created the data model in the first place was re-run.

## Constructor & Destructor Documentation

virtual Gnome::Gda::DataSelect::~DataSelect | ( |  | ) |
| virtual

## Member Function Documentation

void Gnome::Gda::DataSelect::compute_columns_attributes | ( |  | ) |

Computes correct attributes for each of model's columns, which includes the "NOT <tt>0</tt>" attribute, the default value, the precision and scale for numeric values.

Returns
  `true` if no error occurred.

void Gnome::Gda::DataSelect::compute_modification_statements | ( |  | ) |

Makes model try to compute INSERT, UPDATE and DELETE statements to be used when modifying model's contents.

Note
  any modification statement set using set_modification_statement() will first be unset

Returns
  `true` if no error occurred. If `false` is returned, then some modification statement may still have been computed.

void Gnome::Gda::DataSelect::compute_row_selection_condition | ( |  | ) |

Offers the same features as set_row_selection_condition() but the expression is computed from the meta data associated to the connection being used when model was created.

NOTE1: make sure the meta data associated to the connection is up to date before using this method, see Gda::Connection::update_meta_store().

NOTE2: if the SELECT statement from which model has been created uses more than one table, or if the table used does not have any primary key, then this method will fail

Returns
  `true` if no error occurred.

Glib::RefPtr<Connection> Gnome::Gda::DataSelect::get_connection | ( |  | ) |

Get a pointer to the Gda::Connection object which was used when model was created (and which may be used internally by model).

Returns
  A pointer to the Gda::Connection, or `0`.

static GType Gnome::Gda::DataSelect::get_type | ( |  | ) |
| static

Get the GType for this class, for use with the underlying GObject type system.

GdaDataSelect* Gnome::Gda::DataSelect::gobj | ( |  | ) |
| inline

Provides access to the underlying C GObject.

const GdaDataSelect* Gnome::Gda::DataSelect::gobj | ( |  | ) | const
| inline

Provides access to the underlying C GObject.

GdaDataSelect* Gnome::Gda::DataSelect::gobj_copy | ( |  | ) |

Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.

Glib::PropertyProxy< bool > Gnome::Gda::DataSelect::property_auto_reset | ( |  | ) |

Automatically re-run the SELECT statement if any parameter has changed since it was first executed.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns
  A PropertyProxy that allows you to get or set the value of the property, or receive notification when the value of the property changes.

Glib::PropertyProxy_ReadOnly< bool > Gnome::Gda::DataSelect::property_auto_reset | ( |  | ) | const

Automatically re-run the SELECT statement if any parameter has changed since it was first executed.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns
  A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.

Glib::PropertyProxy_ReadOnly< Glib::RefPtr<Connection> > Gnome::Gda::DataSelect::property_connection | ( |  | ) | const

Connection from which this data model is created.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns
  A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.

Glib::PropertyProxy< Glib::RefPtr<Statement> > Gnome::Gda::DataSelect::property_delete_stmt | ( |  | ) |

DELETE Statement to be executed to remove data.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns
  A PropertyProxy that allows you to get or set the value of the property, or receive notification when the value of the property changes.

Glib::PropertyProxy_ReadOnly< Glib::RefPtr<Statement> > Gnome::Gda::DataSelect::property_delete_stmt | ( |  | ) | const

DELETE Statement to be executed to remove data.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns
  A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.

Glib::PropertyProxy_ReadOnly< Glib::RefPtr<Set> > Gnome::Gda::DataSelect::property_exec_params | ( |  | ) | const

GdaSet used when the SELECT statement was executed.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns
  A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.

Glib::PropertyProxy< Glib::RefPtr<Statement> > Gnome::Gda::DataSelect::property_insert_stmt | ( |  | ) |

INSERT Statement to be executed to add data.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns
  A PropertyProxy that allows you to get or set the value of the property, or receive notification when the value of the property changes.

Glib::PropertyProxy_ReadOnly< Glib::RefPtr<Statement> > Gnome::Gda::DataSelect::property_insert_stmt | ( |  | ) | const

INSERT Statement to be executed to add data.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns
  A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.

Glib::PropertyProxy_ReadOnly< guint > Gnome::Gda::DataSelect::property_model_usage | ( |  | ) | const

Determines how the data model may be used.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns
  A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.

Glib::PropertyProxy< Glib::RefPtr<Statement> > Gnome::Gda::DataSelect::property_prepared_stmt | ( |  | ) |

Associated prepared statement (for internal usage).

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns
  A PropertyProxy that allows you to get or set the value of the property, or receive notification when the value of the property changes.

Glib::PropertyProxy_ReadOnly< Glib::RefPtr<Statement> > Gnome::Gda::DataSelect::property_prepared_stmt | ( |  | ) | const

Associated prepared statement (for internal usage).

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns
  A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.

Glib::PropertyProxy< bool > Gnome::Gda::DataSelect::property_store_all_rows | ( |  | ) |

Tells if model has analyzed all the rows.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns
  A PropertyProxy that allows you to get or set the value of the property, or receive notification when the value of the property changes.

Glib::PropertyProxy_ReadOnly< bool > Gnome::Gda::DataSelect::property_store_all_rows | ( |  | ) | const

Tells if model has analyzed all the rows.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns
  A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.

Glib::PropertyProxy< Glib::RefPtr<Statement> > Gnome::Gda::DataSelect::property_update_stmt | ( |  | ) |

UPDATE Statement to be executed to update data.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns
  A PropertyProxy that allows you to get or set the value of the property, or receive notification when the value of the property changes.

Glib::PropertyProxy_ReadOnly< Glib::RefPtr<Statement> > Gnome::Gda::DataSelect::property_update_stmt | ( |  | ) | const

UPDATE Statement to be executed to update data.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns
  A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.

void Gnome::Gda::DataSelect::rerun | ( |  | ) |

Requests that model be re-run to have an updated result.

If an error occurs, then model will not be changed.

Since libgdamm 4.2:
  Returns
    `true` if no error occurred.

void Gnome::Gda::DataSelect::set_modification_statement | ( | const Glib::RefPtr< Statement >& | mod_stmt | ) |

Informs model that it should allow modifications to the data in some columns and some rows using mod_stmt to propagate those modifications into the database.

If mod_stmt is:

- an UPDATE statement, then all the rows in model will be modifyable
- a DELETE statement, then it will be possible to delete rows in model
- in INSERT statement, then it will be possible to add some rows to model
- any other statement, then this method will return an error

This method can be called several times to specify different types of modification.

If mod_stmt is an UPDATE or DELETE statement then it should have a WHERE part which identifies a unique row in model (please note that this property can't be checked but may result in model behaving in an unpredictable way).

NOTE1: However, if the set_row_selection_condition() or set_row_selection_condition_sql() have been successfully be called before, the WHERE part of mod_stmt WILL be modified to use the row selection condition specified through one of these methods (please not that it is then possible to avoid specifying a WHERE part in mod_stmt then).

NOTE2: if set_row_selection_condition() or set_row_selection_condition_sql() have not yet been successfully be called before, then the WHERE part of mod_stmt will be used as if one of these functions had been called.

Parameters

  mod_stmt | A Gda::Statement (INSERT, UPDATE or DELETE).

Returns
  `true` if no error occurred.

void Gnome::Gda::DataSelect::set_modification_statement_sql | ( | const Glib::ustring & | sql | ) |

Offers the same feature as set_modification_statement() but using an SQL statement.

Parameters

  sql | An SQL text.

Returns
  `true` if no error occurred.

bool Gnome::Gda::DataSelect::set_row_selection_condition_sql | ( | const Glib::ustring & | sql_where | ) |

Specifies the SQL condition corresponding to the WHERE part of a SELECT statement which would return only 1 row (the expression of the primary key).

For example for a table created as <![CDATA["CREATE TABLE mytable (part1 int NOT <tt>0</tt>, part2 string NOT <tt>0</tt>, name string, PRIMARY KEY (part1, part2))"]]>, and if pmodel corresponds to the execution of the <![CDATA["SELECT name, part1, part2 FROM mytable"]]>, then the sensible value for sql_where would be <![CDATA["part1 = ##-1::int AND part2 = ##-2::string"]]> because the values of the 'part1' field are located in pmodel's column number 1 and the values of the 'part2' field are located in pmodel's column number 2 and the primary key is composed of (part1, part2).

For more information about the syntax of the parameters (named <![CDATA["##-1::int"]]> for example), see the GdaSqlParser documentation, and set_modification_statement().

Parameters

  sql_where | An SQL condition (without the WHERE keyword).

Returns
  `true` if no error occurred.

## Friends And Related Function Documentation

Glib::RefPtr< Gnome::Gda::DataSelect > wrap | ( | GdaDataSelect * | object,
|  | bool | take_copy = `false`
| ) |  |
| related

A Glib::wrap() method for this object.

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:

- libgdamm/dataselect.h