/*

 * Clutter.

 *

 * An OpenGL based 'interactive canvas' library.

 *

 * Authored By Matthew Allum  <mallum@openedhand.com>

 *

 * Copyright (C) 2006 OpenedHand

 *

 * This library is free software; you can redistribute it and/or

 * modify it under the terms of the GNU Lesser General Public

 * License as published by the Free Software Foundation; either

 * version 2 of the License, or (at your option) any later version.

 *

 * This library is distributed in the hope that it will be useful,

 * but WITHOUT ANY WARRANTY; without even the implied warranty of

 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU

 * Lesser General Public License for more details.

 *

 * You should have received a copy of the GNU Lesser General Public

 * License along with this library. If not, see <http://www.gnu.org/licenses/>.

 *

 *

 *

 * ClutterContainer: Generic actor container interface.

 * Author: Emmanuele Bassi <ebassi@openedhand.com>

 */

#ifdef HAVE_CONFIG_H

#include "config.h"

#endif

#include <stdarg.h>

#include <glib-object.h>

#include <gobject/gvaluecollector.h>

#define CLUTTER_DISABLE_DEPRECATION_WARNINGS

#include "deprecated/clutter-container.h"

#include "clutter-actor-private.h"

#include "clutter-child-meta.h"

#include "clutter-debug.h"

#include "clutter-main.h"

#include "clutter-marshal.h"

#include "clutter-private.h"

#include "clutter-enum-types.h"

#define CLUTTER_CONTAINER_WARN_NOT_IMPLEMENTED(container,vfunc) \

        G_STMT_START { \

          g_warning ("Container of type '%s' does not implement " \

                     "the required ClutterContainer::%s virtual " \

                     "function.",                                 \

                     G_OBJECT_TYPE_NAME ((container)),            \

                     (vfunc));                                    \

        } G_STMT_END

#define CLUTTER_CONTAINER_NOTE_NOT_IMPLEMENTED(container,vfunc) \

        G_STMT_START { \

          CLUTTER_NOTE (ACTOR, "Container of type '%s' does not "    \

                               "implement the ClutterContainer::%s " \

                               "virtual function.",                  \

                        G_OBJECT_TYPE_NAME ((container)),            \

                        (vfunc));                                    \

        } G_STMT_END

/**

 * SECTION:clutter-container

 * @short_description: An interface for container actors

 *

 * #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

{

  ACTOR_ADDED,

  ACTOR_REMOVED,

  CHILD_NOTIFY,

  LAST_SIGNAL

};

static guint container_signals[LAST_SIGNAL] = { 0, };

static GQuark quark_child_meta = 0;

static ClutterChildMeta *get_child_meta     (ClutterContainer *container,

                                             ClutterActor     *actor);

static void              create_child_meta  (ClutterContainer *container,

                                             ClutterActor     *actor);

static void              destroy_child_meta (ClutterContainer *container,

                                             ClutterActor     *actor);

static void              child_notify       (ClutterContainer *container,

                                             ClutterActor     *child,

                                             GParamSpec       *pspec);

typedef ClutterContainerIface   ClutterContainerInterface;

G_DEFINE_INTERFACE (ClutterContainer, clutter_container, G_TYPE_OBJECT);

static void

container_real_add (ClutterContainer *container,

                    ClutterActor     *actor)

{

  clutter_actor_add_child (CLUTTER_ACTOR (container), actor);

}

static void

container_real_remove (ClutterContainer *container,

                       ClutterActor     *actor)

{

  clutter_actor_remove_child (CLUTTER_ACTOR (container), actor);

}

typedef struct {

  ClutterCallback callback;

  gpointer data;

} ForeachClosure;

static gboolean

foreach_cb (ClutterActor *actor,

            gpointer      data)

{

  ForeachClosure *clos = data;

  clos->callback (actor, clos->data);

  return TRUE;

}

static void

container_real_foreach (ClutterContainer *container,

                        ClutterCallback   callback,

                        gpointer          user_data)

{

  ForeachClosure clos;

  clos.callback = callback;

  clos.data = user_data;

  _clutter_actor_foreach_child (CLUTTER_ACTOR (container),

                                foreach_cb,

                                &clos);

}

static void

container_real_raise (ClutterContainer *container,

                      ClutterActor     *child,

                      ClutterActor     *sibling)

{

  ClutterActor *self = CLUTTER_ACTOR (container);

  clutter_actor_set_child_above_sibling (self, child, sibling);

}

static void

container_real_lower (ClutterContainer *container,

                      ClutterActor     *child,

                      ClutterActor     *sibling)

{

  ClutterActor *self = CLUTTER_ACTOR (container);

  clutter_actor_set_child_below_sibling (self, child, sibling);

}

static void

container_real_sort_depth_order (ClutterContainer *container)

{

}

static void

clutter_container_default_init (ClutterContainerInterface *iface)

{

  GType iface_type = G_TYPE_FROM_INTERFACE (iface);

  quark_child_meta =

    g_quark_from_static_string ("clutter-container-child-data");

  /**

   * ClutterContainer::actor-added:

   * @container: the actor which received the signal

   * @actor: the new child that has been added to @container

   *

   * The ::actor-added signal is emitted each time an actor

   * has been added to @container.

   *

   * Since: 0.4

   */

  container_signals[ACTOR_ADDED] =

    g_signal_new (I_("actor-added"),

                  iface_type,

                  G_SIGNAL_RUN_FIRST,

                  G_STRUCT_OFFSET (ClutterContainerIface, actor_added),

                  NULL, NULL,

                  _clutter_marshal_VOID__OBJECT,

                  G_TYPE_NONE, 1,

                  CLUTTER_TYPE_ACTOR);

  /**

   * ClutterContainer::actor-removed:

   * @container: the actor which received the signal

   * @actor: the child that has been removed from @container

   *

   * The ::actor-removed signal is emitted each time an actor

   * is removed from @container.

   *

   * Since: 0.4

   */

  container_signals[ACTOR_REMOVED] =

    g_signal_new (I_("actor-removed"),

                  iface_type,

                  G_SIGNAL_RUN_FIRST,

                  G_STRUCT_OFFSET (ClutterContainerIface, actor_removed),

                  NULL, NULL,

                  _clutter_marshal_VOID__OBJECT,

                  G_TYPE_NONE, 1,

                  CLUTTER_TYPE_ACTOR);

  /**

   * ClutterContainer::child-notify:

   * @container: the container which received the signal

   * @actor: the child that has had a property set

   * @pspec: (type GParamSpec): the #GParamSpec of the property set

   *

   * The ::child-notify signal is emitted each time a property is

   * being set through the clutter_container_child_set() and

   * clutter_container_child_set_property() calls.

   *

   * Since: 0.8

   */

  container_signals[CHILD_NOTIFY] =

    g_signal_new (I_("child-notify"),

                  iface_type,

                  G_SIGNAL_RUN_FIRST | G_SIGNAL_DETAILED,

                  G_STRUCT_OFFSET (ClutterContainerIface, child_notify),

                  NULL, NULL,

                  _clutter_marshal_VOID__OBJECT_PARAM,

                  G_TYPE_NONE, 2,

                  CLUTTER_TYPE_ACTOR, G_TYPE_PARAM);

  iface->add = container_real_add;

  iface->remove = container_real_remove;

  iface->foreach = container_real_foreach;

  iface->raise = container_real_raise;

  iface->lower = container_real_lower;

  iface->sort_depth_order = container_real_sort_depth_order;

  iface->child_meta_type = G_TYPE_INVALID;

  iface->create_child_meta = create_child_meta;

  iface->destroy_child_meta = destroy_child_meta;

  iface->get_child_meta = get_child_meta;

  iface->child_notify = child_notify;

}

static inline void

container_add_actor (ClutterContainer *container,

                     ClutterActor     *actor)

{

  ClutterActor *parent;

  parent = clutter_actor_get_parent (actor);

  if (G_UNLIKELY (parent != NULL))

    {

      g_warning ("Attempting to add actor of type '%s' to a "

		 "container of type '%s', but the actor has "

                 "already a parent of type '%s'.",

		 g_type_name (G_OBJECT_TYPE (actor)),

		 g_type_name (G_OBJECT_TYPE (container)),

		 g_type_name (G_OBJECT_TYPE (parent)));

      return;

    }

  clutter_container_create_child_meta (container, actor);

#ifdef CLUTTER_ENABLE_DEBUG

  if (G_UNLIKELY (_clutter_diagnostic_enabled ()))

    {

      ClutterContainerIface *iface = CLUTTER_CONTAINER_GET_IFACE (container);

      if (iface->add != container_real_add)

        _clutter_diagnostic_message ("The ClutterContainer::add() virtual "

                                     "function has been deprecated and it "

                                     "should not be overridden by newly "

                                     "written code");

    }

#endif /* CLUTTER_ENABLE_DEBUG */

  CLUTTER_CONTAINER_GET_IFACE (container)->add (container, actor);

}

static inline void

container_remove_actor (ClutterContainer *container,

                        ClutterActor     *actor)

{

  ClutterActor *parent;

  parent = clutter_actor_get_parent (actor);

  if (parent != CLUTTER_ACTOR (container))

    {

      g_warning ("Attempting to remove actor of type '%s' from "

		 "group of class '%s', but the container is not "

                 "the actor's parent.",

		 g_type_name (G_OBJECT_TYPE (actor)),

		 g_type_name (G_OBJECT_TYPE (container)));

      return;

    }

  clutter_container_destroy_child_meta (container, actor);

#ifdef CLUTTER_ENABLE_DEBUG

  if (G_UNLIKELY (_clutter_diagnostic_enabled ()))

    {

      ClutterContainerIface *iface = CLUTTER_CONTAINER_GET_IFACE (container);

      if (iface->remove != container_real_remove)

        _clutter_diagnostic_message ("The ClutterContainer::remove() virtual "

                                     "function has been deprecated and it "

                                     "should not be overridden by newly "

                                     "written code");

    }

#endif /* CLUTTER_ENABLE_DEBUG */

  CLUTTER_CONTAINER_GET_IFACE (container)->remove (container, actor);

}

static inline void

container_add_valist (ClutterContainer *container,

                      ClutterActor     *first_actor,

                      va_list           args)

{

  ClutterActor *actor = first_actor;

  while (actor != NULL)

    {

      container_add_actor (container, actor);

      actor = va_arg (args, ClutterActor *);

    }

}

static inline void

container_remove_valist (ClutterContainer *container,

                         ClutterActor     *first_actor,

                         va_list           args)

{

  ClutterActor *actor = first_actor;

  while (actor != NULL)

    {

      container_remove_actor (container, actor);

      actor = va_arg (args, ClutterActor *);

    }

}

/**

 * clutter_container_add: (skip)

 * @container: a #ClutterContainer

 * @first_actor: the first #ClutterActor to add

 * @...: %NULL terminated list of actors to add

 *

 * Adds a list of #ClutterActors to @container. Each time and

 * actor is added, the "actor-added" signal is emitted. Each actor should

 * 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.

 */

void

clutter_container_add (ClutterContainer *container,

                       ClutterActor     *first_actor,

                       ...)

{

  va_list args;

  g_return_if_fail (CLUTTER_IS_CONTAINER (container));

  g_return_if_fail (CLUTTER_IS_ACTOR (first_actor));

  va_start (args, first_actor);

  container_add_valist (container, first_actor, args);

  va_end (args);

}

/**

 * clutter_container_add_actor: (virtual add)

 * @container: a #ClutterContainer

 * @actor: the first #ClutterActor to add

 *

 * Adds a #ClutterActor to @container. This function will emit the

 * "actor-added" signal. The actor should be parented to

 * @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().

 *

 * Since: 0.4

 *

 * Deprecated: 1.10: Use clutter_actor_add_child() instead.

 */

void

clutter_container_add_actor (ClutterContainer *container,

                             ClutterActor     *actor)

{

  g_return_if_fail (CLUTTER_IS_CONTAINER (container));

  g_return_if_fail (CLUTTER_IS_ACTOR (actor));

  container_add_actor (container, actor);

}

/**

 * clutter_container_add_valist: (skip)

 * @container: a #ClutterContainer

 * @first_actor: the first #ClutterActor to add

 * @var_args: list of actors to add, followed by %NULL

 *

 * 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.

 */

void

clutter_container_add_valist (ClutterContainer *container,

                              ClutterActor     *first_actor,

                              va_list           var_args)

{

  g_return_if_fail (CLUTTER_IS_CONTAINER (container));

  g_return_if_fail (CLUTTER_IS_ACTOR (first_actor));

  container_add_valist (container, first_actor, var_args);

}

/**

 * clutter_container_remove: (skip)

 * @container: a #ClutterContainer

 * @first_actor: first #ClutterActor to remove

 * @...: a %NULL-terminated list of actors to remove

 *

 * Removes a %NULL terminated list of #ClutterActors from

 * @container. Each actor should be unparented, so if you want to keep it

 * around you must hold a reference to it yourself, using g_object_ref().

 * 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.

 */

void

clutter_container_remove (ClutterContainer *container,

                          ClutterActor     *first_actor,

                          ...)

{

  va_list var_args;

  g_return_if_fail (CLUTTER_IS_CONTAINER (container));

  g_return_if_fail (CLUTTER_IS_ACTOR (first_actor));

  va_start (var_args, first_actor);

  container_remove_valist (container, first_actor, var_args);

  va_end (var_args);

}

/**

 * clutter_container_remove_actor: (virtual remove)

 * @container: a #ClutterContainer

 * @actor: a #ClutterActor

 *

 * Removes @actor from @container. The actor should be unparented, so

 * if you want to keep it around you must hold a reference to it

 * 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().

 *

 * Since: 0.4

 *

 * Deprecated: 1.10: Use clutter_actor_remove_child() instead.

 */

void

clutter_container_remove_actor (ClutterContainer *container,

                                ClutterActor     *actor)

{

  g_return_if_fail (CLUTTER_IS_CONTAINER (container));

  g_return_if_fail (CLUTTER_IS_ACTOR (actor));

  container_remove_actor (container, actor);

}

/**

 * clutter_container_remove_valist: (skip)

 * @container: a #ClutterContainer

 * @first_actor: the first #ClutterActor to add

 * @var_args: list of actors to remove, followed by %NULL

 *

 * 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.

 */

void

clutter_container_remove_valist (ClutterContainer *container,

                                 ClutterActor     *first_actor,

                                 va_list           var_args)

{

  g_return_if_fail (CLUTTER_IS_CONTAINER (container));

  g_return_if_fail (CLUTTER_IS_ACTOR (first_actor));

  container_remove_valist (container, first_actor, var_args);

}

static void

get_children_cb (ClutterActor *child,

                 gpointer      data)

{

  GList **children = data;

  *children = g_list_prepend (*children, child);

}

/**

 * clutter_container_get_children:

 * @container: a #ClutterContainer

 *

 * Retrieves all the children of @container.

 *

 * Return value: (element-type Clutter.Actor) (transfer container): a list

 *   of #ClutterActors. Use g_list_free() on the returned

 *   list when done.

 *

 * Since: 0.4

 *

 * Deprecated: 1.10: Use clutter_actor_get_children() instead.

 */

GList *

clutter_container_get_children (ClutterContainer *container)

{

  GList *retval;

  g_return_val_if_fail (CLUTTER_IS_CONTAINER (container), NULL);

  retval = NULL;

  clutter_container_foreach (container, get_children_cb, &retval);

  return g_list_reverse (retval);

}

/**

 * clutter_container_foreach:

 * @container: a #ClutterContainer

 * @callback: (scope call): a function to be called for each child

 * @user_data: data to be passed to the function, or %NULL

 *

 * Calls @callback for each child of @container that was added

 * by the application (with clutter_container_add_actor()). Does

 * 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;

 *   alternatively, use the #ClutterActorIter API.

 */

void

clutter_container_foreach (ClutterContainer *container,

                           ClutterCallback   callback,

                           gpointer          user_data)

{

  g_return_if_fail (CLUTTER_IS_CONTAINER (container));

  g_return_if_fail (callback != NULL);

#ifdef CLUTTER_ENABLE_DEBUG

  if (G_UNLIKELY (_clutter_diagnostic_enabled ()))

    {

      ClutterContainerIface *iface = CLUTTER_CONTAINER_GET_IFACE (container);

      if (iface->foreach != container_real_foreach)

        _clutter_diagnostic_message ("The ClutterContainer::foreach() "

                                     "virtual function has been deprecated "

                                     "and it should not be overridden by "

                                     "newly written code");

    }

#endif /* CLUTTER_ENABLE_DEBUG */

  CLUTTER_CONTAINER_GET_IFACE (container)->foreach (container,

                                                    callback,

                                                    user_data);

}

/**

 * clutter_container_foreach_with_internals:

 * @container: a #ClutterContainer

 * @callback: (scope call): a function to be called for each child

 * @user_data: data to be passed to the function, or %NULL

 *

 * Calls @callback for each child of @container, including "internal"

 * 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().

 */

void

clutter_container_foreach_with_internals (ClutterContainer *container,

                                          ClutterCallback   callback,

                                          gpointer          user_data)

{

  ClutterContainerIface *iface;

  g_return_if_fail (CLUTTER_IS_CONTAINER (container));

  g_return_if_fail (callback != NULL);

  iface = CLUTTER_CONTAINER_GET_IFACE (container);

#ifdef CLUTTER_ENABLE_DEBUG

  if (G_UNLIKELY (_clutter_diagnostic_enabled ()))

    {

      if (iface->foreach_with_internals != NULL)

        _clutter_diagnostic_message ("The ClutterContainer::foreach_with_internals() "

                                     "virtual function has been deprecated "

                                     "and it should not be overridden by "

                                     "newly written code");

    }

#endif /* CLUTTER_ENABLE_DEBUG */

  if (iface->foreach_with_internals != NULL)

    iface->foreach_with_internals (container, callback, user_data);

  else

    iface->foreach (container, callback, user_data);

}

/**

 * clutter_container_raise_child: (virtual raise)

 * @container: a #ClutterContainer

 * @actor: the actor to raise

 * @sibling: (allow-none): the sibling to raise to, or %NULL to raise

 *   to the top

 *

 * 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().

 *

 * Since: 0.6

 *

 * Deprecated: 1.10: Use clutter_actor_set_child_above_sibling() instead.

 */

void

clutter_container_raise_child (ClutterContainer *container,

                               ClutterActor     *actor,

                               ClutterActor     *sibling)

{

  ClutterContainerIface *iface;

  ClutterActor *self;

  g_return_if_fail (CLUTTER_IS_CONTAINER (container));

  g_return_if_fail (CLUTTER_IS_ACTOR (actor));

  g_return_if_fail (sibling == NULL || CLUTTER_IS_ACTOR (sibling));

  if (actor == sibling)

    return;

  self = CLUTTER_ACTOR (container);

  if (clutter_actor_get_parent (actor) != self)

    {

      g_warning ("Actor of type '%s' is not a child of the container "

                 "of type '%s'",

                 g_type_name (G_OBJECT_TYPE (actor)),

                 g_type_name (G_OBJECT_TYPE (container)));

      return;

    }

  if (sibling != NULL &&

      clutter_actor_get_parent (sibling) != self)

    {

      g_warning ("Actor of type '%s' is not a child of the container "

                 "of type '%s'",

                 g_type_name (G_OBJECT_TYPE (sibling)),

                 g_type_name (G_OBJECT_TYPE (container)));

      return;

    }

  iface = CLUTTER_CONTAINER_GET_IFACE (container);

#ifdef CLUTTER_ENABLE_DEBUG

  if (G_UNLIKELY (_clutter_diagnostic_enabled ()))

    {

      if (iface->raise != container_real_raise)

        _clutter_diagnostic_message ("The ClutterContainer::raise() "

                                     "virtual function has been deprecated "

                                     "and it should not be overridden by "

                                     "newly written code");

    }

#endif /* CLUTTER_ENABLE_DEBUG */

  iface->raise (container, actor, sibling);

}

/**

 * clutter_container_lower_child: (virtual lower)

 * @container: a #ClutterContainer

 * @actor: the actor to raise

 * @sibling: (allow-none): the sibling to lower to, or %NULL to lower

 *   to the bottom

 *

 * 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().

 *

 * Since: 0.6

 *

 * Deprecated: 1.10: Use clutter_actor_set_child_below_sibling() instead.

 */

void

clutter_container_lower_child (ClutterContainer *container,

                               ClutterActor     *actor,

                               ClutterActor     *sibling)

{

  ClutterContainerIface *iface;

  ClutterActor *self;

  g_return_if_fail (CLUTTER_IS_CONTAINER (container));

  g_return_if_fail (CLUTTER_IS_ACTOR (actor));

  g_return_if_fail (sibling == NULL || CLUTTER_IS_ACTOR (sibling));

  if (actor == sibling)

    return;

  self = CLUTTER_ACTOR (container);

  if (clutter_actor_get_parent (actor) != self)

    {

      g_warning ("Actor of type '%s' is not a child of the container "

                 "of type '%s'",

                 g_type_name (G_OBJECT_TYPE (actor)),

                 g_type_name (G_OBJECT_TYPE (container)));

      return;

    }

  if (sibling != NULL&&

      clutter_actor_get_parent (sibling) != self)

    {

      g_warning ("Actor of type '%s' is not a child of the container "

                 "of type '%s'",

                 g_type_name (G_OBJECT_TYPE (sibling)),

                 g_type_name (G_OBJECT_TYPE (container)));

      return;

    }

  iface = CLUTTER_CONTAINER_GET_IFACE (container);

#ifdef CLUTTER_ENABLE_DEBUG

  if (G_UNLIKELY (_clutter_diagnostic_enabled ()))

    {

      if (iface->lower != container_real_lower)

        _clutter_diagnostic_message ("The ClutterContainer::lower() "

                                     "virtual function has been deprecated "

                                     "and it should not be overridden by "

                                     "newly written code");

    }

#endif /* CLUTTER_ENABLE_DEBUG */

  iface->lower (container, actor, sibling);

}

/**

 * clutter_container_sort_depth_order:

 * @container: a #ClutterContainer

 *

 * Sorts a container's children using their depth. This function should not

 * be normally used by applications.

 *

 * Since: 0.6

 *

 * Deprecated: 1.10: The #ClutterContainerIface.sort_depth_order() virtual

 *   function should not be used any more; the default implementation in

 *   #ClutterContainer does not do anything.

 */

void

clutter_container_sort_depth_order (ClutterContainer *container)

{

  ClutterContainerIface *iface;

  g_return_if_fail (CLUTTER_IS_CONTAINER (container));

  iface = CLUTTER_CONTAINER_GET_IFACE (container);

#ifdef CLUTTER_ENABLE_DEBUG

  if (G_UNLIKELY (_clutter_diagnostic_enabled ()))

    {

      if (iface->sort_depth_order != container_real_sort_depth_order)

        _clutter_diagnostic_message ("The ClutterContainer::sort_depth_order() "

                                     "virtual function has been deprecated "

                                     "and it should not be overridden by "

                                     "newly written code");

    }

#endif /* CLUTTER_ENABLE_DEBUG */

  iface->sort_depth_order (container);

}

/**

 * clutter_container_find_child_by_name:

 * @container: a #ClutterContainer

 * @child_name: the name of the requested child.

 *

 * Finds a child actor of a container by its name. Search recurses

 * into any child container.

 *

 * Return value: (transfer none): The child actor with the requested name,

 *   or %NULL if no actor with that name was found.

 *

 * Since: 0.6

 */

ClutterActor *

clutter_container_find_child_by_name (ClutterContainer *container,

                                      const gchar      *child_name)

{

  GList        *children;

  GList        *iter;

  ClutterActor *actor = NULL;

  g_return_val_if_fail (CLUTTER_IS_CONTAINER (container), NULL);

  g_return_val_if_fail (child_name != NULL, NULL);

  children = clutter_container_get_children (container);

  for (iter = children; iter; iter = g_list_next (iter))

    {

      ClutterActor *a;

      const gchar  *iter_name;

      a = CLUTTER_ACTOR (iter->data);

      iter_name = clutter_actor_get_name (a);

      if (iter_name && !strcmp (iter_name, child_name))

        {

          actor = a;