DeeFilterModel

## DeeFilterModel DeeFilterModel — A DeeModel that contains a filtered subset of another DeeModel |

## Synopsis

    #include <dee.h>

                        DeeFilter;
    struct              DeeFilterModel;
    struct              DeeFilterModelClass;
    DeeModelIter *      dee_filter_model_append_iter        (DeeFilterModel *self,
                                                             DeeModelIter *iter);
    gboolean            dee_filter_model_contains           (DeeFilterModel *self,
                                                             DeeModelIter *iter);
    DeeModelIter *      dee_filter_model_insert_iter        (DeeFilterModel *self,
                                                             DeeModelIter *iter,
                                                             guint pos);
    DeeModelIter *      dee_filter_model_insert_iter_before (DeeFilterModel *self,
                                                             DeeModelIter *iter,
                                                             DeeModelIter *pos);
    DeeModelIter *      dee_filter_model_insert_iter_with_original_order
                                                            (DeeFilterModel *self,
                                                             DeeModelIter *iter);
    DeeModel *          dee_filter_model_new                (DeeModel *orig_model,
                                                             DeeFilter *filter);
    DeeModelIter *      dee_filter_model_prepend_iter       (DeeFilterModel *self,
                                                             DeeModelIter *iter);

## Object Hierarchy

      GObject
       +----DeeSerializableModel
             +----DeeProxyModel
                   +----DeeFilterModel

## Implemented Interfaces

DeeFilterModel implements DeeModel and DeeSerializable.

## Properties

      "filter"                   gpointer              : Read / Write / Construct Only

## Description

A DeeFilterModel should be regarded as a view on a specific subset of of another DeeModel, filtered according to a given "filtering rule".

Filter models re-use the DeeModelIters of the back end model they filter. This means that any iter from the filter model can be used directly on the back end model. This is a powerful invariant, but implies the restriction that a row in the filter model contains the exact same data as the corresponding row in the back end model (ie. you can not apply a "transfomation map" to the filtered data).

The reuse of row iters also minimizes the amount of memory shuffling needed to set up a filter model. The filtering functions, DeeFilterMapFunc and DeeFilterMapNotify, has also been designed to minimize the amount of work done to create a filter model. So if the filter functions are written optimally the resulting filter models should be cheap to construct.

Another important feature of the filter model is also that the rows need not be in the same order as the original rows in the back end model.

There is a suite of filters shipped with Dee which you can browse in the Filters section.

## Details

### DeeFilter

    typedef struct {
      DeeFilterMapFunc   map_func;
      DeeFilterMapNotify map_notify;
      GDestroyNotify     destroy;
      gpointer           userdata;
    } DeeFilter;

Structure encapsulating the mapping logic used to construct a DeeFilterModel

### struct DeeFilterModel

    struct DeeFilterModel;

All fields in the DeeFilterModel structure are private and should never be accessed directly

### struct DeeFilterModelClass

    struct DeeFilterModelClass {
    };

### dee_filter_model_append_iter ()

    DeeModelIter *      dee_filter_model_append_iter        (DeeFilterModel *self,
                                                             DeeModelIter *iter);

Includes `iter` from the back end model in the filtered model, appending it to the end of the filtered rows.

This method is usually called when implementing DeeFilterMapFunc or DeeFilterMapNotify methods.

Returns : | Always returns `iter`. [transfer none]

### dee_filter_model_contains ()

    gboolean            dee_filter_model_contains           (DeeFilterModel *self,
                                                             DeeModelIter *iter);

Check if `iter` from the back end model is mapped in `self`.

`self` : | The DeeFilterModel to check
`iter` : | The DeeModelIter to check. [transfer none]
Returns : | `TRUE` if and only if `iter` is contained in `self`.

### dee_filter_model_insert_iter ()

    DeeModelIter *      dee_filter_model_insert_iter        (DeeFilterModel *self,
                                                             DeeModelIter *iter,
                                                             guint pos);

Includes `iter` from the back end model in the filtered model, inserting it at `pos` pushing other rows down.

This method is usually called when implementing DeeFilterMapFunc or DeeFilterMapNotify methods.

Returns : | Always returns `iter`. [transfer none]

### dee_filter_model_insert_iter_before ()

    DeeModelIter *      dee_filter_model_insert_iter_before (DeeFilterModel *self,
                                                             DeeModelIter *iter,
                                                             DeeModelIter *pos);

Includes `iter` from the back end model in the filtered model, inserting it at the position before `pos` pushing other rows down.

This method is usually called when implementing DeeFilterMapFunc or DeeFilterMapNotify methods.

Returns : | Always returns `iter`. [transfer none]

### dee_filter_model_insert_iter_with_original_order ()

    DeeModelIter *      dee_filter_model_insert_iter_with_original_order
                                                            (DeeFilterModel *self,
                                                             DeeModelIter *iter);

`self`: A DeeFilterModel instance `iter`: Iterator

Inserts `iter` in `self` in a way that is consistent with the ordering of the rows in the original DeeModel behind `self`. THis method assumes that `self` is already ordered this way. If that's not the case then this method has undefined behaviour.

This method is mainly intended as a helper for DeeFilterMapNotify functions of DeeFilter implementations that creates filter models sorted in accordance with the original models.

Returns : | Always returns `iter`. [transfer none]

### dee_filter_model_new ()

    DeeModel *          dee_filter_model_new                (DeeModel *orig_model,
                                                             DeeFilter *filter);

`orig_model` : | The back end model. This will be set as the "back-end" property
`filter` : | Structure containing the logic used to create the filter model. The filter model will create it's own copy of `filter` so unless `filter` is allocated statically or on the stack you need to free it after calling this method.
Returns : | A newly allocated DeeFilterModel. Free with `g_object_unref()`. [transfer full][type DeeFilterModel]

### dee_filter_model_prepend_iter ()

    DeeModelIter *      dee_filter_model_prepend_iter       (DeeFilterModel *self,
                                                             DeeModelIter *iter);

Includes `iter` from the back end model in the filtered model, prepending it to the beginning of the filtered rows.

This method is usually called when implementing DeeFilterMapFunc or DeeFilterMapNotify methods.

Returns : | Always returns `iter`. [transfer none]

## Property Details

### The `"filter"` property

      "filter"                   gpointer              : Read / Write / Construct Only

Property holding the DeeFilter used to filter the model defined in the "back-end" property.

Type: DeeFilter