Iterating Over Children

Containers have a forall method for iterating over their children; GtkContainer's default methods use forall, since they know nothing about the data members in subclasses' instance structs. The forall method invokes a callback on each child, with the provided callback data as the second argument. Obviously it's going to be trivial for GtkBin:

static void
gtk_bin_forall (GtkContainer *container,
                gboolean      include_internals,
                GtkCallback   callback,
                gpointer      callback_data)
{
  GtkBin *bin;

  g_return_if_fail (container != NULL);
  g_return_if_fail (GTK_IS_BIN (container));
  g_return_if_fail (callback != NULL);

  bin = GTK_BIN (container);

  if (bin->child)
    (* callback) (bin->child, callback_data);
}
    

You may notice that GtkBin ignores the include_internals argument. Some containers have "incidental" child widgets in addition to the user-provided children they are primarily designed to hold. For example, GtkNotebook has a widget labelling each of its tabs; GtkCList uses buttons to title each column in the list. These internal widgets must be included in the iteration in many cases; for example, when drawing each child in a container, or destroying each child in a container. However, some operations only operate on the "primary" children, such as the pages in GtkNotebook. The include_internals flag indicates whether to invoke the callback on incidental widgets.

Convenience functions are provided that invoke the forall method; these are used by application authors as well as GtkContainer internals. gtk_container_foreach() iterates over only the primary children of a container, while gtk_container_forall() iterates over all the children.