GcrCollectionModel

## GcrCollectionModel GcrCollectionModel — A GtkTreeModel that represents a collection |

## Synopsis

    struct              GcrCollectionModel;
    struct              GcrCollectionModelClass;
    enum                GcrCollectionModelMode;
    GcrCollectionModel * gcr_collection_model_new           (GcrCollection *collection,
                                                             GcrCollectionModelMode mode,
                                                             ...);
    GcrCollectionModel * gcr_collection_model_new_full      (GcrCollection *collection,
                                                             GcrCollectionModelMode mode,
                                                             const GcrColumn *columns);
    guint               gcr_collection_model_set_columns    (GcrCollectionModel *self,
                                                             const GcrColumn *columns);
    GcrCollection *     gcr_collection_model_get_collection (GcrCollectionModel *self);
    void                gcr_collection_model_set_collection (GcrCollectionModel *self,
                                                             GcrCollection *collection);
    gboolean            gcr_collection_model_iter_for_object
                                                            (GcrCollectionModel *self,
                                                             GObject *object,
                                                             GtkTreeIter *iter);
    GObject *           gcr_collection_model_object_for_iter
                                                            (GcrCollectionModel *self,
                                                             const GtkTreeIter *iter);
    gboolean            gcr_collection_model_is_selected    (GcrCollectionModel *self,
                                                             GtkTreeIter *iter);
    void                gcr_collection_model_change_selected
                                                            (GcrCollectionModel *self,
                                                             GtkTreeIter *iter,
                                                             gboolean selected);
    void                gcr_collection_model_toggle_selected
                                                            (GcrCollectionModel *self,
                                                             GtkTreeIter *iter);
    GList *             gcr_collection_model_get_selected_objects
                                                            (GcrCollectionModel *self);
    void                gcr_collection_model_set_selected_objects
                                                            (GcrCollectionModel *self,
                                                             GList *selected);
    gint                gcr_collection_model_column_for_selected
                                                            (GcrCollectionModel *self);

## Object Hierarchy

      GObject
       +----GcrCollectionModel

## Implemented Interfaces

GcrCollectionModel implements GtkTreeModel and GtkTreeSortable.

## Properties

      "collection"               GcrCollection*        : Read / Write
      "columns"                  gpointer              : Read / Write / Construct Only
      "mode"                     GcrCollectionModelMode  : Read / Write / Construct Only

## Description

This is an implementation of GtkTreeModel which represents the objects in the a GcrCollection. As objects are added or removed from the collection, rows are added and removed from this model.

The row values come from the properties of the objects in the collection. Use `gcr_collection_model_new()` to create a new collection model. To have more control over the values use a set of GcrColumn structures to define the columns. This can be done with `gcr_collection_model_new_full()` or `gcr_collection_model_set_columns()`.

Each row can have a selected state, which is represented by a boolean column. The selected state can be toggled with `gcr_collection_model_toggle_selected()` or set with `gcr_collection_model_set_selected_objects()` and retrieved with `gcr_collection_model_get_selected_objects()`.

To determine which object a row represents and vice versa, use the `gcr_collection_model_iter_for_object()` or `gcr_collection_model_object_for_iter()` functions.

## Details

### struct GcrCollectionModel

    struct GcrCollectionModel;

A GtkTreeModel which contains a row for each object in a GcrCollection.

### struct GcrCollectionModelClass

    struct GcrCollectionModelClass {
    	GObjectClass parent_class;
    };

The class for GcrCollectionModel.

GObjectClass `parent_class`; | The parent class

### enum GcrCollectionModelMode

    typedef enum {
    	GCR_COLLECTION_MODEL_LIST = 0,
    	GCR_COLLECTION_MODEL_TREE
    } GcrCollectionModelMode;

If set GcrCollectionModel is created with a mode of `GCR_COLLECTION_MODEL_TREE`, then any included objects that are themselves a GcrCollection, will have all child objects include as child rows in a tree form.

`GCR_COLLECTION_MODEL_LIST` | only objects in the top collection, no child objects
`GCR_COLLECTION_MODEL_TREE` | show objects in the collection, and child objects in a tree form

### gcr_collection_model_new ()

    GcrCollectionModel * gcr_collection_model_new           (GcrCollection *collection,
                                                             GcrCollectionModelMode mode,
                                                             ...);

Create a new GcrCollectionModel. The variable argument list should contain pairs of property names, and GType values. The variable argument list should be terminated with `NULL`.

`collection` : | the collection to represent
`mode` : | whether list or tree mode
`...` : | the column names and types
Returns : | a newly allocated model, which should be released with `g_object_unref()`. [transfer full]

### gcr_collection_model_new_full ()

    GcrCollectionModel * gcr_collection_model_new_full      (GcrCollection *collection,
                                                             GcrCollectionModelMode mode,
                                                             const GcrColumn *columns);

Create a new GcrCollectionModel.

`collection` : | the collection to represent
`mode` : | whether list or tree mode
`columns` : | the columns the model should contain
Returns : | a newly allocated model, which should be released with `g_object_unref()`. [transfer full]

### gcr_collection_model_set_columns ()

    guint               gcr_collection_model_set_columns    (GcrCollectionModel *self,
                                                             const GcrColumn *columns);

Set the columns that the model should contain. `columns` is an array of GcrColumn structures, with the last one containing `NULL` for all values.

This function can only be called once, and only if the model was not created without a set of columns. This function cannot be called after the model has been added to a view.

The columns are accessed as static data. They should continue to remain in memory for longer than the GcrCollectionModel object.

`self` : | The model
`columns` : | The columns the model should contain
Returns : | The number of columns

### gcr_collection_model_get_collection ()

    GcrCollection *     gcr_collection_model_get_collection (GcrCollectionModel *self);

Get the collection which this model represents

`self` : | a collection model
Returns : | the collection, owned by the model. [transfer none]

### gcr_collection_model_set_collection ()

    void                gcr_collection_model_set_collection (GcrCollectionModel *self,
                                                             GcrCollection *collection);

### gcr_collection_model_iter_for_object ()

    gboolean            gcr_collection_model_iter_for_object
                                                            (GcrCollectionModel *self,
                                                             GObject *object,
                                                             GtkTreeIter *iter);

Set `iter` to the row for the given object. If the object is not in this model, then `FALSE` will be returned.

`self` : | The model
`object` : | The object
`iter` : | The row for the object
Returns : | `TRUE` if the object was present.

### gcr_collection_model_object_for_iter ()

    GObject *           gcr_collection_model_object_for_iter
                                                            (GcrCollectionModel *self,
                                                             const GtkTreeIter *iter);

Get the object that is represented by the given row in the model.

`self` : | The model
`iter` : | The row
Returns : | The object, owned by the model. [transfer none]

### gcr_collection_model_is_selected ()

    gboolean            gcr_collection_model_is_selected    (GcrCollectionModel *self,
                                                             GtkTreeIter *iter);

Check whether a given row has been toggled as selected.

`self` : | The model
`iter` : | The row
Returns : | Whether the row has been selected.

### gcr_collection_model_change_selected ()

    void                gcr_collection_model_change_selected
                                                            (GcrCollectionModel *self,
                                                             GtkTreeIter *iter,
                                                             gboolean selected);

Set whether a given row is toggled selected or not.

`self` : | The model
`iter` : | The row
`selected` : | Whether the row should be selected or not.

### gcr_collection_model_toggle_selected ()

    void                gcr_collection_model_toggle_selected
                                                            (GcrCollectionModel *self,
                                                             GtkTreeIter *iter);

Toggle the selected state of a given row.

`self` : | The model
`iter` : | The row

### gcr_collection_model_get_selected_objects ()

    GList *             gcr_collection_model_get_selected_objects
                                                            (GcrCollectionModel *self);

Get a list of checked/selected objects.

`self` : | the collection model
Returns : | a list of selected objects, which should be freed with `g_list_free()`. [transfer container][element-type GLib.Object]

### gcr_collection_model_set_selected_objects ()

    void                gcr_collection_model_set_selected_objects
                                                            (GcrCollectionModel *self,
                                                             GList *selected);

Set the checked/selected objects.

`self` : | the collection model
`selected` : | a list of objects to select. [element-type GLib.Object]

### gcr_collection_model_column_for_selected ()

    gint                gcr_collection_model_column_for_selected
                                                            (GcrCollectionModel *self);

Get the column identifier for the column that contains the values of the selected state.

`self` : | The model
Returns : | The column identifier.

## Property Details

### The `"collection"` property

      "collection"               GcrCollection*        : Read / Write

Collection to get objects from.

### The `"columns"` property

      "columns"                  gpointer              : Read / Write / Construct Only

Columns for the model.

### The `"mode"` property

      "mode"                     GcrCollectionModelMode  : Read / Write / Construct Only

Tree or list mode.

Default value: GCR_COLLECTION_MODEL_TREE