_foreach vs _forall (RE: PROPOSAL: GTK_WIDGET_COMPOSITE_CHILDflag)

[Tim Janik <timj gtk org>]

On Wed, 26 Aug 1998, Tim Janik wrote:

> ok, i've started out on the actuall implementation of GTK_COMPOSITE_CHILD.
> thing is, various internal gtk calls depend on _foreach to iterate over
> all children. it is rarely used to walk only non composite children, examples
> for this are show_all and hide_all. so the point remains that we need
> to be able to walk over *all* existing widgets in the widget tree.
> since incorporating all composite children into the _foreach calls would also
> change Gtk's current API behaviour, which some programs may rely on, it is
> probably not the best way to include all children into the existing _foreach
> call.
> also, including composite children would cause a bunch of the containers
> to implement show_all and hide_all functions, to leave the composites out,
> since they care for the composites anyways.
> rather than implementing two new function calls (hide_all and show_all) for
> all the containers that have composite children, it seems more appropriate
> to let the GtkWidgetClass methods show_all and hide_all vanish, and introduce
> a new class method _forall for containers, that will be used inside
> of gtk to iterate over the whole tree, i.e. normal children plus composites
> (e.g. needed for propagation of styles or states).
> i'm not sure _forall is the best name, other possibilities would be
> _foreach_internal or somesuch, but that can still be changed...

i've continued to work on this (got distracted by some personall issues),
and the result is this:

 - the GtkContainer::foreach signal will vanish (afaik, there is no code in
   existance that actually connects to this signal, and if there would be,
   connecting to ::foreach would be questionable behaviour anways).
 - there's a new class method GtkContainerClass.forall() that takes care to
   iterate over a containers children, optionally including internal widgets.
     void (* forall)               (GtkContainer    *container,
                                    gboolean         include_internals,
                                    GtkCallback      callback,
                                    gpointer         callbabck_data);
 - the old gtk_container_foreach() (and thus gtk_container_children())
   behaviours remain, that is, they iterate over all children of a container
   that got added via gtk_copntainer_add() or similar methods (i.e. for the
   notebook, _foreach will iterate over the pages only).
 - there is a new function call
   void    gtk_container_forall               (GtkContainer *container,
                                               GtkCallback   callback,
                                               gpointer      callback_data);
   that iterates over *all* children of a container, including internal ones
   (e.g. a notebook's menu/tab labels, clist buttons, etc...). this function
   is classified as "internal gtk usage", since its prototype may change
   in the future, and external gtk programs shouldn't freak around with
   internal children (GUI builders being an occasional exception).

this solution gets rid of the problem of internal gtk code not being able
to acces certain children of distinct containers (e.g. for state propagation
or reparentation) and the confusion of application programmers that
occasionally encounter internal children with gtk_container_foreach() or
gtk_container_children().
also, through using gtk_container_foreach() calls, we can get rid of the
GtkWidgetClass.show_all and GtkWidgetClass.hide_all class methods.
the downside is that all container widgets outside of the gtk distribution
need to be adapted to implement _forall() instead of _foreach(), but the
actuall adaptions of the existing _foreach functions is usually a very
minor issue.

PS: i'll take care of adapting gnome widgets myself.

> 
> ---
> ciaoTJ
> 

---
ciaoTJ