From e1c51092df965105e6b6879f6a9cc9936e4a1b50 Mon Sep 17 00:00:00 2001 From: Federico Mena Quintero Date: Thu, 1 Nov 2012 17:19:10 -0600 Subject: [PATCH] Comments on how the filtering and sorting processes work Signed-off-by: Federico Mena Quintero --- 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 90a4db2d5c..480a6f5a9d 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 8ccfa1b00e..575cc23d07 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);