[gtkmm] Gtk::Container: Update the documentation of forall_vfunc()



commit d6b0cd832231279da31083e9b4e0356aa9cf5c50
Author: Kjell Ahlstedt <kjellahlstedt gmail com>
Date:   Sun Apr 30 09:31:31 2017 +0200

    Gtk::Container: Update the documentation of forall_vfunc()
    
    after the "include_internal" parameter was removed.

 gtk/src/container.ccg |    5 ++++-
 gtk/src/container.hg  |   12 ++++++------
 2 files changed, 10 insertions(+), 7 deletions(-)
---
diff --git a/gtk/src/container.ccg b/gtk/src/container.ccg
index b3ea4fe..a5c45fa 100644
--- a/gtk/src/container.ccg
+++ b/gtk/src/container.ccg
@@ -188,7 +188,7 @@ void Container_Class::forall_vfunc_callback(GtkContainer* self,
       {
         if (callback == &container_foreach_callback)
         {
-          // This call comes from Container::forall() or Container::foreach(),
+          // This call comes from Container::foreach(),
           // or is a recursive call. Don't create another slot layer.
           // callback_data is a pointer to a Container::ForeachSlot.
           const auto slot = static_cast<Container::ForeachSlot*>(callback_data);
@@ -225,12 +225,15 @@ void Container_Class::forall_vfunc_callback(GtkContainer* self,
 
 void Container::foreach(const Container::ForeachSlot& slot)
 {
+  // gtk_container_foreach() calls the virtual function GtkContainerClass.forall,
+  // and thus Container_Class::forall_vfunc_callback().
   ForeachSlot slot_copy (slot);
   gtk_container_foreach(gobj(), &container_foreach_callback, &slot_copy);
 }
 
 void Container::forall(const Container::ForeachSlot& slot)
 {
+  // gtk_container_forall() does not call Container_Class::forall_vfunc_callback().
   ForeachSlot slot_copy (slot);
   gtk_container_forall(gobj(), &container_foreach_callback, &slot_copy);
 }
diff --git a/gtk/src/container.hg b/gtk/src/container.hg
index effcd99..974ec8e 100644
--- a/gtk/src/container.hg
+++ b/gtk/src/container.hg
@@ -171,16 +171,16 @@ protected:
    */
   _WRAP_VFUNC(GType child_type() const, child_type)
 
-  /** Invokes a callback on all children of the container.
+  /** Invokes a callback on all non-internal children of the container.
    *
-   * The callback may optionally be invoked also on children that are considered
-   * "internal" (implementation details of the container). "Internal" children
-   * generally  weren't added by the user of the container, but were added by the
-   * container implementation itself.
+   * "Internal" children generally weren't added by the user of the container,
+   * but were added by the container implementation itself.
    *
+   * %forall_vfunc() resembles foreach(): They don't invoke the callback for
+   * internal children. forall() invokes it for all kinds of children.
    * Most applications should use foreach(), rather than forall().
    *
-   * @param slot A slot to call for each child.
+   * @param slot A slot to call for each non-internal child.
    */
   _WRAP_VFUNC(void forall(const ForeachSlot& slot{callback}), forall,
     custom_vfunc_callback, slot_name slot, slot_callback container_foreach_callback, no_slot_copy)


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]