--- name: "Clutter::Container" section: "3pm" platform: "linux" package: "libclutter-perl" version: "1.002-1" release: "Debian 6.0 (Squeeze)" platforms: ["linux"] url: "https://new.carta.tech/Clutter::Container" --- # Clutter::Container(3pm) An interface for implementing container actors ## NAME Clutter::Container - An interface for implementing container actors ## DESCRIPTION **Clutter::Container** is an interface for Clutter::Actors that provides a common API for adding, removing and iterating over children. By implementing the Clutter::Container interface with the usual Glib::Object subclassing methods it is possible to use the Clutter::Container API for managing children. ## HIERARCHY ``` Glib::Interface +----Clutter::Container ``` ## METHODS ### $container-\>add ($actor, ...) - • ... (list) list of actors Adds a list of actors to *container* ### list = $container-\>child\_get ($child, ...) - • `$child` (Clutter::Actor) - • ... (list) list of property names Returns a list of values of properties of the child ### list = $container-\>child\_get\_property ($child, ...) - • `$child` (Clutter::Actor) - • ... (list) ### childmeta = $container-\>get\_child\_meta ($actor) - • `$actor` (Clutter::Actor) Retrieves the Clutter::ChildMeta instance for *actor* ### string = $container-\>get\_child\_meta\_type Retrieves the ChildMeta type used by *container* ### $container-\>set\_child\_meta\_type ($type\_name) - • `$type_name` (string) Sets the ChildMeta type used by *container*. This type can only be set once and only if the container implementation does not have any ChildMeta type set already. If you try to set the ChildMeta type on an instance with a type already set, this function will croak. May croak with a Glib::Error in $@ on failure. ### $container-\>child\_set ($child, ...) - • `$child` (Clutter::Actor) - • ... (list) list of property names Sets a list of properties of the child ### $container-\>child\_set\_property ($child, ...) - • `$child` (Clutter::Actor) - • ... (list) ### actors = $container-\>get\_children ### actor or undef = $container-\>find\_child\_by\_name ($name) - • `$name` (string) ### $container-\>foreach ($callback, $callback\_data=undef) - • `$callback` (scalar) - • `$callback_data` (scalar) ### $container-\>lower\_child ($actor, $sibling) - • `$actor` (Clutter::Actor) - • `$sibling` (Clutter::Actor) ### $container-\>raise\_child ($actor, $sibling) - • `$actor` (Clutter::Actor) - • `$sibling` (Clutter::Actor) ### $container-\>remove ($actor, ...) - • ... (list) list of actors Removes a list of actors from *container* ## CHILD PROPERTIES Clutter::Container allows the management of properties that exist only when an actor is contained inside a container. For instance, it is possible to add a property like *padding* to a child actor when inside a container; such property might only be useful when adding any actor to a specific container implementation, and might be desirable not to have it inside the actor class itself. In order to create child properties for a container it is needed to subclass the Clutter::ChildMeta object class using the usual Glib::Object mechanisms, like: ``` package My::ChildMeta; use Glib::Object::Subclass 'Clutter::ChildMeta', properties => [ ... ]; ``` The Clutter::ChildMeta class is the class that stores and handles the child properties. A ChildMeta instance also stores references to the container that handles it, and to the actor it is wrapping. The container implementation should set the package name of the ChildMeta subclass it will use; the most convenient place is inside the INIT\_INSTANCE sub: ``` sub INIT_INSTANCE { my ($self) = @_; # instance set up $self->set_child_meta_type('My::ChildMeta'); } ``` This is enough to start using the *Clutter::Container::child\_set()* and *Clutter::Container::child\_get()* methods to store and retrieve values for the properties specified inside the ChildMeta subclass, like: ``` $container->child_set($child, 'padding', [ 0, 10, 0, 10 ]); ``` When the child is removed from the container, the ChildMeta instance bound to it will simply disappear. It is also possible to exercise a higher degree of control on the creation and destruction of the ChildMeta instances by using the CREATE\_CHILD\_META, GET\_CHILD\_META and DESTROY\_CHILD\_META functions. ## CREATING A CUSTOM CONTAINER ACTOR ``` package MyContainer; use Clutter; use Glib::Object::Subclass 'Clutter::Actor', interfaces => [ qw( Clutter::Container ) ]; ``` ### Virtual Methods In order to create a Clutter::Container actor, an implementation of the following methods is required: - **ADD ($container, $actor)** - o $container (Clutter::Container) - o $actor (Clutter::Actor) Called to add *actor* to *container*. The implementation should queue a relayout of *container* and emit the **::actor-added** signal once the actor has been added. For instance: ``` push @{$self->{children}}, $actor; $actor->set_parent($self); $self->queue_relayout(); $self->signal_emit('actor-added', $actor); ``` - **REMOVE ($container, $actor)** - o $container (Clutter::Container) - o $actor (Clutter::Actor) Called to remove *actor* from *container*. The implementation should emit the **::actor-removed** signal once the actor has been removed. - **RAISE ($container, $child,** ***$sibling*****)** - o $container (Clutter::Container) - o $child (Clutter::Actor) - o $sibling (Clutter::Actor) Called when raising *child* above *sibling*. If *sibling* is undefined, then *child* should be raised above every other child of *container*. - **LOWER ($container, $child,** ***$sibling*****)** - o $container (Clutter::Container) - o $child (Clutter::Actor) - o $sibling (Clutter::Actor) Called when lowering *child* below *sibling*. If *sibling* is undefined, then *child* should be lowered below every other child of *container*. - **SORT\_DEPTH\_ORDER ($container)** - o $container (Clutter::Container) Called when resorting the list of children depending on their depth. - **FOREACH ($container, $function,** ***$data*****)** - **FOREACH\_WITH\_INTERNALS ($container, $function,** ***$data*****)** - o $container (Clutter::Container) - o $function (code reference) - o $data (scalar) data to pass to the function Called when iterating over every child of *container*. For each child the *function* must be called with the actor and the passed *data*, for instance: ``` foreach my $child (@{$container->{children}}) { &$function ($child, $data); } ``` This function will also be called by the **get\_children** method. The difference between **FOREACH** and **FOREACH\_WITH\_INTERNALS** is that the latter should iterate over every child of the container, including the actors that are internal to it -- that is, the actors that have not been added using the Clutter::Container API but that are direct responsability of the container itself. If your container actor has no internal children, you can choose to implement only the **FOREACH** method. - **CREATE\_CHILD\_META ($container, $actor)** - o $container (Clutter::Container) - o $actor (Clutter::Actor) Called when creating a new Clutter::ChildMeta instance wrapping *actor* inside *container*. This function should be overridden only if the metadata class used to implement child properties needs special code or needs to be stored inside a different data structure within *container*. For instance: ``` sub CREATE_CHILD_META { my ($self, $child) = @_; my $meta = My::ChildMeta->new( container => $self, actor => $child, ); # store the ChildMeta into a hash using the # actor itself as the key $self->{meta}->{$child} = $meta; } ``` When overriding the *CREATE\_CHILD\_META*, the *GET\_CHILD\_META* and the *DESTROY\_CHILD\_META* methods should be overridden as well. This function is called before Clutter::Container::ADD\_ACTOR. - **DESTROY\_CHILD\_META ($container, $actor)** - o $container (Clutter::Container) - o $actor (Clutter::Actor) Called when destroying a Clutter::ChildMeta instance for *actor*. For instance: ``` sub DESTROY_CHILD_META { my ($self, $child) = @_; delete $self->{meta}->{$child}; } ``` This function is called before Clutter::Actor::REMOVE\_ACTOR - **childmeta = GET\_CHILD\_META ($container, $actor)** - o $container (Clutter::Container) - o $actor (Clutter::Actor) Called when retrieving a Clutter::ChildMeta instance for *actor*. For instance: ``` sub GET_CHILD_META { my ($self, $child) = @_; return $self->{meta}->{$child}; } ``` ## SIGNALS - **actor-added** (Clutter::Container, Clutter::Actor) - **actor-removed** (Clutter::Container, Clutter::Actor) - **child-notify** (Clutter::Container, Clutter::Actor, Glib::ParamSpec) ## SEE ALSO Clutter, Glib::Interface ## COPYRIGHT Copyright (C) 2006, 2007, 2008 OpenedHand Ltd Copyright (C) 2009 Intel Corporation This module is free software; you can redistribute it and/or modify it under the terms of either: - • the GNU Lesser General Public Library version 2.1; or - • the Artistic License, version 2.0. See Clutter for the full copyright notice.