* Library General Public License for more details.
*
* You should have received a copy of the GNU Library General Public
- * License along with this library; if not, write to the
- * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
- * Boston, MA 02111-1307, USA.
+ * License along with this library. If not, see <http://www.gnu.org/licenses/>.
*/
#include "config.h"
* /* Fill the list store with data */
* populate_model (list_store);
*
- * /* Get the first iter in the list */
- * valid = gtk_tree_model_get_iter_first (list_store, &iter);
- *
- * while (valid)
+ * /* Get the first iter in the list, check it is valid and walk
+ * * through the list, reading each row. */
+ * for (valid = gtk_tree_model_get_iter_first (list_store, &iter);
+ * valid;
+ * valid = gtk_tree_model_iter_next (list_store, &iter))
* {
- * /* Walk through the list, reading each row */
* gchar *str_data;
* gint int_data;
*
* g_free (str_data);
*
* row_count++;
- * valid = gtk_tree_model_iter_next (list_store, &iter);
* }
* </programlisting>
* </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) \
struct _GtkTreePath
{
- gint depth;
+ gint depth; /* Number of elements */
+ gint alloc; /* Number of allocated elements */
gint *indices;
};
* Note that no iterator is passed to the signal handler,
* since the row is already deleted.
*
- * Implementations of GtkTreeModel must emit ::row-deleted
- * <emphasis>before</emphasis> removing the node from its
- * internal data structures. This is because models and
- * views which access and monitor this model might have
- * references on the node which need to be released in the
- * row-deleted handler.
+ * This should be called by models after a row has been removed.
+ * The location pointed to by @path should be the location that
+ * the row previously was at. It may not be a valid location anymore.
*/
closure = g_closure_new_simple (sizeof (GClosure), NULL);
g_closure_set_marshal (closure, row_deleted_marshal);
row_deleted_params);
/**
- * GtkTreeModel::rows-reordered:
+ * GtkTreeModel::rows-reordered: (skip)
* @tree_model: the #GtkTreeModel on which the signal is emitted
* @path: a #GtkTreePath identifying the tree node whose children
* have been reordered
GtkTreePath *retval;
retval = g_slice_new (GtkTreePath);
retval->depth = 0;
+ retval->alloc = 0;
retval->indices = NULL;
return retval;
/**
* gtk_tree_path_new_from_indices:
* @first_index: first integer
- * @varargs: list of integers terminated by -1
+ * @...: list of integers terminated by -1
*
* Creates a new path with @first_index and @varargs as indices.
*
*/
void
gtk_tree_path_append_index (GtkTreePath *path,
- gint index)
+ gint index_)
{
g_return_if_fail (path != NULL);
- g_return_if_fail (index >= 0);
+ g_return_if_fail (index_ >= 0);
+
+ if (path->depth == path->alloc)
+ {
+ gint *indices;
+ path->alloc = MAX (path->alloc * 2, 1);
+ indices = g_new (gint, path->alloc);
+ memcpy (indices, path->indices, path->depth * sizeof (gint));
+ g_free (path->indices);
+ path->indices = indices;
+ }
path->depth += 1;
- path->indices = g_realloc (path->indices, path->depth * sizeof(gint));
- path->indices[path->depth - 1] = index;
+ path->indices[path->depth - 1] = index_;
}
/**
gtk_tree_path_prepend_index (GtkTreePath *path,
gint index)
{
- gint *new_indices;
-
- (path->depth)++;
- new_indices = g_new (gint, path->depth);
-
- if (path->indices == NULL)
+ if (path->depth == path->alloc)
{
- path->indices = new_indices;
- path->indices[0] = index;
- return;
+ gint *indices;
+ path->alloc = MAX (path->alloc * 2, 1);
+ indices = g_new (gint, path->alloc);
+ memcpy (indices + 1, path->indices, path->depth * sizeof (gint));
+ g_free (path->indices);
+ path->indices = indices;
}
- memcpy (new_indices + 1, path->indices, (path->depth - 1)*sizeof (gint));
- g_free (path->indices);
- path->indices = new_indices;
+ else if (path->depth > 0)
+ memmove (path->indices + 1, path->indices, path->depth * sizeof (gint));
+
+ path->depth += 1;
path->indices[0] = index;
}
}
/**
- * gtk_tree_path_get_indices:
+ * gtk_tree_path_get_indices: (skip)
* @path: a #GtkTreePath
*
* Returns the current indices of @path.
* This is an array of integers, each representing a node in a tree.
* This value should not be freed.
*
+ * The length of the array can be obtained with gtk_tree_path_get_depth().
+ *
* Return value: The current indices, or %NULL
*/
gint *
/**
* gtk_tree_path_free:
- * @path: a #GtkTreePath
+ * @path: (allow-none): a #GtkTreePath
*
- * Frees @path.
+ * Frees @path. If @path is %NULL, it simply returns.
*/
void
gtk_tree_path_free (GtkTreePath *path)
retval = g_slice_new (GtkTreePath);
retval->depth = path->depth;
- retval->indices = g_new (gint, path->depth);
+ retval->alloc = retval->depth;
+ retval->indices = g_new (gint, path->alloc);
memcpy (retval->indices, path->indices, path->depth * sizeof (gint));
return retval;
}
* @iter: (out): the uninitialized #GtkTreeIter
* @path: the #GtkTreePath
*
- * Sets @iter to a valid iterator pointing to @path.
+ * Sets @iter to a valid iterator pointing to @path. If @path does
+ * not exist, @iter is set to an invalid iterator and %FALSE is returned.
*
* Return value: %TRUE, if @iter was set
*/
/**
* gtk_tree_model_iter_previous:
* @tree_model: a #GtkTreeModel
- * @iter: (inout): the #GtkTreeIter
+ * @iter: (in): the #GtkTreeIter
*
* Sets @iter to point to the previous node at the current level.
*
*
* This function is primarily meant as a way for views to let
* caching models know when nodes are being displayed (and hence,
- * whether or not to cache that node). 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
+ * whether or not to cache that node). Being displayed means a node
+ * is in an expanded branch, regardless of whether the node is currently
+ * 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.
*
* A model should be expected to be able to get an iter independent
* gtk_tree_model_get:
* @tree_model: a #GtkTreeModel
* @iter: a row in @tree_model
- * @Varargs: pairs of column number and value return locations,
+ * @...: pairs of column number and value return locations,
* terminated by -1
*
* Gets the value of one or more cells in the row referenced by @iter.
while (column != -1)
{
- GValue value = { 0, };
+ GValue value = G_VALUE_INIT;
gchar *error = NULL;
if (column >= gtk_tree_model_get_n_columns (tree_model))
* This should be called by models after a row has been removed.
* The location pointed to by @path should be the location that
* 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
gtk_tree_model_row_deleted (GtkTreeModel *tree_model,
}
/**
- * gtk_tree_model_rows_reordered:
+ * gtk_tree_model_rows_reordered: (skip)
* @tree_model: a #GtkTreeModel
* @path: a #GtkTreePath pointing to the tree node whose children
* have been reordered
* Creates a row reference based on @path.
*
* This reference will keep pointing to the node pointed to
- * by @path, so long as it exists. It listens to all signals
- * emitted by @model, and updates its path appropriately. If
+ * by @path, so long as it exists. Any changes that occur on @model are
+ * propagated, and the path is updated appropriately. If
* @path isn't a valid path in @model, then %NULL is returned.
*
* Return value: a newly allocated #GtkTreeRowReference, or %NULL
}
/**
- * gtk_tree_row_reference_reordered:
+ * gtk_tree_row_reference_reordered: (skip)
* @proxy: a #GObject
* @path: the parent path of the reordered signal
* @iter: the iter pointing to the parent of the reordered
projects / ~andy / gtk / blobdiff