callisto-debian/gtk3
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

GtkTreeModel: add more detailed documentation on reference counting

Browse Source
This commit is contained in:
Kristian Rietveld 2011-08-11 10:42:29 +02:00
parent 60d031e311
commit 85d4a5abc7
1 changed files with 38 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
gtk/gtktreemodel.c
View File

@ -197,6 +197,36 @@
* </programlisting> * </programlisting>
* </example> * </example>
* *
* The #GtkTreeModel interface contains two methods for reference
* counting: gtk_tree_model_ref_node() and gtk_tree_model_unref_node().
* These two methods are optional to implement. The reference counting
* is meant as a way for views to let models know when nodes are being
* displayed. #GtkTreeView will take a reference on a node when it is
* visible, which means the node is either in the toplevel or expanded.
* Being displayed does not mean that the node is currently directly
* visible to the user in the viewport. Based on this reference counting
* scheme a caching model, for example, can decide whether or not to cache
* a node based on the reference count. A file-system based model would
* not want to keep the entire file hierarchy in memory, but just the
* folders that are currently expanded in every current view.
*
* When working with reference counting, the following rules must be taken
* into account:
* <itemizedlist>
* <listitem><para>Never take a reference on a node without owning a
* reference on its parent. This means that all parent nodes of a referenced
* node must be referenced as well.</para></listitem>
* <listitem><para>Outstanding references on a deleted node are not released.
* This is not possible because the node has already been deleted by the
* time the row-deleted signal is received.
* </para></listitem>
* <listitem><para>Models are not obligated to emit a signal on rows of
* which none of its siblings are referenced. To phrase this differently,
* signals are only required for levels in which nodes are referenced. For
* the root level however, signals must be emitted at all times (however the
* root level is always referenced when any view is attached).
* </para></listitem>
* </itemizedlist>
*/ */
#define INITIALIZE_TREE_ITER(Iter) \ #define INITIALIZE_TREE_ITER(Iter) \
@ -1615,9 +1645,11 @@ gtk_tree_model_iter_parent (GtkTreeModel *tree_model,
* *
* This function is primarily meant as a way for views to let * This function is primarily meant as a way for views to let
* caching models know when nodes are being displayed (and hence, * caching models know when nodes are being displayed (and hence,
* whether or not to cache that node). For example, a file-system * whether or not to cache that node). Being displayed means a node
* based model would not want to keep the entire file-hierarchy in * is in an expanded branch, regardless of whether the node is currently
* memory, just the sections that are currently being displayed by * visible in the viewport. For example, a file-system based model
* would not want to keep the entire file-hierarchy in memory,
* just the sections that are currently being displayed by
* every current view. * every current view.
* *
* A model should be expected to be able to get an iter independent * A model should be expected to be able to get an iter independent
@ -1824,6 +1856,9 @@ gtk_tree_model_row_has_child_toggled (GtkTreeModel *tree_model,
* This should be called by models after a row has been removed. * This should be called by models after a row has been removed.
* The location pointed to by @path should be the location that * The location pointed to by @path should be the location that
* the row previously was at. It may not be a valid location anymore. * the row previously was at. It may not be a valid location anymore.
*
* Nodes that are deleted are not unreffed, this means that any
* outstanding references on the deleted node should not be released.
*/ */
void void
gtk_tree_model_row_deleted (GtkTreeModel *tree_model, gtk_tree_model_row_deleted (GtkTreeModel *tree_model,