![]() |
![]() |
![]() |
Dee Reference Manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy | Implemented Interfaces | Properties |
#include <dee.h> struct DeeFilter; struct DeeFilterModel; struct DeeFilterModelClass; 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
); 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 (const DeeFilter *filter
,DeeModel *orig_model
); DeeModelIter * dee_filter_model_prepend_iter (DeeFilterModel *self
,DeeModelIter *iter
);
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.
There is a suite of filters shipped with Dee which you can browse in the Filters section.
struct DeeFilter { DeeModelMapFunc map_func; DeeModelMapNotify map_notify; GDestroyNotify destroy; gpointer user_data; };
Structure encapsulating the mapping logic used to construct a DeeFilterModel
DeeModelMapFunc |
The DeeModelMapFunc used to construct the initial contents of a DeeFilterModel |
DeeModelMapNotify |
Callback invoked when the original model changes |
GDestroyNotify |
Callback for freeing the user_data
|
gpointer |
Free form user data associated with the filter. This pointer will
be passed to map_func and map_notify
|
struct DeeFilterModel;
All fields in the DeeFilterModel structure are private and should never be accessed directly
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.
|
The model containing the original data to filter |
|
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 passed together with the filter func |
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()
.
|
The model containing the added row |
|
A DeeModelIter pointing to the new row in orig_model
|
|
The model that was also passed to the DeeModelMapFunc of the DeeFilter this functions is a part of |
|
User data for the DeeFilter |
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 : |
Always returns iter . [transfer none]
|
gboolean dee_filter_model_contains (DeeFilterModel *self
,DeeModelIter *iter
);
Check if iter
from the back end model is mapped in self
.
|
The DeeFilterModel to check |
|
The DeeModelIter to check. [transfer none] |
Returns : |
TRUE if and only if iter is contained in self . |
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 : |
Always returns iter . [transfer none]
|
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 : |
Always returns iter . [transfer none]
|
DeeModelIter * dee_filter_model_insert_iter_with_original_order (DeeFilterModel *self
,DeeModelIter *iter
);
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 DeeModelMapNotify functions of DeeFilter implementations that creates filter models sorted in accordance with the original models.
Returns : |
Always returns iter . [transfer none]
|
DeeModel * dee_filter_model_new (const DeeFilter *filter
,DeeModel *orig_model
);
|
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. |
|
The back end model. This will be set as the "back-end" property |
Returns : |
A newly allocated DeeFilterModel. Free with g_object_unref() . [transfer full]
|
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 : |
Always returns iter . [transfer none]
|