actor: Add destroy_all_children()

There are times when we don't want to remove all children and count of
the reference count to drop to 0 to ensure destruction; there are cases,
such as managed environments, where it's preferable to ensure that the
children of an actor get actually destroyed.

clutter/clutter-actor.c

@@ -10461,6 +10461,10 @@ clutter_actor_remove_child (ClutterActor *self,
  * This function releases the reference added by inserting a child actor
  * in the list of children of @self.
  *
+ * If the reference count of a child drops to zero, the child will be
+ * destroyed. If you want to ensure the destruction of all the children
+ * of @self, use clutter_actor_destroy_all_children().
+ *
  * Since: 1.10
  */
 void
@@ -10483,6 +10487,53 @@ clutter_actor_remove_all_children (ClutterActor *self)
   g_assert (self->priv->n_children == 0);
 }
 
+/**
+ * clutter_actor_destroy_all_children:
+ * @self: a #ClutterActor
+ *
+ * Destroys all children of @self.
+ *
+ * This function releases the reference added by inserting a child
+ * actor in the list of children of @self, and ensures that the
+ * #ClutterActor::destroy signal is emitted on each child of the
+ * actor.
+ *
+ * By default, #ClutterActor will emit the #ClutterActor::destroy signal
+ * when its reference count drops to 0; the default handler of the
+ * #ClutterActor::destroy signal will destroy all the children of an
+ * actor. This function ensures that all children are destroyed, instead
+ * of just removed from @self, unlike clutter_actor_remove_all_children()
+ * which will merely release the reference and remove each child.
+ *
+ * Unless you acquired an additional reference on each child of @self
+ * prior to calling clutter_actor_remove_all_children() and want to reuse
+ * the actors, you should use clutter_actor_destroy_all_children() in
+ * order to make sure that children are destroyed and signal handlers
+ * are disconnected even in cases where circular references prevent this
+ * from automatically happening through reference counting alone.
+ *
+ * Since: 1.10
+ */
+void
+clutter_actor_destroy_all_children (ClutterActor *self)
+{
+  ClutterActorIter iter;
+
+  g_return_if_fail (CLUTTER_IS_ACTOR (self));
+
+  if (self->priv->n_children == 0)
+    return;
+
+  clutter_actor_iter_init (&iter, self);
+  while (clutter_actor_iter_next (&iter, NULL))
+    clutter_actor_iter_destroy (&iter);
+
+  /* sanity check */
+  g_assert (self->priv->first_child == NULL);
+  g_assert (self->priv->last_child == NULL);
+  g_assert (self->priv->n_children == 0);
+}
+
 typedef struct _InsertBetweenData {
   ClutterActor *prev_sibling;
   ClutterActor *next_sibling;

clutter/clutter-actor.h

@@ -493,6 +493,7 @@ void                            clutter_actor_replace_child
 void                            clutter_actor_remove_child                      (ClutterActor               *self,
                                                                                  ClutterActor               *child);
 void                            clutter_actor_remove_all_children               (ClutterActor               *self);
+void                            clutter_actor_destroy_all_children              (ClutterActor               *self);
 GList *                         clutter_actor_get_children                      (ClutterActor               *self);
 gint                            clutter_actor_get_n_children                    (ClutterActor               *self);
 ClutterActor *                  clutter_actor_get_child_at_index                (ClutterActor               *self,

clutter/clutter.symbols

@@ -70,6 +70,7 @@ clutter_actor_continue_paint
 clutter_actor_create_pango_context
 clutter_actor_create_pango_layout
 clutter_actor_destroy
+clutter_actor_destroy_all_children
 clutter_actor_detach_animation
 clutter_actor_event
 clutter_actor_get_abs_allocation_vertices

doc/reference/clutter/clutter-sections.txt

@@ -388,8 +388,9 @@ clutter_actor_insert_child_above
 clutter_actor_insert_child_at_index
 clutter_actor_insert_child_below
 clutter_actor_replace_child
-clutter_actor_remove_all_children
 clutter_actor_remove_child
+clutter_actor_remove_all_children
+clutter_actor_destroy_all_children
 clutter_actor_get_first_child
 clutter_actor_get_next_sibling
 clutter_actor_get_previous_sibling
@@ -408,6 +409,7 @@ clutter_actor_iter_init
 clutter_actor_iter_next
 clutter_actor_iter_prev
 clutter_actor_iter_remove
+clutter_actor_iter_destroy
 
 <SUBSECTION>
 clutter_actor_push_internal