--- name: "Clutter::Animation" section: "3pm" platform: "linux" package: "libclutter-perl" version: "1.002-1" release: "Debian 6.0 (Squeeze)" platforms: ["linux"] url: "https://new.carta.tech/Clutter::Animation" --- # Clutter::Animation(3pm) Animate object properties ## NAME Clutter::Animation - Animate object properties ## SYNOPSIS ``` my $animation = Clutter::Animation->new(); # 500 milliseconds of duration $animation->set_duration(500); # cubic easing mode $animation->set_mode('ease-out-cubic'); # set the object we want to animate $animation->set_object($texture); # bind the properties we want to animate on the object; bind() # calls can be chained up to $animation->bind('scale-x', 2.0) ->bind('scale-y', 2.0) ->bind('opacity', 255); # start the animation $animation->get_timeline()->start(); # set the object as reactive when the animation ends $animation->signal_connect(completed => sub { $animation->get_object()->set_reactive(TRUE); }) ``` ## DESCRIPTION **Clutter::Animation** is an class providing simple, implicit animations for Glib::Object instances. Clutter::Animation instances will bind one or more object properties belonging to a Glib::Object to a Clutter::Interval, and will then use a Clutter::Alpha to interpolate the property between the initial and final values of the interval. The duration of the animation is set using *Clutter::Animation::set\_duration()*. The easing mode of the animation is set using *Clutter::Animation::set\_mode()*. ### Controlling the Animation If you want to control the animation you should retrieve the Clutter::Timeline using *Clutter::Animation::get\_timeline()* and then use Clutter::Timeline methods like *Clutter::Timeline::start()*, *Clutter::Timeline::pause()* or *Clutter::Timeline::stop()*. A Clutter::Animation will emit the Clutter::Animation::completed signal when the Clutter::Timeline used by the animation is completed; unlike Clutter::Timeline, though, the Clutter::Animation::completed will not be emitted if Clutter::Animation:loop is set to `%TRUE` - that is, a looping animation never completes. If your animation depends on user control you can force its completion using *Clutter::Animation::completed()*. If the Glib::Object instance bound to a Clutter::Animation implements the Clutter::Animatable interface it is possible for that instance to control the way the initial and final states are interpolated. ### Changing the Animation The initial and final value of a property bound to the Animation are controlled by a Clutter::Interval instance. You can retrieve the Interval instance and change the values, or you can change the Interval instance itself: ``` # increase the scaling factor $animation->get_interval('scale-x')->set_final_value(2.5); $animation->get_interval('scale-y')->set_final_value(2.5); # change the opacity interval $cur_value = $animation->get_object()->get_opacity(); $interval = Clutter::Interval->new('Glib::Uchar'); $interval->set_interval($cur_value, 128); $animation->update_interval('opacity', $interval); ``` ### Differences between Animation and Behaviour Clutter::Animation is distinguished from Clutter::Behaviour because the former can only control Glib::Object properties of a single Glib::Object instance, while the latter can control multiple properties using accessor functions inside the Clutter::Behaviour::ALPHA\_NOTIFY virtual function, and can control multiple Clutter::Actors at the same time. ### Convenience API For convenience, it is possible to use the *Clutter::Actor::animate()* method which will take care of setting up and tearing down a Clutter::Animation instance and animate an actor between its current state and the specified final state: ``` $texture->animate( 'ease-out-cubic', 500, scale_x => 2.0, scale_y => 2.0, opacity => 255 )->signal_connect(completed => sub { $texture->set_reactive(TRUE) }) ``` The example above reproduces the same animation as the one in the Synopsis. The Clutter::Animation instance created by *Clutter::Actor::animate()* is managed by the *animate()* method itself and it is guaranteed to be valid for as long as the animation is running; once the animation emits the *completed* signal, the animation will still be valid from within handlers connected to that signal, until the default signal handler is executed. ## HIERARCHY ``` Glib::Object +----Clutter::Animation ``` ## METHODS ### animation = Clutter::Animation-\>new Creates a new Clutter::Animation ### alpha = $animation-\>get\_alpha ### $animation-\>set\_alpha ($alpha) - • `$alpha` (Clutter::Alpha) ### animation = $animation-\>bind ($property\_name, $final) - • `$property_name` (string) - • `$final` (scalar) Binds *property\_name* to the animation. An implicit Clutter::Interval will be created which will use: - the type of the property - the current value as the initial value - the passed *final* value as the final value This method will croak if *animation* does not have an object set. ### animation = $animation-\>bind\_interval ($property\_name, $interval) - • `$property_name` (string) - • `$interval` (Clutter::Interval) ### $animation-\>completed Emits the *completed* signal on *animation* ### integer = $animation-\>get\_duration Gets the duration set using *Clutter::Animation::set\_duration()* ### $animation-\>set\_duration ($msecs) - • `$msecs` (integer) Sets the duration of *animation*, in milliseconds ### boolean = $animation-\>has\_property ($property\_name) - • `$property_name` (string) ### interval = $animation-\>get\_interval ($property\_name) - • `$property_name` (string) ### boolean = $animation-\>get\_loop Retrieves whether *animation* is looping or not ### $animation-\>set\_loop ($loop) - • `$loop` (boolean) Sets whether *animation* should loop. A looping animation will never emit the *completed* signal ### scalar = $animation-\>get\_mode Retrieves the easing mode as set using *Clutter::Animation::set\_mode()* ### $animation-\>set\_mode ($mode) - • `$mode` (scalar) Sets the easing mode of *animation*. The easing mode can either be a value of the Clutter::AnimationMode enumeration or the logical id returned by *Clutter::Alpha::register\_func()* for custom easing modes ### object = $animation-\>get\_object Retrieves the object set using *Clutter::Animation::set\_object()* ### $animation-\>set\_object ($object) - • `$object` (Glib::Object) Sets the object to be animated. The *object* must be set before calling *Clutter::Animation::bind()* or *Clutter::Animation::bind\_interval()* ### timeline = $animation-\>get\_timeline ### $animation-\>set\_timeline ($timeline) - • `$timeline` (Clutter::Timeline) ### $animation-\>unbind\_property ($property\_name) - • `$property_name` (string) ### $animation-\>update\_interval ($property\_name, $interval) - • `$property_name` (string) - • `$interval` (Clutter::Interval) ## PROPERTIES - 'alpha' (Clutter::Alpha : readable / writable / private) The alpha used by the animation - 'duration' (Glib::UInt : readable / writable / private) Duration of the animation, in milliseconds - 'loop' (boolean : readable / writable / private) Whether the animation should loop - 'mode' (Glib::ULong : readable / writable / private) The mode of the animation - 'object' (Glib::Object : readable / writable / private) Object to which the animation applies - 'timeline' (Clutter::Timeline : readable / writable / private) The timeline used by the animation ## SIGNALS - **completed** (Clutter::Animation) - **started** (Clutter::Animation) ## ENUMS AND FLAGS ### enum Clutter::AnimationMode - • 'custom-mode' / 'CLUTTER\_CUSTOM\_MODE' - • 'linear' / 'CLUTTER\_LINEAR' - • 'ease-in-quad' / 'CLUTTER\_EASE\_IN\_QUAD' - • 'ease-out-quad' / 'CLUTTER\_EASE\_OUT\_QUAD' - • 'ease-in-out-quad' / 'CLUTTER\_EASE\_IN\_OUT\_QUAD' - • 'ease-in-cubic' / 'CLUTTER\_EASE\_IN\_CUBIC' - • 'ease-out-cubic' / 'CLUTTER\_EASE\_OUT\_CUBIC' - • 'ease-in-out-cubic' / 'CLUTTER\_EASE\_IN\_OUT\_CUBIC' - • 'ease-in-quart' / 'CLUTTER\_EASE\_IN\_QUART' - • 'ease-out-quart' / 'CLUTTER\_EASE\_OUT\_QUART' - • 'ease-in-out-quart' / 'CLUTTER\_EASE\_IN\_OUT\_QUART' - • 'ease-in-quint' / 'CLUTTER\_EASE\_IN\_QUINT' - • 'ease-out-quint' / 'CLUTTER\_EASE\_OUT\_QUINT' - • 'ease-in-out-quint' / 'CLUTTER\_EASE\_IN\_OUT\_QUINT' - • 'ease-in-sine' / 'CLUTTER\_EASE\_IN\_SINE' - • 'ease-out-sine' / 'CLUTTER\_EASE\_OUT\_SINE' - • 'ease-in-out-sine' / 'CLUTTER\_EASE\_IN\_OUT\_SINE' - • 'ease-in-expo' / 'CLUTTER\_EASE\_IN\_EXPO' - • 'ease-out-expo' / 'CLUTTER\_EASE\_OUT\_EXPO' - • 'ease-in-out-expo' / 'CLUTTER\_EASE\_IN\_OUT\_EXPO' - • 'ease-in-circ' / 'CLUTTER\_EASE\_IN\_CIRC' - • 'ease-out-circ' / 'CLUTTER\_EASE\_OUT\_CIRC' - • 'ease-in-out-circ' / 'CLUTTER\_EASE\_IN\_OUT\_CIRC' - • 'ease-in-elastic' / 'CLUTTER\_EASE\_IN\_ELASTIC' - • 'ease-out-elastic' / 'CLUTTER\_EASE\_OUT\_ELASTIC' - • 'ease-in-out-elastic' / 'CLUTTER\_EASE\_IN\_OUT\_ELASTIC' - • 'ease-in-back' / 'CLUTTER\_EASE\_IN\_BACK' - • 'ease-out-back' / 'CLUTTER\_EASE\_OUT\_BACK' - • 'ease-in-out-back' / 'CLUTTER\_EASE\_IN\_OUT\_BACK' - • 'ease-in-bounce' / 'CLUTTER\_EASE\_IN\_BOUNCE' - • 'ease-out-bounce' / 'CLUTTER\_EASE\_OUT\_BOUNCE' - • 'ease-in-out-bounce' / 'CLUTTER\_EASE\_IN\_OUT\_BOUNCE' - • 'animation-last' / 'CLUTTER\_ANIMATION\_LAST' ## SEE ALSO Clutter::Timeline, Clutter::Alpha, Clutter::Behaviour, Clutter::Interval, Clutter::Actor. ## 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.