## ClutterContainer

ClutterContainer — An interface for implementing container actors

## Synopsis

                        ClutterContainer;
    struct              ClutterContainerIface;
    void                clutter_container_add_actor         (ClutterContainer *container,
                                                             ClutterActor *actor);
    void                clutter_container_add               (ClutterContainer *container,
                                                             ClutterActor *first_actor,
                                                             ...);
    void                clutter_container_add_valist        (ClutterContainer *container,
                                                             ClutterActor *first_actor,
                                                             va_list var_args);
    void                clutter_container_remove_actor      (ClutterContainer *container,
                                                             ClutterActor *actor);
    void                clutter_container_remove            (ClutterContainer *container,
                                                             ClutterActor *first_actor,
                                                             ...);
    void                clutter_container_remove_valist     (ClutterContainer *container,
                                                             ClutterActor *first_actor,
                                                             va_list var_args);
    GList *             clutter_container_get_children      (ClutterContainer *container);
    void                clutter_container_foreach           (ClutterContainer *container,
                                                             ClutterCallback callback,
                                                             gpointer user_data);
    void                clutter_container_foreach_with_internals
                                                            (ClutterContainer *container,
                                                             ClutterCallback callback,
                                                             gpointer user_data);

    ClutterActor *      clutter_container_find_child_by_name
                                                            (ClutterContainer *container,
                                                             const gchar *child_name);
    void                clutter_container_raise_child       (ClutterContainer *container,
                                                             ClutterActor *actor,
                                                             ClutterActor *sibling);
    void                clutter_container_lower_child       (ClutterContainer *container,
                                                             ClutterActor *actor,
                                                             ClutterActor *sibling);
    void                clutter_container_sort_depth_order  (ClutterContainer *container);

    GParamSpec *        clutter_container_class_find_child_property
                                                            (GObjectClass *klass,
                                                             const gchar *property_name);
    GParamSpec **       clutter_container_class_list_child_properties
                                                            (GObjectClass *klass,
                                                             guint *n_properties);
    void                clutter_container_child_set_property
                                                            (ClutterContainer *container,
                                                             ClutterActor *child,
                                                             const gchar *property,
                                                             const GValue *value);
    void                clutter_container_child_get_property
                                                            (ClutterContainer *container,
                                                             ClutterActor *child,
                                                             const gchar *property,
                                                             GValue *value);
    void                clutter_container_child_set         (ClutterContainer *container,
                                                             ClutterActor *actor,
                                                             const gchar *first_prop,
                                                             ...);
    void                clutter_container_child_get         (ClutterContainer *container,
                                                             ClutterActor *actor,
                                                             const gchar *first_prop,
                                                             ...);
    void                clutter_container_child_notify      (ClutterContainer *container,
                                                             ClutterActor *child,
                                                             GParamSpec *pspec);

    void                clutter_container_create_child_meta (ClutterContainer *container,
                                                             ClutterActor *actor);
    void                clutter_container_destroy_child_meta
                                                            (ClutterContainer *container,
                                                             ClutterActor *actor);
    ClutterChildMeta *  clutter_container_get_child_meta    (ClutterContainer *container,
                                                             ClutterActor *actor);

## Object Hierarchy

      GInterface
       +----ClutterContainer

## Prerequisites

ClutterContainer requires GObject.

## Known Implementations

ClutterContainer is implemented by ClutterBox, ClutterGroup and ClutterStage.

## Description

ClutterContainer is an interface for writing actors containing other ClutterActors. It provides a standard API for adding, removing and iterating on every contained actor.

An actor implementing ClutterContainer is ClutterGroup.

ClutterContainer is available since Clutter 0.4

## Details

### ClutterContainer

    typedef struct _ClutterContainer ClutterContainer;

ClutterContainer is an opaque structure whose members cannot be directly accessed

Since 0.4

### struct ClutterContainerIface

    struct ClutterContainerIface {
      void (* add)              (ClutterContainer *container,
                                 ClutterActor     *actor);
      void (* remove)           (ClutterContainer *container,
                                 ClutterActor     *actor);
      void (* foreach)          (ClutterContainer *container,
                                 ClutterCallback   callback,
                                 gpointer          user_data);

      void (* foreach_with_internals) (ClutterContainer *container,
                                       ClutterCallback   callback,
                                       gpointer          user_data);

      /* child stacking */
      void (* raise)            (ClutterContainer *container,
                                 ClutterActor     *actor,
                                 ClutterActor     *sibling);
      void (* lower)            (ClutterContainer *container,
                                 ClutterActor     *actor,
                                 ClutterActor     *sibling);
      void (* sort_depth_order) (ClutterContainer *container);

      /* ClutterChildMeta management */
      GType                child_meta_type;
      void              (* create_child_meta)  (ClutterContainer *container,
                                                ClutterActor     *actor);
      void              (* destroy_child_meta) (ClutterContainer *container,
                                                ClutterActor     *actor);
      ClutterChildMeta *(* get_child_meta)     (ClutterContainer *container,
                                                ClutterActor     *actor);

      /* signals */
      void (* actor_added)   (ClutterContainer *container,
                              ClutterActor     *actor);
      void (* actor_removed) (ClutterContainer *container,
                              ClutterActor     *actor);

      void (* child_notify)  (ClutterContainer *container,
                              ClutterActor     *child,
                              GParamSpec       *pspec);
    };

Base interface for container actors. The `add`, `remove` and `foreach` virtual functions must be provided by any implementation; the other virtual functions are optional.

`add` () | virtual function for adding an actor to the container. The implementation of this virtual function is required.
`remove` () | virtual function for removing an actor from the container. The implementation of this virtual function is required.
`foreach` () | virtual function for iterating over the container's children. The implementation of this virtual function is required.
`foreach_with_internals` () | virtual functions for iterating over the container's children, both added using the ClutterContainer API and internal children. The implementation of this virtual function is required only if the ClutterContainer implementation has internal children.
`raise` () | virtual function for raising a child
`lower` () | virtual function for lowering a child
`sort_depth_order` () | virtual function for sorting the children of a container depending on their depth
GType `child_meta_type`; | The GType used for storing auxiliary information about each of the containers children.
`create_child_meta` () | virtual function that gets called for each added child, the function should instantiate an object of type "child_meta_type", set the container and actor fields in the instance and add the record to a data structure for subsequent access for "get_child_meta"
`destroy_child_meta` () | virtual function that gets called when a child is removed; it shuld release all resources held by the record
`get_child_meta` () | return the record for a container child
`actor_added` () | class handler for "actor-added"
`actor_removed` () | class handler for "actor-removed"
`child_notify` () | class handler for "child-notify"

Since 0.4

### clutter_container_add_actor ()

    void                clutter_container_add_actor         (ClutterContainer *container,
                                                             ClutterActor *actor);

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.

Virtual: add

`container` : | a ClutterContainer
`actor` : | the first ClutterActor to add

Since 0.4

### clutter_container_add ()

    void                clutter_container_add               (ClutterContainer *container,
                                                             ClutterActor *first_actor,
                                                             ...);

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.

`container` : | a ClutterContainer
`first_actor` : | the first ClutterActor to add
`...` : | `NULL` terminated list of actors to add

Since 0.4

### clutter_container_add_valist ()

    void                clutter_container_add_valist        (ClutterContainer *container,
                                                             ClutterActor *first_actor,
                                                             va_list var_args);

Alternative va_list version of `clutter_container_add()`.

`container` : | a ClutterContainer
`first_actor` : | the first ClutterActor to add
`var_args` : | list of actors to add, followed by `NULL`

Since 0.4

### clutter_container_remove_actor ()

    void                clutter_container_remove_actor      (ClutterContainer *container,
                                                             ClutterActor *actor);

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

Virtual: remove

`container` : | a ClutterContainer
`actor` : | a ClutterActor

Since 0.4

### clutter_container_remove ()

    void                clutter_container_remove            (ClutterContainer *container,
                                                             ClutterActor *first_actor,
                                                             ...);

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

`container` : | a ClutterContainer
`first_actor` : | first ClutterActor to remove
`...` : | a `NULL`-terminated list of actors to remove

Since 0.4

### clutter_container_remove_valist ()

    void                clutter_container_remove_valist     (ClutterContainer *container,
                                                             ClutterActor *first_actor,
                                                             va_list var_args);

Alternative va_list version of `clutter_container_remove()`.

`container` : | a ClutterContainer
`first_actor` : | the first ClutterActor to add
`var_args` : | list of actors to remove, followed by `NULL`

Since 0.4

### clutter_container_get_children ()

    GList *             clutter_container_get_children      (ClutterContainer *container);

Retrieves all the children of `container`.

`container` : | a ClutterContainer
Returns : | a list of ClutterActors. Use `g_list_free()` on the returned list when done. [element-type Clutter.Actor][transfer container]

Since 0.4

### clutter_container_foreach ()

    void                clutter_container_foreach           (ClutterContainer *container,
                                                             ClutterCallback callback,
                                                             gpointer user_data);

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.

`container` : | a ClutterContainer
`callback` : | a function to be called for each child. [scope call]
`user_data` : | data to be passed to the function, or `NULL`

Since 0.4

### clutter_container_foreach_with_internals ()

    void                clutter_container_foreach_with_internals
                                                            (ClutterContainer *container,
                                                             ClutterCallback callback,
                                                             gpointer user_data);

Calls `callback` for each child of `container`, including "internal" children built in to the container itself that were never added by the application.

`container` : | a ClutterContainer
`callback` : | a function to be called for each child. [scope call]
`user_data` : | data to be passed to the function, or `NULL`

Since 1.0

### clutter_container_find_child_by_name ()

    ClutterActor *      clutter_container_find_child_by_name
                                                            (ClutterContainer *container,
                                                             const gchar *child_name);

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

`container` : | a ClutterContainer
`child_name` : | the name of the requested child.
Returns : | The child actor with the requested name, or `NULL` if no actor with that name was found. [transfer none]

Since 0.6

### clutter_container_raise_child ()

    void                clutter_container_raise_child       (ClutterContainer *container,
                                                             ClutterActor *actor,
                                                             ClutterActor *sibling);

Raises `actor` to `sibling` level, in the depth ordering.

Virtual: raise

`container` : | a ClutterContainer
`actor` : | the actor to raise
`sibling` : | the sibling to raise to, or `NULL` to raise to the top. [allow-none]

Since 0.6

### clutter_container_lower_child ()

    void                clutter_container_lower_child       (ClutterContainer *container,
                                                             ClutterActor *actor,
                                                             ClutterActor *sibling);

Lowers `actor` to `sibling` level, in the depth ordering.

Virtual: lower

`container` : | a ClutterContainer
`actor` : | the actor to raise
`sibling` : | the sibling to lower to, or `NULL` to lower to the bottom. [allow-none]

Since 0.6

### clutter_container_sort_depth_order ()

    void                clutter_container_sort_depth_order  (ClutterContainer *container);

Sorts a container's children using their depth. This function should not be normally used by applications.

`container` : | a ClutterContainer

Since 0.6

### clutter_container_class_find_child_property ()

    GParamSpec *        clutter_container_class_find_child_property
                                                            (GObjectClass *klass,
                                                             const gchar *property_name);

Looks up the GParamSpec for a child property of `klass`.

`klass` : | a GObjectClass implementing the ClutterContainer interface.
`property_name` : | a property name.
Returns : | The GParamSpec for the property or `NULL` if no such property exist. [transfer none]

Since 0.8

### clutter_container_class_list_child_properties ()

    GParamSpec **       clutter_container_class_list_child_properties
                                                            (GObjectClass *klass,
                                                             guint *n_properties);

Returns an array of GParamSpec for all child properties.

`klass` : | a GObjectClass implementing the ClutterContainer interface.
`n_properties` : | return location for length of returned array.
Returns : | an array of GParamSpecs which should be freed after use. [array length=n_properties][transfer full]

Since 0.8

### clutter_container_child_set_property ()

    void                clutter_container_child_set_property
                                                            (ClutterContainer *container,
                                                             ClutterActor *child,
                                                             const gchar *property,
                                                             const GValue *value);

Sets a container-specific property on a child of `container`.

`container` : | a ClutterContainer
`child` : | a ClutterActor that is a child of `container`.
`property` : | the name of the property to set.
`value` : | the value.

Since 0.8

### clutter_container_child_get_property ()

    void                clutter_container_child_get_property
                                                            (ClutterContainer *container,
                                                             ClutterActor *child,
                                                             const gchar *property,
                                                             GValue *value);

Gets a container specific property of a child of `container`, In general, a copy is made of the property contents and the caller is responsible for freeing the memory by calling `g_value_unset()`.

Note that `clutter_container_child_set_property()` is really intended for language bindings, `clutter_container_child_set()` is much more convenient for C programming.

`container` : | a ClutterContainer
`child` : | a ClutterActor that is a child of `container`.
`property` : | the name of the property to set.
`value` : | the value.

Since 0.8

### clutter_container_child_set ()

    void                clutter_container_child_set         (ClutterContainer *container,
                                                             ClutterActor *actor,
                                                             const gchar *first_prop,
                                                             ...);

Sets container specific properties on the child of a container.

`container` : | a ClutterContainer
`actor` : | a ClutterActor that is a child of `container`.
`first_prop` : | name of the first property to be set.
`...` : | value for the first property, followed optionally by more name/value pairs terminated with NULL.

Since 0.8

### clutter_container_child_get ()

    void                clutter_container_child_get         (ClutterContainer *container,
                                                             ClutterActor *actor,
                                                             const gchar *first_prop,
                                                             ...);

Gets `container` specific properties of an actor.

In general, a copy is made of the property contents and the caller is responsible for freeing the memory in the appropriate manner for the type, for instance by calling `g_free()` or `g_object_unref()`.

`container` : | a ClutterContainer
`actor` : | a ClutterActor that is a child of `container`.
`first_prop` : | name of the first property to be set.
`...` : | value for the first property, followed optionally by more name/value pairs terminated with NULL.

Since 0.8

### clutter_container_child_notify ()

    void                clutter_container_child_notify      (ClutterContainer *container,
                                                             ClutterActor *child,
                                                             GParamSpec *pspec);

Calls the ``child_notify()`` virtual function of ClutterContainer. The default implementation will emit the "child-notify" signal.

`container` : | a ClutterContainer
`child` : | a ClutterActor
`pspec` : | a GParamSpec

Since 1.6

### clutter_container_create_child_meta ()

    void                clutter_container_create_child_meta (ClutterContainer *container,
                                                             ClutterActor *actor);

Creates the ClutterChildMeta wrapping `actor` inside the `container`, if the "child_meta_type" class member is not set to `G_TYPE_INVALID`.

This function is only useful when adding a ClutterActor to a ClutterContainer implementation outside of the ClutterContainer::`add()` virtual function implementation.

Applications should not call this function.

`container` : | a ClutterContainer
`actor` : | a ClutterActor

Since 1.2

### clutter_container_destroy_child_meta ()

    void                clutter_container_destroy_child_meta
                                                            (ClutterContainer *container,
                                                             ClutterActor *actor);

Destroys the ClutterChildMeta wrapping `actor` inside the `container`, if any.

This function is only useful when removing a ClutterActor to a ClutterContainer implementation outside of the ClutterContainer::`add()` virtual function implementation.

Applications should not call this function.

`container` : | a ClutterContainer
`actor` : | a ClutterActor

Since 1.2

### clutter_container_get_child_meta ()

    ClutterChildMeta *  clutter_container_get_child_meta    (ClutterContainer *container,
                                                             ClutterActor *actor);

Retrieves the ClutterChildMeta which contains the data about the `container` specific state for `actor`.

`container` : | a ClutterContainer
`actor` : | a ClutterActor that is a child of `container`.
Returns : | the ClutterChildMeta for the `actor` child of `container` or `NULL` if the specifiec actor does not exist or the container is not configured to provide ClutterChildMetas. [transfer none]

Since 0.8