ClutterContainer

ClutterContainer — An interface for 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 ClutterActor, ClutterBox, ClutterCairoTexture, ClutterClone, ClutterGroup, ClutterRectangle, ClutterScrollActor, ClutterStage, ClutterText and ClutterTexture.

Signals

  "actor-added"                                    : Run First
  "actor-removed"                                  : Run First
  "child-notify"                                   : Has Details

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.

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

clutter_container_add_actor ()

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

Warning

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

container :

 a ClutterContainer

actor :

 the first ClutterActor to add

Since 0.4

clutter_container_add ()

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

Warning

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

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

Warning

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

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

Warning

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

container :

 a ClutterContainer

actor :

 a ClutterActor

Since 0.4

clutter_container_remove ()

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

Warning

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

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

Warning

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

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

Warning

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.

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

Warning

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.

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

Warning

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.

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

Warning

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

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

Warning

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

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

Warning

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.

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

Signal Details

The "actor-added" signal

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

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

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.

Since 0.4

The "actor-removed" signal

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

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

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.

Since 0.4

The "child-notify" signal

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

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.

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.

Since 0.8

Generated by GTK-Doc V1.18.1