diff --git a/clutter/clutter-actor.c b/clutter/clutter-actor.c index 4dd2be22e..022eb30fa 100644 --- a/clutter/clutter-actor.c +++ b/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; diff --git a/clutter/clutter-actor.h b/clutter/clutter-actor.h index 45d110d26..56c785be1 100644 --- a/clutter/clutter-actor.h +++ b/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, diff --git a/clutter/clutter.symbols b/clutter/clutter.symbols index 159f76ae8..7fa581593 100644 --- a/clutter/clutter.symbols +++ b/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 diff --git a/doc/reference/clutter/clutter-sections.txt b/doc/reference/clutter/clutter-sections.txt index a82da170b..213206482 100644 --- a/doc/reference/clutter/clutter-sections.txt +++ b/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 clutter_actor_push_internal