[gtk+/gtk-3-6] Comments on how the filtering and sorting processes work

[Federico Mena Quintero <federico src gnome org>]

commit e1c51092df965105e6b6879f6a9cc9936e4a1b50
Author: Federico Mena Quintero <federico gnome org>
Date:   Thu Nov 1 17:19:10 2012 -0600

    Comments on how the filtering and sorting processes work
    
    Signed-off-by: Federico Mena Quintero <federico gnome org>

 gtk/gtkfilesystemmodel.c |   22 +++++++++++++++++++++-
 gtk/gtkfilesystemmodel.h |    2 --
 2 files changed, 21 insertions(+), 3 deletions(-)
---
diff --git a/gtk/gtkfilesystemmodel.c b/gtk/gtkfilesystemmodel.c
index 90a4db2..480a6f5 100644
--- a/gtk/gtkfilesystemmodel.c
+++ b/gtk/gtkfilesystemmodel.c
@@ -42,6 +42,9 @@
  *      the special kind of usage for "search" and "recent-files", where the file chooser gives the model the
  *      files to be displayed.
  *
+ * Internal data structure
+ * -----------------------
+ *
  * Each file is kept in a FileModelNode structure.  Each FileModelNode holds a GFile* and other data.  All the
  * node structures have the same size, determined at runtime, depending on the number of columns that were passed
  * to _gtk_file_system_model_new() or _gtk_file_system_model_new_for_directory() (that is, the size of a node is
@@ -66,7 +69,14 @@
  *
  * Each FileModelNode has a node->visible field, which indicates whether the node is visible in the GtkTreeView.
  * A node may be invisible if, for example, it corresponds to a hidden file and the file chooser is not showing
- * hidden files.
+ * hidden files.  Also, a file filter may be explicitly set onto the model, for example, to only show files that
+ * match "*.jpg".  In this case, node->filtered_out says whether the node failed the filter.  The ultimate
+ * decision on whether a node is visible or not in the treeview is distilled into the node->visible field.
+ * The reason for having a separate node->filtered_out field is so that the file chooser can query whether
+ * a (filtered-out) folder should be made sensitive in the GUI.
+ *
+ * Visible rows vs. possibly-invisible nodes
+ * -----------------------------------------
  *
  * Since not all nodes in the model->files array may be visible, we need a way to map visible row indexes from
  * the treeview to array indexes in our array of files.  And thus we introduce a bit of terminology:
@@ -95,6 +105,16 @@
  *
  * You never access a node->row directly.  Instead, call node_get_tree_row().  That function will validate the nodes
  * up to the sought one if the node is not valid yet, and it will return a proper 0-based row.
+ *
+ * Sorting
+ * -------
+ *
+ * The model implements the GtkTreeSortable interface.  To avoid re-sorting
+ * every time a node gets added (which would lead to O(n^2) performance during
+ * the initial population of the model), the model can freeze itself (with
+ * freeze_updates()) during the intial population process.  When the model is
+ * frozen, sorting will not happen.  The model will sort itself when the freeze
+ * count goes back to zero, via corresponding calls to thaw_updates().
  */
 
 /*** DEFINES ***/
diff --git a/gtk/gtkfilesystemmodel.h b/gtk/gtkfilesystemmodel.h
index 8ccfa1b..575cc23 100644
--- a/gtk/gtkfilesystemmodel.h
+++ b/gtk/gtkfilesystemmodel.h
@@ -81,8 +81,6 @@ void                _gtk_file_system_model_set_show_files   (GtkFileSystemModel
 							     gboolean            show_files);
 void                _gtk_file_system_model_set_filter_folders (GtkFileSystemModel *model,
 							     gboolean            show_folders);
-void                _gtk_file_system_model_freeze_updates   (GtkFileSystemModel *model);
-void                _gtk_file_system_model_thaw_updates     (GtkFileSystemModel *model);
 void                _gtk_file_system_model_clear_cache      (GtkFileSystemModel *model,
                                                              int                 column);