actor: Add remove_all_children()

A simple method for removing all children of an actor in one fell swoop.

clutter/clutter-actor.c

@@ -9679,7 +9679,8 @@ clutter_actor_add_child_internal (ClutterActor             *self,
  * This function will take into consideration the #ClutterActor:depth
  * of @child, and will keep the list of children sorted.
  *
- * This function will emit the #ClutterContainer::actor-added signal.
+ * This function will emit the #ClutterContainer::actor-added signal
+ * on @self.
  *
  * Since: 1.10
  */
@@ -9714,7 +9715,8 @@ clutter_actor_add_child (ClutterActor *self,
  * This function will not take into consideration the #ClutterActor:depth
  * of @child.
  *
- * This function will emit the #ClutterContainer::actor-added signal.
+ * This function will emit the #ClutterContainer::actor-added signal
+ * on @self.
  *
  * Since: 1.10
  */
@@ -9751,7 +9753,8 @@ clutter_actor_insert_child_at_index (ClutterActor *self,
  * This function will not take into consideration the #ClutterActor:depth
  * of @child.
  *
- * This function will emit the #ClutterContainer::actor-added signal.
+ * This function will emit the #ClutterContainer::actor-added signal
+ * on @self.
  *
  * Since: 1.10
  */
@@ -9792,7 +9795,8 @@ clutter_actor_insert_child_above (ClutterActor *self,
  * This function will not take into consideration the #ClutterActor:depth
  * of @child.
  *
- * This function will emit the #ClutterContainer::actor-added signal.
+ * This function will emit the #ClutterContainer::actor-added signal
+ * on @self.
  *
  * Since: 1.10
  */
@@ -10019,7 +10023,7 @@ clutter_actor_remove_child_internal (ClutterActor *self,
  * function.
  *
  * This function will emit the #ClutterContainer::actor-removed
- * signal.
+ * signal on @self.
  *
  * Since: 1.10
  */
@@ -10036,6 +10040,42 @@ clutter_actor_remove_child (ClutterActor *self,
   clutter_actor_remove_child_internal (self, child, TRUE, TRUE);
 }
 
+/**
+ * clutter_actor_remove_all_children:
+ * @self: a #ClutterActor
+ *
+ * Removes all children of @self.
+ *
+ * This function releases the reference added by inserting a child actor
+ * in the list of children of @self.
+ *
+ * Since: 1.10
+ */
+void
+clutter_actor_remove_all_children (ClutterActor *self)
+{
+  ClutterActor *iter;
+
+  g_return_if_fail (CLUTTER_IS_ACTOR (self));
+
+  if (self->priv->n_children == 0)
+    return;
+
+  iter = self->priv->first_child;
+  while (iter != NULL)
+    {
+      ClutterActor *next = iter->priv->next_sibling;
+
+      clutter_actor_remove_child_internal (self, iter, TRUE, TRUE);
+
+      iter = next;
+    }
+
+  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

@@ -466,6 +466,7 @@ void                  clutter_actor_replace_child             (ClutterActor
                                                                ClutterActor          *new_child);
 void                  clutter_actor_remove_child              (ClutterActor          *self,
                                                                ClutterActor          *child);
+void                  clutter_actor_remove_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,

tests/conform/test-actor-graph.c

@@ -311,3 +311,31 @@ actor_replace_child (TestConformSimpleFixture *fixture,
   clutter_actor_destroy (actor);
   g_object_unref (actor);
 }
+
+void
+actor_remove_all (TestConformSimpleFixture *fixture,
+                  gconstpointer dummy)
+{
+  ClutterActor *actor = clutter_actor_new ();
+
+  g_object_ref_sink (actor);
+
+  clutter_actor_add_child (actor, g_object_new (CLUTTER_TYPE_ACTOR,
+                                                "name", "foo",
+                                                NULL));
+  clutter_actor_add_child (actor, g_object_new (CLUTTER_TYPE_ACTOR,
+                                                "name", "bar",
+                                                NULL));
+  clutter_actor_add_child (actor, g_object_new (CLUTTER_TYPE_ACTOR,
+                                                "name", "baz",
+                                                NULL));
+
+  g_assert_cmpint (clutter_actor_get_n_children (actor), ==, 3);
+
+  clutter_actor_remove_all_children (actor);
+
+  g_assert_cmpint (clutter_actor_get_n_children (actor), ==, 0);
+
+  clutter_actor_destroy (actor);
+  g_object_unref (actor);
+}

tests/conform/test-conform-main.c

@@ -130,10 +130,11 @@ main (int argc, char **argv)
 
   TEST_CONFORM_SIMPLE ("/actor", actor_add_child);
   TEST_CONFORM_SIMPLE ("/actor", actor_insert_child);
-  TEST_CONFORM_SIMPLE ("/actor", actor_remove_child);
   TEST_CONFORM_SIMPLE ("/actor", actor_raise_child);
   TEST_CONFORM_SIMPLE ("/actor", actor_lower_child);
   TEST_CONFORM_SIMPLE ("/actor", actor_replace_child);
+  TEST_CONFORM_SIMPLE ("/actor", actor_remove_child);
+  TEST_CONFORM_SIMPLE ("/actor", actor_remove_all);
   TEST_CONFORM_SIMPLE ("/actor", actor_destruction);
   TEST_CONFORM_SIMPLE ("/actor", actor_anchors);
   TEST_CONFORM_SIMPLE ("/actor", actor_picking);