GdaDataModelIter

GdaDataModelIter — Data model iterator

Synopsis




                    GdaDataModelIter;
const GValue*       gda_data_model_iter_get_value_at    (GdaDataModelIter *iter,
                                                         gint col);
const GValue*       gda_data_model_iter_get_value_for_field
                                                        (GdaDataModelIter *iter,
                                                         const gchar *field_name);
gboolean            gda_data_model_iter_is_valid        (GdaDataModelIter *iter);
gboolean            gda_data_model_iter_set_at_row      (GdaDataModelIter *iter,
                                                         gint row);
gboolean            gda_data_model_iter_move_next       (GdaDataModelIter *iter);
gboolean            gda_data_model_iter_move_prev       (GdaDataModelIter *iter);
gint                gda_data_model_iter_get_row         (GdaDataModelIter *iter);
GdaHolder*          gda_data_model_iter_get_holder_for_field
                                                        (GdaDataModelIter *iter,
                                                         gint col);
void                gda_data_model_iter_invalidate_contents
                                                        (GdaDataModelIter *iter);

Object Hierarchy


  GObject
   +----GdaSet
         +----GdaDataModelIter

Properties


  "current-row"              gint                  : Read / Write
  "data-model"               GdaDataModel          : Read / Write / Construct Only
  "forced-model"             GdaDataModel          : Read / Write
  "update-model"             gboolean              : Read / Write

Signals


  "end-of-data"                                    : Run First
  "row-changed"                                    : Run First
  "row-to-change"                                  : Run Last

Description

A GdaDataModelIter object is used to iterate through the rows of a GdaDataModel. If the data model is accessible in a random access way then any number of GdaDataModelIter objects can be created on the same data model, and if the data model only supports a cursor based access then only one GdaDataModelIter can be created. In any case creating a GdaDataModelIter should be done using the gda_data_model_create_iter() method. Note that if the data model only supports a cursor based access, then calling this method several times will always return the same GdaDataModelIter, but with its reference count increased by 1 (so you should call g_object_unref() when finished with it).

When a GdaDataModelIter 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 gda_data_model_iter_get_value_at() or gda_data_model_iter_get_value_for_field() methods (or in the same way GdaSet's values are accessed as GdaDataModelIter inherits the GdaSet).

Right after being created, a GdaDataModelIter is invalid (does not point to any row of its data model). To read the first row of the data model, use the gda_data_model_iter_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 GdaDataModelIter will be declared invalid (and gda_data_model_iter_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 GdaDataModelIter can be moved backwards using the gda_data_model_iter_move_prev() method. However if the iterator is invalid, moving backwards will not be possible (on the contrary to gda_data_model_iter_move_next() which moves to the first row).

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

Details

GdaDataModelIter

typedef struct _GdaDataModelIter GdaDataModelIter;


gda_data_model_iter_get_value_at ()

const GValue*       gda_data_model_iter_get_value_at    (GdaDataModelIter *iter,
                                                         gint col);

Get the value stored at the column col in iter

iter : a GdaDataModelIter object
col : the requested column
Returns : the GValue, or NULL

gda_data_model_iter_get_value_for_field ()

const GValue*       gda_data_model_iter_get_value_for_field
                                                        (GdaDataModelIter *iter,
                                                         const gchar *field_name);

Get the value stored at the column field_name in iter

iter : a GdaDataModelIter object
field_name : the requested column name
Returns : the GValue, or NULL

gda_data_model_iter_is_valid ()

gboolean            gda_data_model_iter_is_valid        (GdaDataModelIter *iter);

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

iter : a GdaDataModelIter object
Returns : TRUE if iter is valid

gda_data_model_iter_set_at_row ()

gboolean            gda_data_model_iter_set_at_row      (GdaDataModelIter *iter,
                                                         gint row);

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

If row < 0 then iter is not bound to any row of the data model it iters through.

iter : a GdaDataModelIter object
row : the row to set iter to
Returns : TRUE if no error occurred

gda_data_model_iter_move_next ()

gboolean            gda_data_model_iter_move_next       (GdaDataModelIter *iter);

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

iter : a GdaDataModelIter object
Returns : TRUE if no error occurred

gda_data_model_iter_move_prev ()

gboolean            gda_data_model_iter_move_prev       (GdaDataModelIter *iter);

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

iter : a GdaDataModelIter object
Returns : TRUE if no error occurred

gda_data_model_iter_get_row ()

gint                gda_data_model_iter_get_row         (GdaDataModelIter *iter);

Get the row which iter represents in the data model

iter : a GdaDataModelIter object
Returns : the row number, or -1 if not available

gda_data_model_iter_get_holder_for_field ()

GdaHolder*          gda_data_model_iter_get_holder_for_field
                                                        (GdaDataModelIter *iter,
                                                         gint col);

Fetch a pointer to the GdaHolder object which is synchronized with data at column col

iter : a GdaDataModelIter object
col : the requested column
Returns : the GdaHolder, or NULL if an error occurred

gda_data_model_iter_invalidate_contents ()

void                gda_data_model_iter_invalidate_contents
                                                        (GdaDataModelIter *iter);

Declare all the parameters in iter invalid, without modifying the GdaDataModel iter is for or changing the row it represents. This method is for internal usage.

iter : a GdaDataModelIter object

Property Details

The "current-row" property

  "current-row"              gint                  : Read / Write

Allowed values: >= -1

Default value: -1


The "data-model" property

  "data-model"               GdaDataModel          : Read / Write / Construct Only


The "forced-model" property

  "forced-model"             GdaDataModel          : Read / Write


The "update-model" property

  "update-model"             gboolean              : Read / Write

Default value: TRUE

Signal Details

The "end-of-data" signal

void                user_function                      (GdaDataModelIter *gdadatamodeliter,
                                                        gpointer          user_data)             : Run First

gdadatamodeliter : the object which received the signal.
user_data : user data set when the signal handler was connected.

The "row-changed" signal

void                user_function                      (GdaDataModelIter *gdadatamodeliter,
                                                        gint              arg1,
                                                        gpointer          user_data)             : Run First

gdadatamodeliter : the object which received the signal.
arg1 :
user_data : user data set when the signal handler was connected.

The "row-to-change" signal

gboolean            user_function                      (GdaDataModelIter *gdadatamodeliter,
                                                        gint              arg1,
                                                        gpointer          user_data)             : Run Last

gdadatamodeliter : the object which received the signal.
arg1 :
user_data : user data set when the signal handler was connected.
Returns :