## ClutterContainer

ClutterContainer — An interface for implementing container actors

## Synopsis

                        ClutterContainer;
                        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);

    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,
                                                             ...);

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

## Object Hierarchy

      GInterface
       +----ClutterContainer

## Prerequisites

ClutterContainer requires GObject.

## Known Implementations

ClutterContainer is implemented by ClutterStage and ClutterGroup.

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

### ClutterContainerIface

    typedef struct {
      void (* add)              (ClutterContainer *container,
                                 ClutterActor     *actor);
      void (* remove)           (ClutterContainer *container,
                                 ClutterActor     *actor);
      void (* foreach)          (ClutterContainer *container,
                                 ClutterCallback   callback,
                                 gpointer          user_data);
      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     *actor,
                              GParamSpec       *pspec);
    } ClutterContainerIface;

Base interface for container actors.

`add` () | virtual function for adding an actor to the container
`remove` () | virtual function for removing an actor from the container
`foreach` () | virtual function for iterating over the container's 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.

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

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

Since 0.4

### clutter_container_foreach ()

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

Calls `callback` for each child of `container`.

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

Since 0.4

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

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.

`container` : | a ClutterContainer
`actor` : | the actor to raise
`sibling` : | the sibling to raise to, or `NULL` to raise to the top

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.

`container` : | a ClutterContainer
`actor` : | the actor to raise
`sibling` : | the sibling to lower to, or `NULL` to lower to the bottom

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.

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.

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_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

Since 0.8