Public Member Functions | Static Public Member Functions | Protected Member Functions | Related Functions

Gnome::Gda::DataModelIter Class Reference
[Data Models]

Data model iterator. More...

Inheritance diagram for Gnome::Gda::DataModelIter:
Inheritance graph
[legend]
Collaboration diagram for Gnome::Gda::DataModelIter:
Collaboration graph
[legend]

List of all members.

Public Member Functions

virtual ~DataModelIter ()
GdaDataModelIter* gobj ()
 Provides access to the underlying C GObject.
const GdaDataModelIter* gobj () const
 Provides access to the underlying C GObject.
GdaDataModelIter* gobj_copy ()
 Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.
bool is_valid () const
 Tells if iter is a valid iterator (if it actually corresponds to a valid row in the model)
bool move_next ()
 Moves iter one row further than where it already is (synchronizes the values of the parameters in iter with the values at the new row).
bool move_prev ()
 Moves iter one row before where it already is (synchronizes the values of the parameters in iter with the values at the new row).
bool move_to_row (int row)
 Synchronizes the values of the parameters in iter with the values at the row row.
int get_row () const
 Get the row which iter represents in the data model.
void invalidate_contents ()
 Declare all the parameters in iter invalid, without modifying the Gda::DataModel iter is for or changing the row it represents.
Glib::RefPtr< Holderget_holder_for_field (int col)
 Fetch a pointer to the Gda::Holder object which is synchronized with data at column col.
Glib::RefPtr< const Holderget_holder_for_field (int col) const
 Fetch a pointer to the Gda::Holder object which is synchronized with data at column col.
Value get_value_at (int col) const
 Get the value stored at the column col in iter.
Value get_value_for_field (const Glib::ustring& field_name) const
 Get the value stored at the column field_name in iter.
bool set_value_at (int col, const Value&value)
 Sets a value in iter, at the column specified by col.
Glib::PropertyProxy< int > property_current_row ()
 Current represented row in the data model.
Glib::PropertyProxy_ReadOnly< int > property_current_row () const
 Current represented row in the data model.
Glib::PropertyProxy_ReadOnly
< Glib::RefPtr< DataModel > > 
property_data_model () const
 Data model for which the iter is for.
Glib::PropertyProxy
< Glib::RefPtr< DataModel > > 
property_forced_model ()
 Overrides the data model the iter is attached to (reserved for internal usage).
Glib::PropertyProxy_ReadOnly
< Glib::RefPtr< DataModel > > 
property_forced_model () const
 Overrides the data model the iter is attached to (reserved for internal usage).
Glib::PropertyProxy< bool > property_update_model ()
 You rarely need to use properties because there are get_ and set_ methods for almost all of them.
Glib::PropertyProxy_ReadOnly
< bool > 
property_update_model () const
 You rarely need to use properties because there are get_ and set_ methods for almost all of them.
Glib::SignalProxy0< void > signal_end_of_data ()
Glib::SignalProxy1< void, int > signal_row_changed ()

Static Public Member Functions

static Glib::RefPtr
< DataModelIter
create (const Glib::RefPtr< DataModel >& data_model)

Protected Member Functions

 DataModelIter (const Glib::RefPtr< DataModel >& data_model)
virtual void on_end_of_data ()
virtual void on_row_changed (int row)

Related Functions

(Note that these are not member functions.)


Glib::RefPtr
< Gnome::Gda::DataModelIter
wrap (GdaDataModelIter* object, bool take_copy=false)
 A Glib::wrap() method for this object.

Detailed Description

Data model iterator.

A Gda::DataModelIter object is used to iterate through the rows of a Gda::DataModel. If the data model is accessible in a random access way then any number of Gda::DataModelIter objects can be created on the same data model, and if the data model only supports a cursor based access then only one Gda::DataModelIter can be created. In any case creating a Gda::DataModelIter should be done using the create_iter() method.

When a Gda::DataModelIter is valid (that is when it points to an existing row in the data model it iterates through), the individual values (corresponding to each column of the data model, at the pointer row) can be accessed using the get_value_at() or get_value_for_field() methods (or in the same way Gda::Set's values are accessed as Gda::DataModelIter inherits the Gda::Set).

Right after being created, a Gda::DataModelIter is invalid (does not point to any row of its data model). To read the first row of the data model, use the move_next() method. Calling this method several times will move the iterator forward, up to when the data model has no more rows and the Gda::DataModelIter will be declared invalid (and move_next() has returned FALSE). Note that at this point, the number of rows in the data model will be known.

If the data model supports it, a Gda::DataModelIter can be moved backwards using the move_prev() method. However if the iterator is invalid, moving backwards will not be possible (on the contrary to move_next() which moves to the first row).

The move_to_row() method, if the iterator can be moved both forward and backwards, can move the iterator to a specific row (sometimes faster than moving it forward or backwards a number of times).


Constructor & Destructor Documentation

virtual Gnome::Gda::DataModelIter::~DataModelIter (  ) [virtual]
Gnome::Gda::DataModelIter::DataModelIter ( const Glib::RefPtr< DataModel >&  data_model ) [explicit, protected]

Member Function Documentation

static Glib::RefPtr<DataModelIter> Gnome::Gda::DataModelIter::create ( const Glib::RefPtr< DataModel >&  data_model ) [static]
Glib::RefPtr<Holder> Gnome::Gda::DataModelIter::get_holder_for_field ( int  col )

Fetch a pointer to the Gda::Holder object which is synchronized with data at column col.

Parameters:
colThe requested column.
Returns:
The Gda::Holder, or 0 if an error occurred.
Glib::RefPtr<const Holder> Gnome::Gda::DataModelIter::get_holder_for_field ( int  col ) const

Fetch a pointer to the Gda::Holder object which is synchronized with data at column col.

Parameters:
colThe requested column.
Returns:
The Gda::Holder, or 0 if an error occurred.
int Gnome::Gda::DataModelIter::get_row (  ) const

Get the row which iter represents in the data model.

Returns:
The row number, or -1 if iter is invalid.
Value Gnome::Gda::DataModelIter::get_value_at ( int  col ) const

Get the value stored at the column col in iter.

The returned value must not be modified.

Parameters:
colThe requested column.
Returns:
The Value, or 0 if the value could not be fetched.
Value Gnome::Gda::DataModelIter::get_value_for_field ( const Glib::ustring field_name ) const

Get the value stored at the column field_name in iter.

Parameters:
field_nameThe requested column name.
Returns:
The Value, or 0.
GdaDataModelIter* Gnome::Gda::DataModelIter::gobj (  ) [inline]

Provides access to the underlying C GObject.

Reimplemented from Gnome::Gda::Set.

const GdaDataModelIter* Gnome::Gda::DataModelIter::gobj (  ) const [inline]

Provides access to the underlying C GObject.

Reimplemented from Gnome::Gda::Set.

GdaDataModelIter* Gnome::Gda::DataModelIter::gobj_copy (  )

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

Reimplemented from Gnome::Gda::Set.

void Gnome::Gda::DataModelIter::invalidate_contents (  )

Declare all the parameters in iter invalid, without modifying the Gda::DataModel iter is for or changing the row it represents.

This method is for internal usage. Note that for is_valid() to return false, it is also necessary to set the "current-row" property to -1.

bool Gnome::Gda::DataModelIter::is_valid (  ) const

Tells if iter is a valid iterator (if it actually corresponds to a valid row in the model)

Returns:
true if iter is valid.

Reimplemented from Gnome::Gda::Set.

bool Gnome::Gda::DataModelIter::move_next (  )

Moves iter one row further than where it already is (synchronizes the values of the parameters in iter with the values at the new row).

If the iterator was on the data model's last row, then it can't be moved forward anymore, and the returned value is false; nore also that the "current-row" property is set to -1 (which means that is_valid() would return false)

If any other error occurred then the returned value is false, but the "current-row" property is set to the new current row (one row more than it was before the call). In this case each Gda::Holder composing iter for which an error occurred will be invalid (see Gda::Holder::is_valid()).

Returns:
true if the iterator is now at the next row.
bool Gnome::Gda::DataModelIter::move_prev (  )

Moves iter one row before where it already is (synchronizes the values of the parameters in iter with the values at the new row).

If the iterator was on the data model's first row, then it can't be moved backwards anymore, and the returned value is false; note also that the "current-row" property is set to -1 (which means that is_valid() would return false).

If any other error occurred then the returned value is false, but the "current-row" property is set to the new current row (one row less than it was before the call). In this case each Gda::Holder composing iter for which an error occurred will be invalid (see Gda::Holder::is_valid()).

Returns:
true if the iterator is now at the previous row.
bool Gnome::Gda::DataModelIter::move_to_row ( int  row )

Synchronizes the values of the parameters in iter with the values at the row row.

If row is not a valid row, then the returned value is false, and the "current-row" property is set to -1 (which means that is_valid() would return false)

If any other error occurred then the returned value is false, but the "current-row" property is set to the row row. In this case each Gda::Holder composing iter for which an error occurred will be invalid (see Gda::Holder::is_valid()).

Parameters:
rowThe row to set iter to.
Returns:
true if no error occurred.
virtual void Gnome::Gda::DataModelIter::on_end_of_data (  ) [protected, virtual]
virtual void Gnome::Gda::DataModelIter::on_row_changed ( int  row ) [protected, virtual]
Glib::PropertyProxy_ReadOnly<int> Gnome::Gda::DataModelIter::property_current_row (  ) const

Current represented row in the data model.

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 property of the value, or receive notification when the value of the property changes.
Glib::PropertyProxy<int> Gnome::Gda::DataModelIter::property_current_row (  )

Current represented row in the data model.

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 property of the value, or receive notification when the value of the property changes.
Glib::PropertyProxy_ReadOnly< Glib::RefPtr<DataModel> > Gnome::Gda::DataModelIter::property_data_model (  ) const

Data model for which the iter is for.

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 property of the value, or receive notification when the value of the property changes.
Glib::PropertyProxy_ReadOnly< Glib::RefPtr<DataModel> > Gnome::Gda::DataModelIter::property_forced_model (  ) const

Overrides the data model the iter is attached to (reserved 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 property of the value, or receive notification when the value of the property changes.
Glib::PropertyProxy< Glib::RefPtr<DataModel> > Gnome::Gda::DataModelIter::property_forced_model (  )

Overrides the data model the iter is attached to (reserved 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 property of the value, or receive notification when the value of the property changes.
Glib::PropertyProxy_ReadOnly<bool> Gnome::Gda::DataModelIter::property_update_model (  ) const

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 property of the value, or receive notification when the value of the property changes.
Glib::PropertyProxy<bool> Gnome::Gda::DataModelIter::property_update_model (  )

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 property of the value, or receive notification when the value of the property changes.
bool Gnome::Gda::DataModelIter::set_value_at ( int  col,
const Value value 
)

Sets a value in iter, at the column specified by col.

Parameters:
colThe column number.
valueA Value (not 0).
Returns:
true if no error occurred.
Glib::SignalProxy0< void > Gnome::Gda::DataModelIter::signal_end_of_data (  )
Prototype:
void on_my_end_of_data()
Glib::SignalProxy1< void,int > Gnome::Gda::DataModelIter::signal_row_changed (  )
Prototype:
void on_my_row_changed(int row)

Friends And Related Function Documentation

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

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

Parameters:
objectThe C instance.
take_copyFalse 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: