From c43e4377481bb7f04745438fa8217943c2e2ea3b Mon Sep 17 00:00:00 2001 From: Owen Taylor Date: Fri, 5 Mar 2004 16:40:12 +0000 Subject: Improve the docs (reported by Vitaly Tishkov, #74362) Add some comments to Fri Mar 5 11:17:35 2004 Owen Taylor * gtk/gtktreemodel.c (gtk_tree_row_reference_new_proxy): Improve the docs (reported by Vitaly Tishkov, #74362) Add some comments to the code about the row reference handling that are hopefully not entirely wrong. --- ChangeLog | 8 ++++++++ ChangeLog.pre-2-10 | 8 ++++++++ ChangeLog.pre-2-4 | 8 ++++++++ ChangeLog.pre-2-6 | 8 ++++++++ ChangeLog.pre-2-8 | 8 ++++++++ gtk/gtktreemodel.c | 29 ++++++++++++++++++++++++++--- 6 files changed, 66 insertions(+), 3 deletions(-) diff --git a/ChangeLog b/ChangeLog index bebe44f12..b3f519fb1 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,11 @@ +Fri Mar 5 11:17:35 2004 Owen Taylor + + * gtk/gtktreemodel.c (gtk_tree_row_reference_new_proxy): + Improve the docs (reported by Vitaly Tishkov, + #74362) Add some comments to the code about the + row reference handling that are hopefully not entirely + wrong. + 2004-03-05 Michael Natterer * gtk/gtkfilechooserdefault.c (gtk_file_chooser_default_show_all): diff --git a/ChangeLog.pre-2-10 b/ChangeLog.pre-2-10 index bebe44f12..b3f519fb1 100644 --- a/ChangeLog.pre-2-10 +++ b/ChangeLog.pre-2-10 @@ -1,3 +1,11 @@ +Fri Mar 5 11:17:35 2004 Owen Taylor + + * gtk/gtktreemodel.c (gtk_tree_row_reference_new_proxy): + Improve the docs (reported by Vitaly Tishkov, + #74362) Add some comments to the code about the + row reference handling that are hopefully not entirely + wrong. + 2004-03-05 Michael Natterer * gtk/gtkfilechooserdefault.c (gtk_file_chooser_default_show_all): diff --git a/ChangeLog.pre-2-4 b/ChangeLog.pre-2-4 index bebe44f12..b3f519fb1 100644 --- a/ChangeLog.pre-2-4 +++ b/ChangeLog.pre-2-4 @@ -1,3 +1,11 @@ +Fri Mar 5 11:17:35 2004 Owen Taylor + + * gtk/gtktreemodel.c (gtk_tree_row_reference_new_proxy): + Improve the docs (reported by Vitaly Tishkov, + #74362) Add some comments to the code about the + row reference handling that are hopefully not entirely + wrong. + 2004-03-05 Michael Natterer * gtk/gtkfilechooserdefault.c (gtk_file_chooser_default_show_all): diff --git a/ChangeLog.pre-2-6 b/ChangeLog.pre-2-6 index bebe44f12..b3f519fb1 100644 --- a/ChangeLog.pre-2-6 +++ b/ChangeLog.pre-2-6 @@ -1,3 +1,11 @@ +Fri Mar 5 11:17:35 2004 Owen Taylor + + * gtk/gtktreemodel.c (gtk_tree_row_reference_new_proxy): + Improve the docs (reported by Vitaly Tishkov, + #74362) Add some comments to the code about the + row reference handling that are hopefully not entirely + wrong. + 2004-03-05 Michael Natterer * gtk/gtkfilechooserdefault.c (gtk_file_chooser_default_show_all): diff --git a/ChangeLog.pre-2-8 b/ChangeLog.pre-2-8 index bebe44f12..b3f519fb1 100644 --- a/ChangeLog.pre-2-8 +++ b/ChangeLog.pre-2-8 @@ -1,3 +1,11 @@ +Fri Mar 5 11:17:35 2004 Owen Taylor + + * gtk/gtktreemodel.c (gtk_tree_row_reference_new_proxy): + Improve the docs (reported by Vitaly Tishkov, + #74362) Add some comments to the code about the + row reference handling that are hopefully not entirely + wrong. + 2004-03-05 Michael Natterer * gtk/gtkfilechooserdefault.c (gtk_file_chooser_default_show_all): diff --git a/gtk/gtktreemodel.c b/gtk/gtktreemodel.c index c9be46409..e3f957ec3 100644 --- a/gtk/gtktreemodel.c +++ b/gtk/gtktreemodel.c @@ -154,6 +154,18 @@ gtk_tree_model_base_init (gpointer g_class) GTK_TYPE_TREE_PATH, GTK_TYPE_TREE_ITER); + /* We need to get notification about structure changes + * to update row references., so instead of using the + * standard g_signal_new() with an offset into our interface + * structure, we use a customs closures for the class + * closures (default handlers) that first update row references + * and then calls the function from the interface structure. + * + * The reason we don't simply update the row references from + * the wrapper functions (gtk_tree_model_row_inserted(), etc.) + * is to keep proper ordering with respect to signal handlers + * connected normally and after. + */ closure = g_closure_new_simple (sizeof (GClosure), NULL); g_closure_set_marshal (closure, row_inserted_marshal); tree_model_signals[ROW_INSERTED] = @@ -1756,6 +1768,10 @@ gtk_tree_row_reference_new (GtkTreeModel *model, g_return_val_if_fail (GTK_IS_TREE_MODEL (model), NULL); g_return_val_if_fail (path != NULL, NULL); + /* We use the model itself as the proxy object; and call + * gtk_tree_row_reference_inserted(), etc, in the + * class closure (default handler) marshalers for the signal. + */ return gtk_tree_row_reference_new_proxy (G_OBJECT (model), model, path); } @@ -1772,8 +1788,15 @@ gtk_tree_row_reference_new (GtkTreeModel *model, * gtk_tree_row_reference_new(), it does not listen to the model for changes. * The creator of the row reference must do this explicitly using * gtk_tree_row_reference_inserted(), gtk_tree_row_reference_deleted(), - * gtk_tree_row_reference_reordered(). This must be called once per signal per - * proxy. + * gtk_tree_row_reference_reordered(). + * + * These functions must be called exactly once per proxy when the + * corresponding signal on the model is emitted. This single call + * updates all row references for that proxy. Since built-in GTK+ + * objects like #GtkTreeView already use this mechanism internally, + * using them as the proxy object will produce unpredictable results. + * Further more, passing the same object as @model and @proxy + * doesn't work for reasons of internal implementation. * * This type of row reference is primarily meant by structures that need to * carefully monitor exactly when a row_reference updates itself, and is not @@ -1812,7 +1835,7 @@ gtk_tree_row_reference_new_proxy (GObject *proxy, parent_iter = iter; } - /* Make ther row reference */ + /* Make the row reference */ reference = g_new (GtkTreeRowReference, 1); g_object_ref (proxy); -- cgit v1.2.1