[gtk+] Clarify models vs callbacks in entry completion docs

[Matthias Clasen <matthiasc src gnome org>]

commit 6d218084c3c6cfc134e5b99dddbc1d0c88bff0fc
Author: Matthias Clasen <mclasen redhat com>
Date:   Mon Jan 31 18:49:20 2011 -0500

    Clarify models vs callbacks in entry completion docs
    
    See https://bugzilla.gnome.org/show_bug.cgi?id=641073

 gtk/gtkentrycompletion.c |   19 +++++++++++++++++++
 1 files changed, 19 insertions(+), 0 deletions(-)
---
diff --git a/gtk/gtkentrycompletion.c b/gtk/gtkentrycompletion.c
index 763b670..b770fa9 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