From 630e602eac37b831677376c33b208a5c536f8260 Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Thu, 9 Feb 2012 15:38:11 +0000 Subject: [PATCH] docs: Update the Container interface documentation The API reference should be more explicit about which parts of the interface should be overridden, and which are deprecated. --- clutter/clutter-container.c | 58 +++++++++++++++++++++++++++++++++---- 1 file changed, 53 insertions(+), 5 deletions(-) diff --git a/clutter/clutter-container.c b/clutter/clutter-container.c index 9059b0db3..49c828266 100644 --- a/clutter/clutter-container.c +++ b/clutter/clutter-container.c @@ -67,8 +67,17 @@ * SECTION:clutter-container * @short_description: An interface for container actors * - * #ClutterContainer provides some common API for #ClutterActor - * instances containing children. + * #ClutterContainer is an interface implemented by #ClutterActor, and + * it provides some common API for notifying when a child actor is added + * or removed, as well as the infrastructure for accessing child properties + * through #ClutterChildMeta. + * + * Until Clutter 1.10, the #ClutterContainer interface was also the public + * API for implementing container actors; this part of the interface has + * been deprecated: #ClutterContainer has a default implementation which + * defers to #ClutterActor the child addition and removal, as well as the + * iteration. See the documentation of #ClutterContainerIface for the list + * of virtual functions that should be overridden. */ enum @@ -360,6 +369,10 @@ container_remove_valist (ClutterContainer *container, * be parented to @container, which takes a reference on the actor. You * cannot add a #ClutterActor to more than one #ClutterContainer. * + * This function will call #ClutterContainerIface.add(), which is a + * deprecated virtual function. The default implementation will + * call clutter_actor_add_child(). + * * Since: 0.4 * * Deprecated: 1.10: Use clutter_actor_add_child() instead. @@ -389,6 +402,10 @@ clutter_container_add (ClutterContainer *container, * @container. You cannot add a #ClutterActor to more than one * #ClutterContainer. * + * This function will call #ClutterContainerIface.add(), which is a + * deprecated virtual function. The default implementation will + * call clutter_actor_add_child(). + * * Virtual: add * * Since: 0.4 @@ -413,6 +430,10 @@ clutter_container_add_actor (ClutterContainer *container, * * Alternative va_list version of clutter_container_add(). * + * This function will call #ClutterContainerIface.add(), which is a + * deprecated virtual function. The default implementation will + * call clutter_actor_add_child(). + * * Since: 0.4 * * Deprecated: 1.10: Use clutter_actor_add_child() instead. @@ -440,6 +461,10 @@ clutter_container_add_valist (ClutterContainer *container, * Each time an actor is removed, the "actor-removed" signal is * emitted by @container. * + * This function will call #ClutterContainerIface.remove(), which is a + * deprecated virtual function. The default implementation will call + * clutter_actor_remove_child(). + * * Since: 0.4 * * Deprecated: 1.10: Use clutter_actor_remove_child() instead. @@ -469,6 +494,10 @@ clutter_container_remove (ClutterContainer *container, * yourself, using g_object_ref(). When the actor has been removed, * the "actor-removed" signal is emitted by @container. * + * This function will call #ClutterContainerIface.remove(), which is a + * deprecated virtual function. The default implementation will call + * clutter_actor_remove_child(). + * * Virtual: remove * * Since: 0.4 @@ -493,6 +522,10 @@ clutter_container_remove_actor (ClutterContainer *container, * * Alternative va_list version of clutter_container_remove(). * + * This function will call #ClutterContainerIface.remove(), which is a + * deprecated virtual function. The default implementation will call + * clutter_actor_remove_child(). + * * Since: 0.4 * * Deprecated: 1.10: Use clutter_actor_remove_child() instead. @@ -555,12 +588,16 @@ clutter_container_get_children (ClutterContainer *container) * not iterate over "internal" children that are part of the * container's own implementation, if any. * + * This function calls the #ClutterContainerIface.foreach() + * virtual function, which has been deprecated. + * * Since: 0.4 * * Deprecated: 1.10: Use clutter_actor_get_first_child() or * clutter_actor_get_last_child() to retrieve the beginning of * the list of children, and clutter_actor_get_next_sibling() - * and clutter_actor_get_previous_sibling() to iterate over it. + * and clutter_actor_get_previous_sibling() to iterate over it; + * alternatively, use the #ClutterActorIter API. */ void clutter_container_foreach (ClutterContainer *container, @@ -598,6 +635,9 @@ clutter_container_foreach (ClutterContainer *container, * children built in to the container itself that were never added * by the application. * + * This function calls the #ClutterContainerIface.foreach_with_internals() + * virtual function, which has been deprecated. + * * Since: 1.0 * * Deprecated: 1.10: See clutter_container_foreach(). @@ -640,6 +680,10 @@ clutter_container_foreach_with_internals (ClutterContainer *container, * * Raises @actor to @sibling level, in the depth ordering. * + * This function calls the #ClutterContainerIface.raise() virtual function, + * which has been deprecated. The default implementation will call + * clutter_actor_set_child_above_sibling(). + * * Virtual: raise * * Since: 0.6 @@ -707,6 +751,10 @@ clutter_container_raise_child (ClutterContainer *container, * * Lowers @actor to @sibling level, in the depth ordering. * + * This function calls the #ClutterContainerIface.lower() virtual function, + * which has been deprecated. The default implementation will call + * clutter_actor_set_child_below_sibling(). + * * Virtual: lower * * Since: 0.6 @@ -1387,8 +1435,8 @@ clutter_container_child_get (ClutterContainer *container, * @child: a #ClutterActor * @pspec: a #GParamSpec * - * Calls the child_notify() virtual function of - * #ClutterContainer. The default implementation will emit the + * Calls the #ClutterContainerIface.child_notify() virtual function + * of #ClutterContainer. The default implementation will emit the * #ClutterContainer::child-notify signal. * * Since: 1.6