diff --git a/ChangeLog b/ChangeLog index d0896119d3..0b2a365fb9 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,9 @@ 2000-10-17 + * gtk/gtktreemodel.c: Added user docs. + + * gtk/gtk.h: remove gtktreedatalist.h. + * gtk/gtktreestore.c (gtk_tree_store_get_type): Get the correct parent when generating my type. diff --git a/ChangeLog.pre-2-0 b/ChangeLog.pre-2-0 index d0896119d3..0b2a365fb9 100644 --- a/ChangeLog.pre-2-0 +++ b/ChangeLog.pre-2-0 @@ -1,5 +1,9 @@ 2000-10-17 + * gtk/gtktreemodel.c: Added user docs. + + * gtk/gtk.h: remove gtktreedatalist.h. + * gtk/gtktreestore.c (gtk_tree_store_get_type): Get the correct parent when generating my type. diff --git a/ChangeLog.pre-2-10 b/ChangeLog.pre-2-10 index d0896119d3..0b2a365fb9 100644 --- a/ChangeLog.pre-2-10 +++ b/ChangeLog.pre-2-10 @@ -1,5 +1,9 @@ 2000-10-17 + * gtk/gtktreemodel.c: Added user docs. + + * gtk/gtk.h: remove gtktreedatalist.h. + * gtk/gtktreestore.c (gtk_tree_store_get_type): Get the correct parent when generating my type. diff --git a/ChangeLog.pre-2-2 b/ChangeLog.pre-2-2 index d0896119d3..0b2a365fb9 100644 --- a/ChangeLog.pre-2-2 +++ b/ChangeLog.pre-2-2 @@ -1,5 +1,9 @@ 2000-10-17 + * gtk/gtktreemodel.c: Added user docs. + + * gtk/gtk.h: remove gtktreedatalist.h. + * gtk/gtktreestore.c (gtk_tree_store_get_type): Get the correct parent when generating my type. diff --git a/ChangeLog.pre-2-4 b/ChangeLog.pre-2-4 index d0896119d3..0b2a365fb9 100644 --- a/ChangeLog.pre-2-4 +++ b/ChangeLog.pre-2-4 @@ -1,5 +1,9 @@ 2000-10-17 + * gtk/gtktreemodel.c: Added user docs. + + * gtk/gtk.h: remove gtktreedatalist.h. + * gtk/gtktreestore.c (gtk_tree_store_get_type): Get the correct parent when generating my type. diff --git a/ChangeLog.pre-2-6 b/ChangeLog.pre-2-6 index d0896119d3..0b2a365fb9 100644 --- a/ChangeLog.pre-2-6 +++ b/ChangeLog.pre-2-6 @@ -1,5 +1,9 @@ 2000-10-17 + * gtk/gtktreemodel.c: Added user docs. + + * gtk/gtk.h: remove gtktreedatalist.h. + * gtk/gtktreestore.c (gtk_tree_store_get_type): Get the correct parent when generating my type. diff --git a/ChangeLog.pre-2-8 b/ChangeLog.pre-2-8 index d0896119d3..0b2a365fb9 100644 --- a/ChangeLog.pre-2-8 +++ b/ChangeLog.pre-2-8 @@ -1,5 +1,9 @@ 2000-10-17 + * gtk/gtktreemodel.c: Added user docs. + + * gtk/gtk.h: remove gtktreedatalist.h. + * gtk/gtktreestore.c (gtk_tree_store_get_type): Get the correct parent when generating my type. diff --git a/gtk/gtk.h b/gtk/gtk.h index e7183cc01a..e039ea28c1 100644 --- a/gtk/gtk.h +++ b/gtk/gtk.h @@ -139,7 +139,6 @@ #include #include #include -#include #include #include #include diff --git a/gtk/gtktreemodel.c b/gtk/gtktreemodel.c index e00d87787f..a752884da8 100644 --- a/gtk/gtktreemodel.c +++ b/gtk/gtktreemodel.c @@ -48,6 +48,14 @@ gtk_tree_model_get_type (void) return tree_model_type; } +/** + * gtk_tree_path_new: + * @void: + * + * Creates a new #GtkTreePath. + * + * Return value: A newly created #GtkTreePath. + **/ /* GtkTreePath Operations */ GtkTreePath * gtk_tree_path_new (void) @@ -60,6 +68,16 @@ gtk_tree_path_new (void) return retval; } +/** + * gtk_tree_path_new_from_string: + * @path: The string representation of a path. + * + * Creates a new #GtkTreePath initialized to @path. @path is expected to be a + * colon separated list of numbers. For example, the string "10:4:0" would + * create a path of depth 3. + * + * Return value: A newly created #GtkTreePath. + **/ GtkTreePath * gtk_tree_path_new_from_string (gchar *path) { @@ -78,12 +96,22 @@ gtk_tree_path_new_from_string (gchar *path) if (*ptr == '\000') break; + /* FIXME: should we error out if this is not a ':', or should we be tolerant? */ path = ptr + 1; } return retval; } +/** + * gtk_tree_path_to_string: + * @path: A #GtkTreePath + * + * Generates a string representation of the path. This string is a ':' + * separated list of numbers. For example, "4:10:0:3" would be an acceptable return value for this string. + * + * Return value: A newly allocated string. Must be freed with #g_free. + **/ gchar * gtk_tree_path_to_string (GtkTreePath *path) { @@ -108,6 +136,15 @@ gtk_tree_path_to_string (GtkTreePath *path) return retval; } +/** + * gtk_tree_path_new_root: + * @void: + * + * Creates a new root #GtkTreePath. The string representation of this path is + * "0" + * + * Return value: A new #GtkTreePath. + **/ GtkTreePath * gtk_tree_path_new_root (void) { @@ -119,11 +156,24 @@ gtk_tree_path_new_root (void) return retval; } +/** + * gtk_tree_path_append_index: + * @path: A #GtkTreePath. + * @index: The index. + * + * Appends a new index to a path. As a result, the depth of the path is + * increased. + **/ void gtk_tree_path_append_index (GtkTreePath *path, gint index) { - gint *new_indices = g_new (gint, ++path->depth); + gint *new_indices; + + g_return_if_fail (path != NULL); + g_return_if_fail (index >= 0); + + new_indices = = g_new (gint, ++path->depth); if (path->indices == NULL) { path->indices = new_indices; @@ -137,6 +187,14 @@ gtk_tree_path_append_index (GtkTreePath *path, path->indices[path->depth - 1] = index; } +/** + * gtk_tree_path_prepend_index: + * @path: A #GtkTreePath. + * @index: The index. + * + * Prepends a new index to a path. As a result, the depth of the path is + * increased. + **/ void gtk_tree_path_prepend_index (GtkTreePath *path, gint index) @@ -154,18 +212,45 @@ gtk_tree_path_prepend_index (GtkTreePath *path, path->indices[0] = index; } +/** + * gtk_tree_path_get_depth: + * @path: A #GtkTreePath. + * + * Returns the current depth of @path. + * + * Return value: The depth of @path + **/ gint gtk_tree_path_get_depth (GtkTreePath *path) { + g_return_val_if_fail (path != NULL, 0); + return path->depth; } +/** + * gtk_tree_path_get_indices: + * @path: A #GtkTreePath. + * + * Returns the current indices of @path. This is an array of integers, each + * representing a node in a tree. + * + * Return value: The current indices, or NULL. + **/ gint * gtk_tree_path_get_indices (GtkTreePath *path) { + g_return_val_if_fail (path != NULL, NULL); + return path->indices; } +/** + * gtk_tree_path_free: + * @path: A #GtkTreePath. + * + * Frees @path. + **/ void gtk_tree_path_free (GtkTreePath *path) { @@ -173,6 +258,14 @@ gtk_tree_path_free (GtkTreePath *path) g_free (path); } +/** + * gtk_tree_path_copy: + * @path: A #GtkTreePath. + * + * Creates a new #GtkTreePath based upon @path. + * + * Return value: A new #GtkTreePath. + **/ GtkTreePath * gtk_tree_path_copy (GtkTreePath *path) { @@ -185,9 +278,20 @@ gtk_tree_path_copy (GtkTreePath *path) return retval; } +/** + * gtk_tree_path_compare: + * @a: A #GtkTreePath. + * @b: A #GtkTreePath to compare with. + * + * Compares two paths. If @a appears before @b in a tree, then 1, is returned. + * If @b appears before @a, then -1 is returned. If the two nodes are equal, + * then 0 is returned. + * + * Return value: The relative positions of @a and @b + **/ gint -gtk_tree_path_compare (GtkTreePath *a, - GtkTreePath *b) +gtk_tree_path_compare (const GtkTreePath *a, + const GtkTreePath *b) { gint p = 0, q = 0; @@ -208,14 +312,27 @@ gtk_tree_path_compare (GtkTreePath *a, return (a->depth < b->depth?1:-1); } +/** + * gtk_tree_path_next: + * @path: A #GtkTreePath. + * + * Moves the @path to point to the next node at the current depth. + **/ void gtk_tree_path_next (GtkTreePath *path) { g_return_if_fail (path != NULL); + g_return_if_fail (path->depth > 0); path->indices[path->depth - 1] ++; } +/** + * gtk_tree_path_prev: + * @path: A #GtkTreePath. + * + * Moves the @path to point to the previous node at the current depth, if it exists. + **/ gint gtk_tree_path_prev (GtkTreePath *path) { @@ -229,6 +346,14 @@ gtk_tree_path_prev (GtkTreePath *path) return TRUE; } +/** + * gtk_tree_path_up: + * @path: A #GtkTreePath. + * + * Moves the @path to point to it's parent node, if it has a parent. + * + * Return value: TRUE if @path has a parent, and the move was made. + **/ gint gtk_tree_path_up (GtkTreePath *path) { @@ -242,6 +367,12 @@ gtk_tree_path_up (GtkTreePath *path) return TRUE; } +/** + * gtk_tree_path_down: + * @path: A #GtkTreePath. + * + * Moves @path to point to the first child of the current path. + **/ void gtk_tree_path_down (GtkTreePath *path) { @@ -250,6 +381,14 @@ gtk_tree_path_down (GtkTreePath *path) gtk_tree_path_append_index (path, 0); } +/** + * gtk_tree_model_get_n_columns: + * @tree_model: A #GtkTreeModel. + * + * Returns the number of columns supported by the #tree_model + * + * Return value: The number of columns. + **/ gint gtk_tree_model_get_n_columns (GtkTreeModel *tree_model) { @@ -257,7 +396,16 @@ gtk_tree_model_get_n_columns (GtkTreeModel *tree_model) return (* GTK_TREE_MODEL_GET_IFACE (tree_model)->get_n_columns) (tree_model); } -/* Node options */ +/** + * gtk_tree_model_get_node: + * @tree_model: A #GtkTreeModel. + * @path: The @GtkTreePath. + * + * Returns a #GtkTreeNode located at @path. If such a node does not exist, NULL + * is returned. + * + * Return value: A #GtkTreeNode located at @path, or NULL. + **/ GtkTreeNode gtk_tree_model_get_node (GtkTreeModel *tree_model, GtkTreePath *path) @@ -266,6 +414,16 @@ gtk_tree_model_get_node (GtkTreeModel *tree_model, return (* GTK_TREE_MODEL_GET_IFACE (tree_model)->get_node) (tree_model, path); } +/** + * gtk_tree_model_get_path: + * @tree_model: A #GtkTreeModel. + * @node: The #GtkTreeNode. + * + * Returns a newly created #GtkTreePath that points to @node. This path should + * be freed with #gtk_tree_path_free. + * + * Return value: a newly created #GtkTreePath. + **/ GtkTreePath * gtk_tree_model_get_path (GtkTreeModel *tree_model, GtkTreeNode node) @@ -274,16 +432,36 @@ gtk_tree_model_get_path (GtkTreeModel *tree_model, return (* GTK_TREE_MODEL_GET_IFACE (tree_model)->get_path) (tree_model, node); } +/** + * gtk_tree_model_node_get_value: + * @tree_model: A #GtkTreeModel. + * @node: The #GtkTreeNode. + * @column: A column on the node. + * @value: An empty #GValue to set. + * + * Sets initializes and sets @value to that at @column. When done with value, + * #g_value_unset needs to be called on it. + **/ void gtk_tree_model_node_get_value (GtkTreeModel *tree_model, GtkTreeNode node, - gint column, - GValue *value) + gint column, + GValue *value) { g_return_if_fail (GTK_TREE_MODEL_GET_IFACE (tree_model)->node_get_value != NULL); (* GTK_TREE_MODEL_GET_IFACE (tree_model)->node_get_value) (tree_model, node, column, value); } +/** + * gtk_tree_model_node_next: + * @tree_model: A #GtkTreeModel. + * @node: A reference to a #GtkTreeNode. + * + * Sets @node to be the node following it at the current level. If there is no + * next @node, FALSE is returned, and *@node is set to NULL. + * + * Return value: TRUE if @node has been changed to the next node. + **/ gboolean gtk_tree_model_node_next (GtkTreeModel *tree_model, GtkTreeNode *node) @@ -292,6 +470,16 @@ gtk_tree_model_node_next (GtkTreeModel *tree_model, return (* GTK_TREE_MODEL_GET_IFACE (tree_model)->node_next) (tree_model, node); } +/** + * gtk_tree_model_node_children: + * @tree_model: A #GtkTreeModel. + * @node: The #GtkTreeNode to get children from. + * + * Returns the first child node of @node. If it has no children, then NULL is + * returned. + * + * Return value: The first child of @node, or NULL. + **/ GtkTreeNode gtk_tree_model_node_children (GtkTreeModel *tree_model, GtkTreeNode node) @@ -300,6 +488,15 @@ gtk_tree_model_node_children (GtkTreeModel *tree_model, return (* GTK_TREE_MODEL_GET_IFACE (tree_model)->node_children) (tree_model, node); } +/** + * gtk_tree_model_node_has_child: + * @tree_model: A #GtkTreeModel. + * @node: The #GtkTreeNode to test for children. + * + * Returns TRUE if @node has children, FALSE otherwise. + * + * Return value: TRUE if @node has children. + **/ gboolean gtk_tree_model_node_has_child (GtkTreeModel *tree_model, GtkTreeNode node) @@ -308,6 +505,15 @@ gtk_tree_model_node_has_child (GtkTreeModel *tree_model, return (* GTK_TREE_MODEL_GET_IFACE (tree_model)->node_has_child) (tree_model, node); } +/** + * gtk_tree_model_node_n_children: + * @tree_model: A #GtkTreeModel. + * @node: The #GtkTreeNode. + * + * Returns the number of children that @node has. + * + * Return value: The number of children of @node. + **/ gint gtk_tree_model_node_n_children (GtkTreeModel *tree_model, GtkTreeNode node) @@ -316,15 +522,35 @@ gtk_tree_model_node_n_children (GtkTreeModel *tree_model, return (* GTK_TREE_MODEL_GET_IFACE (tree_model)->node_n_children) (tree_model, node); } +/** + * gtk_tree_model_node_nth_child: + * @tree_model: A #GtkTreeModel. + * @node: The #GtkTreeNode to get the child from. + * @n: The index of the desired #GtkTreeNode. + * + * Returns a child of @node, using the given index. The first index is 0. If + * the index is too big, NULL is returned. + * + * Return value: the child of @node at index @n. + **/ GtkTreeNode gtk_tree_model_node_nth_child (GtkTreeModel *tree_model, GtkTreeNode node, - gint n) + gint n) { g_return_val_if_fail (GTK_TREE_MODEL_GET_IFACE (tree_model)->node_nth_child != NULL, NULL); return (* GTK_TREE_MODEL_GET_IFACE (tree_model)->node_nth_child) (tree_model, node, n); } +/** + * gtk_tree_model_node_parent: + * @tree_model: A #GtkTreeModel. + * @node: The #GtkTreeNode. + * + * Returns the parent of @node. If @node is at depth 0, then NULL is returned. + * + * Return value: Returns the parent node of @node, or NULL. + **/ GtkTreeNode gtk_tree_model_node_parent (GtkTreeModel *tree_model, GtkTreeNode node)