From 6d218084c3c6cfc134e5b99dddbc1d0c88bff0fc Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Mon, 31 Jan 2011 18:49:20 -0500 Subject: [PATCH] Clarify models vs callbacks in entry completion docs See https://bugzilla.gnome.org/show_bug.cgi?id=641073 --- gtk/gtkentrycompletion.c | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/gtk/gtkentrycompletion.c b/gtk/gtkentrycompletion.c index 763b670992..b770fa973c 100644 --- a/gtk/gtkentrycompletion.c +++ b/gtk/gtkentrycompletion.c @@ -49,6 +49,19 @@ * "actions" in the popup window. Their appearance is similar to menuitems, * to differentiate them clearly from completion strings. When an action is * selected, the #GtkEntryCompletion::action-activated signal is emitted. + * + * GtkEntryCompletion uses a #GtkTreeModelFilter model to represent the + * subset of the entire model that is currently matching. While the + * GtkEntryCompletion signals #GtkEntryCompletion::match-selected and + * #GtkEntryCompletion::cursor-on-match take the original model and an + * iter pointing to that model as arguments, other callbacks and signals + * (such as #GtkCellLayoutDataFuncs or #GtkCellArea::apply-attributes) + * will generally take the filter model as argument. As long as you are + * only calling gtk_tree_model_get(), this will make no difference to + * you. If for some reason, you need the original model, use + * gtk_tree_model_filter_get_model(). Don't forget to use + * gtk_tree_model_filter_convert_iter_to_child_iter() to obtain a + * matching iter. */ #include "config.h" @@ -235,6 +248,9 @@ gtk_entry_completion_class_init (GtkEntryCompletionClass *klass) * entry with the contents of the text column in the row * pointed to by @iter. * + * Note that @model is the model that was passed to + * gtk_entry_completion_set_model(). + * * Return value: %TRUE if the signal has been handled * * Since: 2.4 @@ -261,6 +277,9 @@ gtk_entry_completion_class_init (GtkEntryCompletionClass *klass) * of the entry with the contents of the text column in the row * pointed to by @iter. * + * Note that @model is the model that was passed to + * gtk_entry_completion_set_model(). + * * Return value: %TRUE if the signal has been handled * * Since: 2.12