DeeFilterModel

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

Synopsis

#include <dee.h>

                    DeeFilterModel;
                    DeeFilterModelClass;
                    DeeFilterModelPrivate;
                    DeeFilter;
void                (*DeeModelMapFunc)                  (DeeModel *orig_model,
                                                         DeeFilterModel *filter_model,
                                                         gpointer user_data);
void                (*DeeModelMapNotify)                (DeeModel *orig_model,
                                                         DeeModelIter *orig_iter,
                                                         DeeFilterModel *filter_model,
                                                         gpointer user_data);
DeeModel*           dee_filter_model_new                (const DeeFilter *filter,
                                                         DeeModel *orig_model);
gboolean            dee_filter_model_contains           (DeeFilterModel *self,
                                                         DeeModelIter *iter);
DeeModelIter*       dee_filter_model_append_iter        (DeeFilterModel *self,
                                                         DeeModelIter *iter);
DeeModelIter*       dee_filter_model_prepend_iter       (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);

Object Hierarchy

  GObject
   +----DeeVersionedModel
         +----DeeProxyModel
               +----DeeFilterModel

Implemented Interfaces

DeeFilterModel implements DeeModel.

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, DeeModelMapFunc and DeeModelMapNotify, 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.

Details

DeeFilterModel

typedef struct _DeeFilterModel DeeFilterModel;

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


DeeFilterModelClass

typedef struct {
} DeeFilterModelClass;


DeeFilterModelPrivate

typedef struct _DeeFilterModelPrivate DeeFilterModelPrivate;

Ignore this structure.


DeeFilter

typedef struct {
  DeeModelMapFunc   map_func;
  DeeModelMapNotify map_notify;
  GDestroyNotify    destroy;
  gpointer          user_data;
} DeeFilter;

Structure encapsulating the mapping logic used to construct a DeeFilterModel

DeeModelMapFunc map_func;

The DeeModelMapFunc used to construct the initial contents of a DeeFilterModel

DeeModelMapNotify map_notify;

Callback invoked when the original model changes

GDestroyNotify destroy;

Callback for freeing the user_data

gpointer user_data;

Free form user data associated with the filter. This pointer will be passed to map_func and map_notify

DeeModelMapFunc ()

void                (*DeeModelMapFunc)                  (DeeModel *orig_model,
                                                         DeeFilterModel *filter_model,
                                                         gpointer user_data);

Function used to collect the rows from a model that should be included in a DeeFilterModel. To add rows to filter_model use the methods dee_filter_model_append_iter(), dee_filter_model_prepend_iter(), dee_filter_model_insert_iter(), and dee_filter_model_insert_iter_before().

The iteration over the original model is purposely left to the map func in order to allow optimized iterations if the the caller has a priori knowledge of the sorting and grouping of the data in the original model.

orig_model :

The model containing the original data to filter

filter_model :

The model that will contain the filtered results. The filter func must iterate over orig_model and add all relevant rows to filter_model. This model is guaranteed to be empty when the filter func is invoked

user_data :

User data passed together with the filter func

DeeModelMapNotify ()

void                (*DeeModelMapNotify)                (DeeModel *orig_model,
                                                         DeeModelIter *orig_iter,
                                                         DeeFilterModel *filter_model,
                                                         gpointer user_data);

Callback invoked when a row is added to orig_model. To add rows to filter_model use the methods dee_filter_model_append_iter(), dee_filter_model_prepend_iter(), dee_filter_model_insert_iter(), and dee_filter_model_insert_iter_before().

orig_model :

The model containing the added row

orig_iter :

A DeeModelIter pointing to the new row in orig_model

filter_model :

The model that was also passed to the DeeModelMapFunc of the DeeFilter this functions is a part of

user_data :

User data for the DeeFilter

dee_filter_model_new ()

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

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.

orig_model :

The back end model. This will be set as the "back-end" property

Returns :

A newly allocated DeeFilterModel. Free with g_object_unref().

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

Returns :

TRUE if and only if iter is contained in self.

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 DeeModelMapFunc or DeeModelMapNotify methods.

Returns :


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 DeeModelMapFunc or DeeModelMapNotify methods.

Returns :


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 DeeModelMapFunc or DeeModelMapNotify methods.

Returns :


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 DeeModelMapFunc or DeeModelMapNotify methods.

Returns :

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.