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

Generated by GTK-Doc V1.10