Clutter Reference Manual: ClutterModelIter

## ClutterModelIter ClutterModelIter — Iterates through a model |

## Synopsis

    struct              ClutterModelIter;
    struct              ClutterModelIterClass;
    ClutterModelIter *  clutter_model_iter_copy             (ClutterModelIter *iter);

    void                clutter_model_iter_get              (ClutterModelIter *iter,
                                                             ...);
    void                clutter_model_iter_get_valist       (ClutterModelIter *iter,
                                                             va_list args);
    void                clutter_model_iter_get_value        (ClutterModelIter *iter,
                                                             guint column,
                                                             GValue *value);
    void                clutter_model_iter_set              (ClutterModelIter *iter,
                                                             ...);
    void                clutter_model_iter_set_valist       (ClutterModelIter *iter,
                                                             va_list args);
    void                clutter_model_iter_set_value        (ClutterModelIter *iter,
                                                             guint column,
                                                             const GValue *value);

    gboolean            clutter_model_iter_is_first         (ClutterModelIter *iter);
    gboolean            clutter_model_iter_is_last          (ClutterModelIter *iter);
    ClutterModelIter *  clutter_model_iter_next             (ClutterModelIter *iter);
    ClutterModelIter *  clutter_model_iter_prev             (ClutterModelIter *iter);

    ClutterModel *      clutter_model_iter_get_model        (ClutterModelIter *iter);
    guint               clutter_model_iter_get_row          (ClutterModelIter *iter);

## Object Hierarchy

      GObject
       +----ClutterModelIter

## Properties

      "model"                    ClutterModel*         : Read / Write
      "row"                      guint                 : Read / Write

## Description

ClutterModelIter is an object used for iterating through all the rows of a ClutterModel. It allows setting and getting values on the row which is currently pointing at.

A ClutterModelIter represents a position between two elements of the sequence. For example, the iterator returned by `clutter_model_get_first_iter()` represents the gap immediately before the first row of the ClutterModel, and the iterator returned by `clutter_model_get_last_iter()` represents the gap immediately after the last row.

A ClutterModelIter can only be created by a ClutterModel implementation and it is valid as long as the model does not change.

ClutterModelIter is available since Clutter 0.6

## Details

### struct ClutterModelIter

    struct ClutterModelIter;

Base class for list models iters. The ClutterModelIter structure contains only private data and should be manipulated using the provided API.

Since 0.6

### struct ClutterModelIterClass

    struct ClutterModelIterClass {
      /* vtable not signals */
      void              (* get_value) (ClutterModelIter *iter,
                                       guint             column,
                                       GValue           *value);
      void              (* set_value) (ClutterModelIter *iter,
                                       guint             column,
                                       const GValue     *value);

      gboolean          (* is_first)  (ClutterModelIter *iter);
      gboolean          (* is_last)   (ClutterModelIter *iter);

      ClutterModelIter *(* next)      (ClutterModelIter *iter);
      ClutterModelIter *(* prev)      (ClutterModelIter *iter);

      ClutterModel *    (* get_model) (ClutterModelIter *iter);
      guint             (* get_row)   (ClutterModelIter *iter);

      ClutterModelIter *(* copy)      (ClutterModelIter *iter);
    };

Class for ClutterModelIter instances.

`get_value` () | Virtual function for retrieving the value at the given column of the row pointed by the iterator
`set_value` () | Virtual function for setting the value at the given column of the row pointer by the iterator
`is_first` () | Virtual function for knowing whether the iterator points at the first row in the model
`is_last` () | Virtual function for knowing whether the iterator points at the last row in the model
`next` () | Virtual function for moving the iterator to the following row in the model
`prev` () | Virtual function for moving the iterator toe the previous row in the model
`get_model` () | Virtual function for getting the model to which the iterator belongs to
`get_row` () | Virtual function for getting the row to which the iterator points
`copy` () | Virtual function for copying a ClutterModelIter.

Since 0.6

### clutter_model_iter_copy ()

    ClutterModelIter *  clutter_model_iter_copy             (ClutterModelIter *iter);

Copies the passed iterator.

`iter` : | a ClutterModelIter
Returns : | a copy of the iterator, or `NULL`. [transfer full]

Since 0.8

### clutter_model_iter_get ()

    void                clutter_model_iter_get              (ClutterModelIter *iter,
                                                             ...);

Gets the value of one or more cells in the row referenced by `iter`. The variable argument list should contain integer column numbers, each column column number followed by a place to store the value being retrieved. The list is terminated by a -1.

For example, to get a value from column 0 with type `G_TYPE_STRING` use:

    1
    clutter_model_iter_get (iter, 0, &place_string_here, -1);

where place_string_here is a gchar* to be filled with the string. If appropriate, the returned values have to be freed or unreferenced.

`iter` : | a ClutterModelIter
`...` : | a list of column/return location pairs, terminated by -1

Since 0.6

### clutter_model_iter_get_valist ()

    void                clutter_model_iter_get_valist       (ClutterModelIter *iter,
                                                             va_list args);

See `clutter_model_iter_get()`. This version takes a va_list for language bindings.

`iter` : | a ClutterModelIter
`args` : | a list of column/return location pairs, terminated by -1

Since 0.6

### clutter_model_iter_get_value ()

    void                clutter_model_iter_get_value        (ClutterModelIter *iter,
                                                             guint column,
                                                             GValue *value);

Sets an initializes `value` to that at `column`. When done with `value`, `g_value_unset()` needs to be called to free any allocated memory.

`iter` : | a ClutterModelIter
`column` : | column number to retrieve the value from
`value` : | an empty GValue to set. [out]

Since 0.6

### clutter_model_iter_set ()

    void                clutter_model_iter_set              (ClutterModelIter *iter,
                                                             ...);

Sets the value of one or more cells in the row referenced by `iter`. The variable argument list should contain integer column numbers, each column column number followed by the value to be set. The list is terminated by a -1.

For example, to set column 0 with type `G_TYPE_STRING`, use:

    1
    clutter_model_iter_set (iter, 0, "foo", -1);

`iter` : | a ClutterModelIter
`...` : | a list of column/return location pairs, terminated by -1

Since 0.6

### clutter_model_iter_set_valist ()

    void                clutter_model_iter_set_valist       (ClutterModelIter *iter,
                                                             va_list args);

See `clutter_model_iter_set()`; this version takes a va_list for language bindings.

`iter` : | a ClutterModelIter
`args` : | va_list of column/value pairs, terminiated by -1

Since 0.6

### clutter_model_iter_set_value ()

    void                clutter_model_iter_set_value        (ClutterModelIter *iter,
                                                             guint column,
                                                             const GValue *value);

Sets the data in the cell specified by `iter` and `column`. The type of `value` must be convertable to the type of the column.

`iter` : | a ClutterModelIter
`column` : | column number to retrieve the value from
`value` : | new value for the cell

Since 0.6

### clutter_model_iter_is_first ()

    gboolean            clutter_model_iter_is_first         (ClutterModelIter *iter);

Gets whether the current iterator is at the beginning of the model to which it belongs.

`iter` : | a ClutterModelIter
Returns : | TRUE if `iter` is the first iter in the filtered model

Since 0.6

### clutter_model_iter_is_last ()

    gboolean            clutter_model_iter_is_last          (ClutterModelIter *iter);

Gets whether the iterator is at the end of the model to which it belongs.

`iter` : | a ClutterModelIter
Returns : | TRUE if `iter` is the last iter in the filtered model.

Since 0.6

### clutter_model_iter_next ()

    ClutterModelIter *  clutter_model_iter_next             (ClutterModelIter *iter);

Updates the `iter` to point at the next position in the model. The model implementation should take into account the presence of a filter function.

`iter` : | a ClutterModelIter
Returns : | The passed iterator, updated to point at the next row in the model. [transfer none]

Since 0.6

### clutter_model_iter_prev ()

    ClutterModelIter *  clutter_model_iter_prev             (ClutterModelIter *iter);

Sets the `iter` to point at the previous position in the model. The model implementation should take into account the presence of a filter function.

`iter` : | a ClutterModelIter
Returns : | The passed iterator, updated to point at the previous row in the model. [transfer none]

Since 0.6

### clutter_model_iter_get_model ()

    ClutterModel *      clutter_model_iter_get_model        (ClutterModelIter *iter);

Retrieves a pointer to the ClutterModel that this iter is part of.

`iter` : | a ClutterModelIter
Returns : | a pointer to a ClutterModel. [transfer none]

Since 0.6

### clutter_model_iter_get_row ()

    guint               clutter_model_iter_get_row          (ClutterModelIter *iter);

Retrieves the position of the row that the `iter` points to.

`iter` : | a ClutterModelIter
Returns : | the position of the `iter` in the model

Since 0.6

## Property Details

### The `"model"` property

      "model"                    ClutterModel*         : Read / Write

A reference to the ClutterModel that this iter belongs to.

Since 0.6

### The `"row"` property

      "row"                      guint                 : Read / Write

The row number to which this iter points to.

Default value: 0

Since 0.6