From 9e1fc3a7babc6c6b611024a1856573ab12c65386 Mon Sep 17 00:00:00 2001 From: Jonathan Blandford Date: Sat, 8 Sep 2001 18:23:47 +0000 Subject: [PATCH] Write documentation Write documentation Sat Sep 8 14:19:49 2001 Jonathan Blandford * gtk/gtkliststore.c: Write documentation * gtk/gtktreestore.c: Write documentation Quick Documentation cleanup pass. --- ChangeLog | 5 + ChangeLog.pre-2-0 | 5 + ChangeLog.pre-2-10 | 5 + ChangeLog.pre-2-2 | 5 + ChangeLog.pre-2-4 | 5 + ChangeLog.pre-2-6 | 5 + ChangeLog.pre-2-8 | 5 + docs/reference/gtk/tmpl/gtk-unused.sgml | 6 + docs/reference/gtk/tmpl/gtkcontainer.sgml | 7 - docs/reference/gtk/tmpl/gtkliststore.sgml | 24 +- docs/reference/gtk/tmpl/gtktreemodel.sgml | 6 +- docs/reference/gtk/tree_widget.sgml | 38 ++- gtk/gtkliststore.c | 92 ++++--- gtk/gtkliststore.h | 16 +- gtk/gtktreeselection.c | 10 +- gtk/gtktreestore.c | 302 +++++++++++++++------- 16 files changed, 370 insertions(+), 166 deletions(-) diff --git a/ChangeLog b/ChangeLog index fff88df6c1..bb7d80a9f9 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,8 @@ +Sat Sep 8 14:19:49 2001 Jonathan Blandford + + * gtk/gtkliststore.c: Write documentation + * gtk/gtktreestore.c: Write documentation + Sat Sep 8 13:53:09 2001 Owen Taylor * gtk/gtkrc.[ch] gtk/gtkstyle.[ch]: Replace uses of GBSearchArray diff --git a/ChangeLog.pre-2-0 b/ChangeLog.pre-2-0 index fff88df6c1..bb7d80a9f9 100644 --- a/ChangeLog.pre-2-0 +++ b/ChangeLog.pre-2-0 @@ -1,3 +1,8 @@ +Sat Sep 8 14:19:49 2001 Jonathan Blandford + + * gtk/gtkliststore.c: Write documentation + * gtk/gtktreestore.c: Write documentation + Sat Sep 8 13:53:09 2001 Owen Taylor * gtk/gtkrc.[ch] gtk/gtkstyle.[ch]: Replace uses of GBSearchArray diff --git a/ChangeLog.pre-2-10 b/ChangeLog.pre-2-10 index fff88df6c1..bb7d80a9f9 100644 --- a/ChangeLog.pre-2-10 +++ b/ChangeLog.pre-2-10 @@ -1,3 +1,8 @@ +Sat Sep 8 14:19:49 2001 Jonathan Blandford + + * gtk/gtkliststore.c: Write documentation + * gtk/gtktreestore.c: Write documentation + Sat Sep 8 13:53:09 2001 Owen Taylor * gtk/gtkrc.[ch] gtk/gtkstyle.[ch]: Replace uses of GBSearchArray diff --git a/ChangeLog.pre-2-2 b/ChangeLog.pre-2-2 index fff88df6c1..bb7d80a9f9 100644 --- a/ChangeLog.pre-2-2 +++ b/ChangeLog.pre-2-2 @@ -1,3 +1,8 @@ +Sat Sep 8 14:19:49 2001 Jonathan Blandford + + * gtk/gtkliststore.c: Write documentation + * gtk/gtktreestore.c: Write documentation + Sat Sep 8 13:53:09 2001 Owen Taylor * gtk/gtkrc.[ch] gtk/gtkstyle.[ch]: Replace uses of GBSearchArray diff --git a/ChangeLog.pre-2-4 b/ChangeLog.pre-2-4 index fff88df6c1..bb7d80a9f9 100644 --- a/ChangeLog.pre-2-4 +++ b/ChangeLog.pre-2-4 @@ -1,3 +1,8 @@ +Sat Sep 8 14:19:49 2001 Jonathan Blandford + + * gtk/gtkliststore.c: Write documentation + * gtk/gtktreestore.c: Write documentation + Sat Sep 8 13:53:09 2001 Owen Taylor * gtk/gtkrc.[ch] gtk/gtkstyle.[ch]: Replace uses of GBSearchArray diff --git a/ChangeLog.pre-2-6 b/ChangeLog.pre-2-6 index fff88df6c1..bb7d80a9f9 100644 --- a/ChangeLog.pre-2-6 +++ b/ChangeLog.pre-2-6 @@ -1,3 +1,8 @@ +Sat Sep 8 14:19:49 2001 Jonathan Blandford + + * gtk/gtkliststore.c: Write documentation + * gtk/gtktreestore.c: Write documentation + Sat Sep 8 13:53:09 2001 Owen Taylor * gtk/gtkrc.[ch] gtk/gtkstyle.[ch]: Replace uses of GBSearchArray diff --git a/ChangeLog.pre-2-8 b/ChangeLog.pre-2-8 index fff88df6c1..bb7d80a9f9 100644 --- a/ChangeLog.pre-2-8 +++ b/ChangeLog.pre-2-8 @@ -1,3 +1,8 @@ +Sat Sep 8 14:19:49 2001 Jonathan Blandford + + * gtk/gtkliststore.c: Write documentation + * gtk/gtktreestore.c: Write documentation + Sat Sep 8 13:53:09 2001 Owen Taylor * gtk/gtkrc.[ch] gtk/gtkstyle.[ch]: Replace uses of GBSearchArray diff --git a/docs/reference/gtk/tmpl/gtk-unused.sgml b/docs/reference/gtk/tmpl/gtk-unused.sgml index 5a4532ffa3..658a0dc6a7 100644 --- a/docs/reference/gtk/tmpl/gtk-unused.sgml +++ b/docs/reference/gtk/tmpl/gtk-unused.sgml @@ -225,6 +225,12 @@ has the focus. @clist: The #GtkCList widget to check. + + + + + + diff --git a/docs/reference/gtk/tmpl/gtkcontainer.sgml b/docs/reference/gtk/tmpl/gtkcontainer.sgml index 4fa9b0e086..8c7596d839 100644 --- a/docs/reference/gtk/tmpl/gtkcontainer.sgml +++ b/docs/reference/gtk/tmpl/gtkcontainer.sgml @@ -38,13 +38,6 @@ GtkContainer @pspec: - - - - - - - diff --git a/docs/reference/gtk/tmpl/gtkliststore.sgml b/docs/reference/gtk/tmpl/gtkliststore.sgml index a83c4cef94..35ae04ce37 100644 --- a/docs/reference/gtk/tmpl/gtkliststore.sgml +++ b/docs/reference/gtk/tmpl/gtkliststore.sgml @@ -36,8 +36,10 @@ GtkListStore -@store: +@list_store: @iter: + +@store: @@ -45,9 +47,11 @@ GtkListStore -@store: +@list_store: @iter: @position: + +@store: @@ -55,9 +59,11 @@ GtkListStore -@store: +@list_store: @iter: @sibling: + +@store: @@ -65,9 +71,11 @@ GtkListStore -@store: +@list_store: @iter: @sibling: + +@store: @@ -75,8 +83,10 @@ GtkListStore -@store: +@list_store: @iter: + +@store: @@ -84,7 +94,9 @@ GtkListStore -@store: +@list_store: @iter: + +@store: diff --git a/docs/reference/gtk/tmpl/gtktreemodel.sgml b/docs/reference/gtk/tmpl/gtktreemodel.sgml index ecdc8bca81..7aaa1d9aba 100644 --- a/docs/reference/gtk/tmpl/gtktreemodel.sgml +++ b/docs/reference/gtk/tmpl/gtktreemodel.sgml @@ -1,8 +1,8 @@ -gtktreemodel +GtkTreeModel - +The tree interface used by #GtkTreeView @@ -11,7 +11,7 @@ gtktreemodel - +#GtkTreeView, #GtkTreeStore, #GtkListStore diff --git a/docs/reference/gtk/tree_widget.sgml b/docs/reference/gtk/tree_widget.sgml index 7efe6491f5..c47fc1f646 100644 --- a/docs/reference/gtk/tree_widget.sgml +++ b/docs/reference/gtk/tree_widget.sgml @@ -7,7 +7,9 @@ Tree and List Widget Overview - Overview of GtkTreeModel, GtkTreeView, and friends + Overview of GtkTreeModel, GtkTreeView, and other assocoiated widgets @@ -16,14 +18,27 @@ To create a tree or list in GTK+, you need to use the GtkTreeModel interface, in conjunction with the GtkTreeView. + linkend="GtkTreeView">GtkTreeView widget. - Write real docs here + This widget is designed around a + Model/View/Controller design and consists + of four major parts: + + the tree view widget (GtkTreeView) + the view column (GtkTreeViewColumn) + the cell renderers (GtkCellRenderer etc.) + and the model interface (GtkTreeModel) + + The View is composed of the first three, + while the last is the Model. One of the + prime benefits of the MVC design is that multiple views can be + created of a single model. For example, a model mapping the file + system could be created for a file manager. Many views could be + created to display various parts of the file system, but only one + copy need be kept in memory. - - Simple Example @@ -31,7 +46,9 @@ linkend="GtkTreeView">GtkTreeView widget in context of the other widgets. It simply creates a simple model and view, and puts them together. Note that the model is never populated with - data — that is left as an exercise for the reader. + data — that is left as an exercise for the reader. More + information can be found on this in the GtkTreeModel section. - diff --git a/gtk/gtkliststore.c b/gtk/gtkliststore.c index 50e17a7261..3223382f80 100644 --- a/gtk/gtkliststore.c +++ b/gtk/gtkliststore.c @@ -572,15 +572,10 @@ gtk_list_store_iter_parent (GtkTreeModel *tree_model, return FALSE; } -/* Public accessors */ -/* This is a somewhat inelegant function that does a lot of list - * manipulations on it's own. - */ - /** * gtk_list_store_set_value: - * @store: a #GtkListStore - * @iter: iterator for the row you're modifying + * @list_store: A #GtkListStore + * @iter: A valid #GtkTreeIter for the row being modified * @column: column number to modify * @value: new value for the cell * @@ -688,11 +683,11 @@ gtk_list_store_set_value (GtkListStore *list_store, /** * gtk_list_store_set_valist: - * @list_store: a #GtkListStore - * @iter: row to set data for + * @list_store: A #GtkListStore + * @iter: A valid #GtkTreeIter for the row being modified * @var_args: va_list of column/value pairs * - * See gtk_list_store_set(); this version takes a va_list for + * See @gtk_list_store_set; this version takes a va_list for * use by language bindings. * **/ @@ -837,11 +832,10 @@ gtk_list_store_remove_silently (GtkListStore *list_store, /** * gtk_list_store_remove: - * @store: a #GtkListStore - * @iter: a row in @list_store + * @list_store: A #GtkListStore + * @iter: A valid #GtkTreeIter * - * Removes the given row from the list store, emitting the - * "deleted" signal on #GtkTreeModel. + * Removes the given row from the list store. After being removed, @iter is set to be the next valid row, or invalidated if it pointed to the last row inn @list_store * **/ void @@ -849,10 +843,12 @@ gtk_list_store_remove (GtkListStore *list_store, GtkTreeIter *iter) { GtkTreePath *path; + GSList *next; g_return_if_fail (GTK_IS_LIST_STORE (list_store)); g_return_if_fail (VALID_ITER (iter, list_store)); + next = G_SLIST (iter->user_data)->next; path = gtk_list_store_get_path (GTK_TREE_MODEL (list_store), iter); validate_list_store (list_store); @@ -864,6 +860,16 @@ gtk_list_store_remove (GtkListStore *list_store, list_store->stamp ++; gtk_tree_model_deleted (GTK_TREE_MODEL (list_store), path); gtk_tree_path_free (path); + + if (next) + { + iter->stamp = list_store->stamp; + iter->user_data = next; + } + else + { + iter->stamp = 0; + } } static void @@ -887,13 +893,15 @@ insert_after (GtkListStore *list_store, /** * gtk_list_store_insert: - * @store: a #GtkListStore - * @iter: iterator to initialize with the new row + * @list_store: A #GtkListStore + * @iter: An unset #GtkTreeIter to set to the new row * @position: position to insert the new row * - * Creates a new row at @position, initializing @iter to point to the - * new row, and emitting the "inserted" signal from the #GtkTreeModel - * interface. + * Creates a new row at @position. @iter will be changed to point to this new + * row. If @position is larger than the number of rows on the list, then the + * new row will be appended to the list. The row will be empty before this + * function is called. To fill in values, you need to call @gtk_list_store_set + * or @gtk_list_store_set_value. * **/ void @@ -941,13 +949,14 @@ gtk_list_store_insert (GtkListStore *list_store, /** * gtk_list_store_insert_before: - * @store: a #GtkListStore - * @iter: iterator to initialize with the new row - * @sibling: an existing row + * @list_store: A #GtkListStore + * @iter: An unset #GtkTreeIter to set to the new row + * @sibling: A valid #GtkTreeIter, or %NULL * - * Inserts a new row before @sibling, initializing @iter to point to - * the new row, and emitting the "inserted" signal from the - * #GtkTreeModel interface. + * Inserts a new row before @sibling. If @sibling is %NULL, then the row will be + * appended to the beginning of the list. @iter will be changed to point to + * this new row. The row will be empty before this function is called. To fill + * in values, you need to call @gtk_list_store_set or @gtk_list_store_set_value. * **/ void @@ -1028,13 +1037,14 @@ gtk_list_store_insert_before (GtkListStore *list_store, /** * gtk_list_store_insert_after: - * @store: a #GtkListStore - * @iter: iterator to initialize with the new row - * @sibling: an existing row + * @list_store: A #GtkListStore + * @iter: An unset #GtkTreeIter to set to the new row + * @sibling: A valid #GtkTreeIter, or %NULL * - * Inserts a new row after @sibling, initializing @iter to point to - * the new row, and emitting the "inserted" signal from the - * #GtkTreeModel interface. + * Inserts a new row after @sibling. If @sibling is %NULL, then the row will be + * prepended to the beginning of the list. @iter will be changed to point to + * this new row. The row will be empty after this function is called. To fill + * in values, you need to call @gtk_list_store_set or @gtk_list_store_set_value. * **/ void @@ -1080,12 +1090,12 @@ gtk_list_store_insert_after (GtkListStore *list_store, /** * gtk_list_store_prepend: - * @store: a #GtkListStore - * @iter: iterator to initialize with new row + * @list_store: A #GtkListStore + * @iter: An unset #GtkTreeIter to set to the prepend row * - * Prepends a row to @store, initializing @iter to point to the - * new row, and emitting the "inserted" signal on the #GtkTreeModel - * interface for the @store. + * Prepend a new row to @list_store. @iter will be changed to point to this new + * row. The row will be empty after this function is called. To fill in + * values, you need to call @gtk_list_store_set or @gtk_list_store_set_value. * **/ void @@ -1118,12 +1128,12 @@ gtk_list_store_prepend (GtkListStore *list_store, /** * gtk_list_store_append: - * @store: a #GtkListStore - * @iter: iterator to initialize with the new row + * @list_store: A #GtkListStore + * @iter: An unset #GtkTreeIter to set to the appended row * - * Appends a row to @store, initializing @iter to point to the - * new row, and emitting the "inserted" signal on the #GtkTreeModel - * interface for the @store. + * Appends a new row to @list_store. @iter will be changed to point to this new + * row. The row will be empty after this function is called. To fill in + * values, you need to call @gtk_list_store_set or @gtk_list_store_set_value. * **/ void diff --git a/gtk/gtkliststore.h b/gtk/gtkliststore.h index 6549087c89..10364ac2b1 100644 --- a/gtk/gtkliststore.h +++ b/gtk/gtkliststore.h @@ -67,7 +67,7 @@ GtkListStore *gtk_list_store_new (gint n_columns, ...); GtkListStore *gtk_list_store_newv (gint n_columns, GType *types); -void gtk_list_store_set_value (GtkListStore *store, +void gtk_list_store_set_value (GtkListStore *list_store, GtkTreeIter *iter, gint column, GValue *value); @@ -77,22 +77,22 @@ void gtk_list_store_set (GtkListStore *list_store, void gtk_list_store_set_valist (GtkListStore *list_store, GtkTreeIter *iter, va_list var_args); -void gtk_list_store_remove (GtkListStore *store, +void gtk_list_store_remove (GtkListStore *list_store, GtkTreeIter *iter); -void gtk_list_store_insert (GtkListStore *store, +void gtk_list_store_insert (GtkListStore *list_store, GtkTreeIter *iter, gint position); -void gtk_list_store_insert_before (GtkListStore *store, +void gtk_list_store_insert_before (GtkListStore *list_store, GtkTreeIter *iter, GtkTreeIter *sibling); -void gtk_list_store_insert_after (GtkListStore *store, +void gtk_list_store_insert_after (GtkListStore *list_store, GtkTreeIter *iter, GtkTreeIter *sibling); -void gtk_list_store_prepend (GtkListStore *store, +void gtk_list_store_prepend (GtkListStore *list_store, GtkTreeIter *iter); -void gtk_list_store_append (GtkListStore *store, +void gtk_list_store_append (GtkListStore *list_store, GtkTreeIter *iter); -void gtk_list_store_clear (GtkListStore *store); +void gtk_list_store_clear (GtkListStore *list_store); #ifdef __cplusplus diff --git a/gtk/gtktreeselection.c b/gtk/gtktreeselection.c index b09d007813..3105c86469 100644 --- a/gtk/gtktreeselection.c +++ b/gtk/gtktreeselection.c @@ -276,7 +276,15 @@ gtk_tree_selection_get_user_data (GtkTreeSelection *selection) return selection->user_data; } -GtkTreeView* +/** + * gtk_tree_selection_get_tree_view: + * @selection: A #GtkTreeSelection + * + * Returns the tree view associated with @selection. + * + * Return value: A #GtkTreeView + **/ +GtkTreeView * gtk_tree_selection_get_tree_view (GtkTreeSelection *selection) { g_return_val_if_fail (GTK_IS_TREE_SELECTION (selection), NULL); diff --git a/gtk/gtktreestore.c b/gtk/gtktreestore.c index 6d17ba3215..d6a1c21336 100644 --- a/gtk/gtktreestore.c +++ b/gtk/gtktreestore.c @@ -244,7 +244,11 @@ static void gtk_tree_store_init (GtkTreeStore *tree_store) { tree_store->root = g_node_new (NULL); - tree_store->stamp = g_random_int (); + do + { + tree_store->stamp = g_random_int (); + } + while (tree_store->stamp != 0); tree_store->sort_list = NULL; tree_store->sort_column_id = -2; } @@ -684,10 +688,18 @@ gtk_tree_store_iter_parent (GtkTreeModel *tree_model, return FALSE; } -/* - * This is a somewhat inelegant function that does a lot of list - * manipulations on it's own. - */ +/** + * gtk_tree_store_set_value: + * @tree_store: a #GtkTreeStore + * @iter: A valid #GtkTreeIter for the row being modified + * @column: column number to modify + * @value: new value for the cell + * + * Sets the data in the cell specified by @iter and @column. + * The type of @value must be convertible to the type of the + * column. + * + **/ void gtk_tree_store_set_value (GtkTreeStore *tree_store, GtkTreeIter *iter, @@ -786,11 +798,11 @@ gtk_tree_store_set_value (GtkTreeStore *tree_store, /** * gtk_tree_store_set_valist: - * @tree_store: a #GtkTreeStore - * @iter: row to set data for + * @tree_store: A #GtkTreeStore + * @iter: A valid #GtkTreeIter for the row being modified * @var_args: va_list of column/value pairs * - * See gtk_tree_store_set(); this version takes a va_list for + * See @gtk_tree_store_set; this version takes a va_list for * use by language bindings. * **/ @@ -844,8 +856,8 @@ gtk_tree_store_set_valist (GtkTreeStore *tree_store, /** * gtk_tree_store_set: - * @tree_store: a #GtkTreeStore - * @iter: row iterator + * @tree_store: A #GtkTreeStore + * @iter: A valid #GtkTreeIter for the row being modified * @Varargs: pairs of column number and value, terminated with -1 * * Sets the value of one or more cells in the row referenced by @iter. @@ -870,60 +882,85 @@ gtk_tree_store_set (GtkTreeStore *tree_store, va_end (var_args); } +/** + * gtk_tree_store_remove: + * @tree_store: A #GtkTreeStore + * @iter: A valid #GtkTreeIter + * + * Removes @iter from @tree_store. After being removed, @iter is set to the + * next valid row at that level, or invalidated if it previeously pointed to the last one. + **/ void -gtk_tree_store_remove (GtkTreeStore *model, +gtk_tree_store_remove (GtkTreeStore *tree_store, GtkTreeIter *iter) { GtkTreePath *path; GtkTreeIter new_iter = {0,}; GNode *parent; + GNode *next_node; - g_return_if_fail (GTK_IS_TREE_STORE (model)); - g_return_if_fail (VALID_ITER (iter, model)); + g_return_if_fail (GTK_IS_TREE_STORE (tree_store)); + g_return_if_fail (VALID_ITER (iter, tree_store)); parent = G_NODE (iter->user_data)->parent; g_assert (parent != NULL); + next_node = G_NODE (iter->user_data); if (G_NODE (iter->user_data)->data) _gtk_tree_data_list_free ((GtkTreeDataList *) G_NODE (iter->user_data)->data, - model->column_headers); + tree_store->column_headers); - path = gtk_tree_store_get_path (GTK_TREE_MODEL (model), iter); + path = gtk_tree_store_get_path (GTK_TREE_MODEL (tree_store), iter); g_node_destroy (G_NODE (iter->user_data)); - model->stamp++; - gtk_tree_model_deleted (GTK_TREE_MODEL (model), path); + tree_store->stamp++; + gtk_tree_model_deleted (GTK_TREE_MODEL (tree_store), path); - if (parent != G_NODE (model->root)) + if (parent != G_NODE (tree_store->root)) { /* child_toggled */ if (parent->children == NULL) { gtk_tree_path_up (path); - new_iter.stamp = model->stamp; + new_iter.stamp = tree_store->stamp; new_iter.user_data = parent; - gtk_tree_model_has_child_toggled (GTK_TREE_MODEL (model), path, &new_iter); - } - - /* revalidate iter */ - while (parent != G_NODE (model->root)) - { - if (parent->next != NULL) - { - iter->stamp = model->stamp; - iter->user_data = parent->next; - break; - } - parent = parent->parent; + gtk_tree_model_has_child_toggled (GTK_TREE_MODEL (tree_store), path, &new_iter); } } gtk_tree_path_free (path); + + /* revalidate iter */ + if (next_node != NULL) + { + iter->stamp = tree_store->stamp; + iter->user_data = next_node; + } + else + { + iter->stamp = 0; + } } +/** + * gtk_tree_store_insert: + * @list_store: A #GtkListStore + * @iter: An unset #GtkTreeIter to set to the new row + * @parent: A valid #GtkTreeIter, or %NULL + * @position: position to insert the new row + * + * Creates a new row at @position. If parent is non-NULL, then the row will be + * made a child of @parent. Otherwise, the row will be created at the toplevel. + * If @position is larger than the number of rows at that level, then the new + * row will be inserted to the end of the list. @iter will be changed to point + * to this new row. The row will be empty before this function is called. To + * fill in values, you need to call @gtk_list_store_set or + * @gtk_list_store_set_value. + * + **/ void -gtk_tree_store_insert (GtkTreeStore *model, +gtk_tree_store_insert (GtkTreeStore *tree_store, GtkTreeIter *iter, GtkTreeIter *parent, gint position) @@ -931,29 +968,47 @@ gtk_tree_store_insert (GtkTreeStore *model, GtkTreePath *path; GNode *parent_node; - g_return_if_fail (GTK_IS_TREE_STORE (model)); + g_return_if_fail (GTK_IS_TREE_STORE (tree_store)); if (parent) - g_return_if_fail (VALID_ITER (parent, model)); + g_return_if_fail (VALID_ITER (parent, tree_store)); if (parent) parent_node = parent->user_data; else - parent_node = model->root; + parent_node = tree_store->root; - iter->stamp = model->stamp; + iter->stamp = tree_store->stamp; iter->user_data = g_node_new (NULL); g_node_insert (parent_node, position, G_NODE (iter->user_data)); - path = gtk_tree_store_get_path (GTK_TREE_MODEL (model), iter); - gtk_tree_model_inserted (GTK_TREE_MODEL (model), path, iter); + path = gtk_tree_store_get_path (GTK_TREE_MODEL (tree_store), iter); + gtk_tree_model_inserted (GTK_TREE_MODEL (tree_store), path, iter); gtk_tree_path_free (path); - validate_tree ((GtkTreeStore*)model); + validate_tree ((GtkTreeStore*)tree_store); } +/** + * gtk_tree_store_insert_before: + * @tree_store: A #GtkTreeStore + * @iter: An unset #GtkTreeIter to set to the new row + * parent: A valid #GtkTreeIter, or %NULL + * @sibling: A valid #GtkTreeIter, or %NULL + * + * Inserts a new row before @sibling. If @sibling is %NULL, then the row will + * be appended to the beginning of the @parent 's children. If @parent and + * @sibling are %NULL, then the row will be appended to the toplevel. If both + * @sibling and @parent are set, then @parent must be the parent of @sibling. + * When @sibling is set, @parent is optional. + * + * @iter will be changed to point to this new row. The row will be empty after + * this function is called. To fill in values, you need to call + * @gtk_tree_store_set or @gtk_tree_store_set_value. + * + **/ void -gtk_tree_store_insert_before (GtkTreeStore *model, +gtk_tree_store_insert_before (GtkTreeStore *tree_store, GtkTreeIter *iter, GtkTreeIter *parent, GtkTreeIter *sibling) @@ -962,17 +1017,17 @@ gtk_tree_store_insert_before (GtkTreeStore *model, GNode *parent_node = NULL; GNode *new_node; - g_return_if_fail (GTK_IS_TREE_STORE (model)); + g_return_if_fail (GTK_IS_TREE_STORE (tree_store)); g_return_if_fail (iter != NULL); if (parent != NULL) - g_return_if_fail (VALID_ITER (parent, model)); + g_return_if_fail (VALID_ITER (parent, tree_store)); if (sibling != NULL) - g_return_if_fail (VALID_ITER (sibling, model)); + g_return_if_fail (VALID_ITER (sibling, tree_store)); new_node = g_node_new (NULL); if (parent == NULL && sibling == NULL) - parent_node = model->root; + parent_node = tree_store->root; else if (parent == NULL) parent_node = G_NODE (sibling->user_data)->parent; else if (sibling == NULL) @@ -987,19 +1042,37 @@ gtk_tree_store_insert_before (GtkTreeStore *model, sibling ? G_NODE (sibling->user_data) : NULL, new_node); - iter->stamp = model->stamp; + iter->stamp = tree_store->stamp; iter->user_data = new_node; - path = gtk_tree_store_get_path (GTK_TREE_MODEL (model), iter); - gtk_tree_model_inserted (GTK_TREE_MODEL (model), path, iter); + path = gtk_tree_store_get_path (GTK_TREE_MODEL (tree_store), iter); + gtk_tree_model_inserted (GTK_TREE_MODEL (tree_store), path, iter); gtk_tree_path_free (path); - validate_tree ((GtkTreeStore*)model); + validate_tree ((GtkTreeStore*)tree_store); } +/** + * gtk_tree_store_insert_after: + * @tree_store: A #GtkTreeStore + * @iter: An unset #GtkTreeIter to set to the new row + * parent: A valid #GtkTreeIter, or %NULL + * @sibling: A valid #GtkTreeIter, or %NULL + * + * Inserts a new row after @sibling. If @sibling is %NULL, then the row will be + * prepended to the beginning of the @parent 's children. If @parent and + * @sibling are %NULL, then the row will be prepended to the toplevel. If both + * @sibling and @parent are set, then @parent must be the parent of @sibling. + * When @sibling is set, @parent is optional. + * + * @iter will be changed to point to this new row. The row will be empty after + * this function is called. To fill in values, you need to call + * @gtk_tree_store_set or @gtk_tree_store_set_value. + * + **/ void -gtk_tree_store_insert_after (GtkTreeStore *model, +gtk_tree_store_insert_after (GtkTreeStore *tree_store, GtkTreeIter *iter, GtkTreeIter *parent, GtkTreeIter *sibling) @@ -1008,17 +1081,17 @@ gtk_tree_store_insert_after (GtkTreeStore *model, GNode *parent_node; GNode *new_node; - g_return_if_fail (GTK_IS_TREE_STORE (model)); + g_return_if_fail (GTK_IS_TREE_STORE (tree_store)); g_return_if_fail (iter != NULL); if (parent != NULL) - g_return_if_fail (VALID_ITER (parent, model)); + g_return_if_fail (VALID_ITER (parent, tree_store)); if (sibling != NULL) - g_return_if_fail (VALID_ITER (sibling, model)); + g_return_if_fail (VALID_ITER (sibling, tree_store)); new_node = g_node_new (NULL); if (parent == NULL && sibling == NULL) - parent_node = model->root; + parent_node = tree_store->root; else if (parent == NULL) parent_node = G_NODE (sibling->user_data)->parent; else if (sibling == NULL) @@ -1035,31 +1108,43 @@ gtk_tree_store_insert_after (GtkTreeStore *model, sibling ? G_NODE (sibling->user_data) : NULL, new_node); - iter->stamp = model->stamp; + iter->stamp = tree_store->stamp; iter->user_data = new_node; - path = gtk_tree_store_get_path (GTK_TREE_MODEL (model), iter); - gtk_tree_model_inserted (GTK_TREE_MODEL (model), path, iter); + path = gtk_tree_store_get_path (GTK_TREE_MODEL (tree_store), iter); + gtk_tree_model_inserted (GTK_TREE_MODEL (tree_store), path, iter); gtk_tree_path_free (path); - validate_tree ((GtkTreeStore*)model); + validate_tree ((GtkTreeStore*)tree_store); } +/** + * gtk_tree_store_prepend: + * @tree_store: A #GtkTreeStore + * @iter: An unset #GtkTreeIter to set to the prepended row + * @parent: A valid #GtkTreeIter, or %NULL + * + * Prepends a new row to @tree_store. If @parent is non-NULL, then it will prepend + * the new row before the last child of @parent, otherwise it will prepend a row + * to the top level. @iter will be changed to point to this new row. The row + * will be empty after this function is called. To fill in values, you need to + * call @gtk_tree_store_set or @gtk_tree_store_set_value. + **/ void -gtk_tree_store_prepend (GtkTreeStore *model, +gtk_tree_store_prepend (GtkTreeStore *tree_store, GtkTreeIter *iter, GtkTreeIter *parent) { GNode *parent_node; - g_return_if_fail (GTK_IS_TREE_STORE (model)); + g_return_if_fail (GTK_IS_TREE_STORE (tree_store)); g_return_if_fail (iter != NULL); if (parent != NULL) - g_return_if_fail (VALID_ITER (parent, model)); + g_return_if_fail (VALID_ITER (parent, tree_store)); if (parent == NULL) - parent_node = model->root; + parent_node = tree_store->root; else parent_node = parent->user_data; @@ -1067,47 +1152,59 @@ gtk_tree_store_prepend (GtkTreeStore *model, { GtkTreePath *path; - iter->stamp = model->stamp; + iter->stamp = tree_store->stamp; iter->user_data = g_node_new (NULL); g_node_prepend (parent_node, iter->user_data); - if (parent_node != model->root) + if (parent_node != tree_store->root) { - path = gtk_tree_store_get_path (GTK_TREE_MODEL (model), parent); - gtk_tree_model_has_child_toggled (GTK_TREE_MODEL (model), path, parent); + path = gtk_tree_store_get_path (GTK_TREE_MODEL (tree_store), parent); + gtk_tree_model_has_child_toggled (GTK_TREE_MODEL (tree_store), path, parent); gtk_tree_path_append_index (path, 0); } else { - path = gtk_tree_store_get_path (GTK_TREE_MODEL (model), iter); + path = gtk_tree_store_get_path (GTK_TREE_MODEL (tree_store), iter); } - gtk_tree_model_inserted (GTK_TREE_MODEL (model), path, iter); + gtk_tree_model_inserted (GTK_TREE_MODEL (tree_store), path, iter); gtk_tree_path_free (path); } else { - gtk_tree_store_insert_after (model, iter, parent, NULL); + gtk_tree_store_insert_after (tree_store, iter, parent, NULL); } - validate_tree ((GtkTreeStore*)model); + validate_tree ((GtkTreeStore*)tree_store); } +/** + * gtk_tree_store_append: + * @tree_store: A #GtkTreeStore + * @iter: An unset #GtkTreeIter to set to the appended row + * @parent: A valid #GtkTreeIter, or %NULL + * + * Appends a new row to @tree_store. If @parent is non-NULL, then it will append the + * new row after the last child of @parent, otherwise it will append a row to + * the top level. @iter will be changed to point to this new row. The row will + * be empty after this function is called. To fill in values, you need to call + * @gtk_tree_store_set or @gtk_tree_store_set_value. + **/ void -gtk_tree_store_append (GtkTreeStore *model, +gtk_tree_store_append (GtkTreeStore *tree_store, GtkTreeIter *iter, GtkTreeIter *parent) { GNode *parent_node; - g_return_if_fail (GTK_IS_TREE_STORE (model)); + g_return_if_fail (GTK_IS_TREE_STORE (tree_store)); g_return_if_fail (iter != NULL); if (parent != NULL) - g_return_if_fail (VALID_ITER (parent, model)); + g_return_if_fail (VALID_ITER (parent, tree_store)); if (parent == NULL) - parent_node = model->root; + parent_node = tree_store->root; else parent_node = parent->user_data; @@ -1115,58 +1212,85 @@ gtk_tree_store_append (GtkTreeStore *model, { GtkTreePath *path; - iter->stamp = model->stamp; + iter->stamp = tree_store->stamp; iter->user_data = g_node_new (NULL); g_node_append (parent_node, G_NODE (iter->user_data)); - if (parent_node != model->root) + if (parent_node != tree_store->root) { - path = gtk_tree_store_get_path (GTK_TREE_MODEL (model), parent); - gtk_tree_model_has_child_toggled (GTK_TREE_MODEL (model), path, parent); + path = gtk_tree_store_get_path (GTK_TREE_MODEL (tree_store), parent); + gtk_tree_model_has_child_toggled (GTK_TREE_MODEL (tree_store), path, parent); gtk_tree_path_append_index (path, 0); } else { - path = gtk_tree_store_get_path (GTK_TREE_MODEL (model), iter); + path = gtk_tree_store_get_path (GTK_TREE_MODEL (tree_store), iter); } - gtk_tree_model_inserted (GTK_TREE_MODEL (model), path, iter); + gtk_tree_model_inserted (GTK_TREE_MODEL (tree_store), path, iter); gtk_tree_path_free (path); } else { - gtk_tree_store_insert_before (model, iter, parent, NULL); + gtk_tree_store_insert_before (tree_store, iter, parent, NULL); } - validate_tree ((GtkTreeStore*)model); + validate_tree ((GtkTreeStore*)tree_store); } +/** + * gtk_tree_store_is_ancestor: + * @tree_store: A #GtkTreeStore + * @iter: A valid #GtkTreeIter + * @descendant: A valid #GtkTreeIter + * + * Returns %TRUE if @iter is an ancestor of @descendant. That is, @iter is the + * parent (or grandparent or great-grandparent) of @descendant. + * + * Return value: %TRUE, if @iter is an ancestor of @descendant + **/ gboolean -gtk_tree_store_is_ancestor (GtkTreeStore *model, +gtk_tree_store_is_ancestor (GtkTreeStore *tree_store, GtkTreeIter *iter, GtkTreeIter *descendant) { - g_return_val_if_fail (GTK_IS_TREE_STORE (model), FALSE); - g_return_val_if_fail (VALID_ITER (iter, model), FALSE); - g_return_val_if_fail (VALID_ITER (descendant, model), FALSE); + g_return_val_if_fail (GTK_IS_TREE_STORE (tree_store), FALSE); + g_return_val_if_fail (VALID_ITER (iter, tree_store), FALSE); + g_return_val_if_fail (VALID_ITER (descendant, tree_store), FALSE); return g_node_is_ancestor (G_NODE (iter->user_data), G_NODE (descendant->user_data)); } +/** + * gtk_tree_store_iter_depth: + * @tree_store: A #GtkTreeStore + * @iter: A valid #GtkTreeIter + * + * Returns the depth of @iter. This will be 0 for anything on the root level, 1 + * for anything down a level, etc. + * + * Return value: The depth of @iter + **/ gint -gtk_tree_store_iter_depth (GtkTreeStore *model, +gtk_tree_store_iter_depth (GtkTreeStore *tree_store, GtkTreeIter *iter) { - g_return_val_if_fail (GTK_IS_TREE_STORE (model), 0); - g_return_val_if_fail (VALID_ITER (iter, model), 0); + g_return_val_if_fail (GTK_IS_TREE_STORE (tree_store), 0); + g_return_val_if_fail (VALID_ITER (iter, tree_store), 0); return g_node_depth (G_NODE (iter->user_data)) - 1; } +/** + * gtk_tree_store_clear: + * @tree_store: @ #GtkTreeStore + * + * Removes all rows from @tree_store + **/ void gtk_tree_store_clear (GtkTreeStore *tree_store) {