Introducing GtkTreeModelFilter

[Kristian Rietveld <kris gtk org>]

Hello, my name is GtkTreeModelFilter. I am a really useful GtkTreeModel
and would like to be included in gtk+2.4 and travel around the Internet.


What am I and why am I useful?

I am a multifunctional model wrapping another model (just like my
brother GtkTreeModelSort does) and can do the following things:
*  filter specific rows, based on data from a "visible column", a column
storing booleans indicating whether the row should be filtered or not,
or based on the return value of a "visible function", which gets a
model, iter and user_data and returns a boolean indicating whether the
row should be filtered or not.
*  modify the "appearance" of the model, using a modify function. You
pass in the number of columns you want to have, together with the GTypes
and a modify function. For each row, the modify function will be called,
with a model, iter, GValue, column number, and user_data. The modify
function should set a correct value in the GValue, which will be shown
in the model. This is extremely powerful and allows for just changing
some values and also for creating a completely different model based on
the given child model. It's a bit difficult to explain this, you would
just have to see this in action.
*  set a different root node, also known as a "virtual root". This is
self-explaining, you can pass in a GtkTreePath indicating the root node
for the filter during construction time.

And yes, it is even possible to use these features at once in the same
model.


Real-World usage

I am already being used in several applications. Most notably Rhythmbox,
which is a really demanding GtkTreeModelFilter user, displaying and
filtering thousands of rows. I can handle that pretty well (although a
bit slow).


Questions/Sidenotes

Would it be a good idea to make my data really private using Owen's cool
GObjectPrivate thing?

Sidenote: you can set a modify or (filter function/filter column) only
*once*.



I have attached my headerfile and I hope that you will consider
including me in your next release.


thanks,

	GtkTreeModelFilter


---

Sorry, I couldn't resist writing this e-mail this way :P.


	-Kris

/* gtktreemodelfilter.h
 * Copyright (C) 2000,2001  Red Hat, Inc., Jonathan Blandford <jrb redhat com>
 * Copyright (C) 2001,2002  Kristian Rietveld <kris gtk org>
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License as
 * published by the Free Software Foundation; either version 2 of the
 * License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * General Public License for more details.
 *
 * You should have received a copy of the GNU General Public
 * License along with this program; if not, write to the
 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 * Boston, MA 02111-1307, USA.
 */

#ifndef __GTK_TREE_MODEL_FILTER_H__
#define __GTK_TREE_MODEL_FILTER_H__

#include <gtk/gtktreemodel.h>

G_BEGIN_DECLS

#define GTK_TYPE_TREE_MODEL_FILTER              (gtk_tree_model_filter_get_type ())
#define GTK_TREE_MODEL_FILTER(obj)              (G_TYPE_CHECK_INSTANCE_CAST ((obj), GTK_TYPE_TREE_MODEL_FILTER, GtkTreeModelFilter))
#define GTK_TREE_MODEL_FILTER_CLASS(vtable)     (G_TYPE_CHECK_CLASS_CAST ((vtable), GTK_TYPE_TREE_MODEL_FILTER, GtkTreeModelFilterClass))
#define GTK_IS_TREE_MODEL_FILTER(obj)           (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GTK_TYPE_TREE_MODEL_FILTER))
#define GTK_IS_TREE_MODEL_FILTER_CLASS(vtable)  (G_TYPE_CHECK_CLASS_TYPE ((vtable), GTK_TYPE_TREE_MODEL_FILTER))
#define GTK_TREE_MODEL_FILTER_GET_CLASS(inst)   (G_TYPE_INSTANCE_GET_CLASS ((obj), GTK_TYPE_TREE_MODEL_FILTER, GtkTreeModelFilterClass))

typedef gboolean (* GtkTreeModelFilterVisibleFunc) (GtkTreeModel *model,
                                                    GtkTreeIter  *iter,
                                                    gpointer      data);
typedef void (* GtkTreeModelFilterModifyFunc) (GtkTreeModel *model,
                                               GtkTreeIter  *iter,
                                               GValue       *value,
                                               gint          column,
                                               gpointer      data);

typedef struct _GtkTreeModelFilter        GtkTreeModelFilter;
typedef struct _GtkTreeModelFilterClass   GtkTreeModelFilterClass;

struct _GtkTreeModelFilter
{
  GObject parent;

  /*< private >*/
  gpointer root;
  gint stamp;
  guint child_flags;
  GtkTreeModel *child_model;
  gint zero_ref_count;

  guint root_level_visible;

  GtkTreePath *virtual_root;

  GtkTreeModelFilterVisibleFunc visible_func;
  gpointer visible_data;
  GtkDestroyNotify visible_destroy;

  gint modify_n_columns;
  GType *modify_types;
  GtkTreeModelFilterModifyFunc modify_func;
  gpointer modify_data;
  gpointer modify_destroy;

  gint visible_column;

  gboolean visible_method_set;
  gboolean modify_func_set;

  /* signal ids */
  guint changed_id;
  guint inserted_id;
  guint has_child_toggled_id;
  guint deleted_id;
  guint reordered_id;
};

struct _GtkTreeModelFilterClass
{
  GObjectClass parent_class;
};

GType         gtk_tree_model_filter_get_type                   (void);
GtkTreeModel *gtk_tree_model_filter_new                        (GtkTreeModel                  *child_model,
                                                                GtkTreePath                   *root);
void          gtk_tree_model_filter_set_visible_func           (GtkTreeModelFilter            *filter,
                                                                GtkTreeModelFilterVisibleFunc  func,
                                                                gpointer                       data,
                                                                GtkDestroyNotify               destroy);
void          gtk_tree_model_filter_set_modify_func            (GtkTreeModelFilter            *filter,
                                                                gint                           n_columns,
                                                                GType                         *types,
                                                                GtkTreeModelFilterModifyFunc   func,
                                                                gpointer                       data,
                                                                GtkDestroyNotify               destroy);
void          gtk_tree_model_filter_set_visible_column         (GtkTreeModelFilter            *filter,
                                                                gint                           column);

GtkTreeModel *gtk_tree_model_filter_get_model                  (GtkTreeModelFilter            *filter);

/* conversion */
void          gtk_tree_model_filter_convert_child_iter_to_iter (GtkTreeModelFilter            *filter,
                                                                GtkTreeIter                   *filter_iter,
                                                                GtkTreeIter                   *child_iter);
void          gtk_tree_model_filter_convert_iter_to_child_iter (GtkTreeModelFilter            *filter,
                                                                GtkTreeIter                   *child_iter,
                                                                GtkTreeIter                   *filter_iter);
GtkTreePath  *gtk_tree_model_filter_convert_child_path_to_path (GtkTreeModelFilter            *filter,
                                                                GtkTreePath                   *child_path);
GtkTreePath  *gtk_tree_model_filter_convert_path_to_child_path (GtkTreeModelFilter            *path,
                                                                GtkTreePath                   *filter_path);

void          gtk_tree_model_filter_refilter                   (GtkTreeModelFilter            *filter);
void          gtk_tree_model_filter_clear_cache                (GtkTreeModelFilter            *filter);

G_END_DECLS

#endif /* __GTK_TREE_MODEL_FILTER_H__ */