ClutterContainer: Clutter Reference Manual

## ClutterContainer ClutterContainer — An interface for container actors |

## Functions

void | clutter_container_add_actor ()
void | clutter_container_add ()
void | clutter_container_add_valist ()
void | clutter_container_remove_actor ()
void | clutter_container_remove ()
void | clutter_container_remove_valist ()
GList * | clutter_container_get_children ()
void | clutter_container_foreach ()
void | clutter_container_foreach_with_internals ()
ClutterActor * | clutter_container_find_child_by_name ()
void | clutter_container_raise_child ()
void | clutter_container_lower_child ()
void | clutter_container_sort_depth_order ()
GParamSpec * | clutter_container_class_find_child_property ()
GParamSpec ** | clutter_container_class_list_child_properties ()
void | clutter_container_child_set_property ()
void | clutter_container_child_get_property ()
void | clutter_container_child_set ()
void | clutter_container_child_get ()
void | clutter_container_child_notify ()
void | clutter_container_create_child_meta ()
void | clutter_container_destroy_child_meta ()
ClutterChildMeta * | clutter_container_get_child_meta ()

## Signals

void | actor-added | Run First
void | actor-removed | Run First
void | child-notify | Has Details

## Types and Values

| ClutterContainer
struct | ClutterContainerIface

## Object Hierarchy

        GInterface
        ╰── ClutterContainer

## Prerequisites

ClutterContainer requires GObject.

## Known Implementations

ClutterContainer is implemented by ClutterActor, ClutterBox, ClutterCairoTexture, ClutterClone, ClutterGLXTexturePixmap, ClutterGroup, ClutterRectangle, ClutterScrollActor, ClutterStage, ClutterText, ClutterTexture and ClutterX11TexturePixmap.

## Description

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.

## Functions

### clutter_container_add_actor ()

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

`clutter_container_add_actor` has been deprecated since version 1.10 and should not be used in newly-written code.

Use `clutter_actor_add_child()` instead.

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

[virtual add]

#### Parameters

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

Since: 0.4

### clutter_container_add ()

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

`clutter_container_add` has been deprecated since version 1.10 and should not be used in newly-written code.

Use `clutter_actor_add_child()` instead.

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

[skip]

#### Parameters

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

`clutter_container_add_valist` has been deprecated since version 1.10 and should not be used in newly-written code.

Use `clutter_actor_add_child()` instead.

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

[skip]

#### Parameters

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

`clutter_container_remove_actor` has been deprecated since version 1.10 and should not be used in newly-written code.

Use `clutter_actor_remove_child()` instead.

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

[virtual remove]

#### Parameters

container | a ClutterContainer |
actor | a ClutterActor |

Since: 0.4

### clutter_container_remove ()

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

`clutter_container_remove` has been deprecated since version 1.10 and should not be used in newly-written code.

Use `clutter_actor_remove_child()` instead.

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

[skip]

#### Parameters

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

`clutter_container_remove_valist` has been deprecated since version 1.10 and should not be used in newly-written code.

Use `clutter_actor_remove_child()` instead.

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

[skip]

#### Parameters

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

`clutter_container_get_children` has been deprecated since version 1.10 and should not be used in newly-written code.

Use `clutter_actor_get_children()` instead.

Retrieves all the children of `container` .

#### Parameters

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

`clutter_container_foreach` has been deprecated since version 1.10 and should not be used in newly-written code.

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.

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.

#### Parameters

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

`clutter_container_foreach_with_internals` has been deprecated since version 1.10 and should not be used in newly-written code.

See `clutter_container_foreach()`.

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.

#### Parameters

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.

#### Parameters

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

`clutter_container_raise_child` has been deprecated since version 1.10 and should not be used in newly-written code.

Use `clutter_actor_set_child_above_sibling()` instead.

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]

#### Parameters

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

`clutter_container_lower_child` has been deprecated since version 1.10 and should not be used in newly-written code.

Use `clutter_actor_set_child_below_sibling()` instead.

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]

#### Parameters

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

`clutter_container_sort_depth_order` has been deprecated since version 1.10 and should not be used in newly-written code.

The `ClutterContainerIface.sort_depth_order()` virtual function should not be used any more; the default implementation in ClutterContainer does not do anything.

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

#### Parameters

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

#### Parameters

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.

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

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 `ClutterContainerIface.child_notify()` virtual function of ClutterContainer. The default implementation will emit the “child-notify” signal.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

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

## Types and Values

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

#### Members

`add` () | virtual function for adding an actor to the container. This virtual function is deprecated, and it should not be overridden. |
`remove` () | virtual function for removing an actor from the container. This virtual function is deprecated, and it should not be overridden. |
`foreach` () | virtual function for iterating over the container's children. This virtual function is deprecated, and it should not be overridden. |
`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. This virtual function is deprecated, and it should not be overridden. |
`raise` () | virtual function for raising a child. This virtual function is deprecated and it should not be overridden. |
`lower` () | virtual function for lowering a child. This virtual function is deprecated and it should not be overridden. |
`sort_depth_order` () | virtual function for sorting the children of a container depending on their depth. This virtual function is deprecated and it should not be overridden. |
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

## Signal Details

### The `“actor-added”` signal

    void
    user_function (ClutterContainer *container,
                   ClutterActor     *actor,
                   gpointer          user_data)

The ::actor-added signal is emitted each time an actor has been added to `container` .

#### Parameters

container | the actor which received the signal |
actor | the new child that has been added to `container` |
user_data | user data set when the signal handler was connected. |

Flags: Run First

Since: 0.4

### The `“actor-removed”` signal

    void
    user_function (ClutterContainer *container,
                   ClutterActor     *actor,
                   gpointer          user_data)

The ::actor-removed signal is emitted each time an actor is removed from `container` .

#### Parameters

container | the actor which received the signal |
actor | the child that has been removed from `container` |
user_data | user data set when the signal handler was connected. |

Flags: Run First

Since: 0.4

### The `“child-notify”` signal

    void
    user_function (ClutterContainer *container,
                   ClutterActor     *actor,
                   GParamSpec       *pspec,
                   gpointer          user_data)

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.

#### Parameters

container | the container which received the signal |
actor | the child that has had a property set |
pspec | the GParamSpec of the property set. | [type GParamSpec]
user_data | user data set when the signal handler was connected. |

Flags: Has Details

Since: 0.8