man Clutter::Animation (3): 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'

COPYRIGHT

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.