Clutter Reference Manual: Implicit Animations

## Implicit Animations Implicit Animations — Simple implicit animations |

## Functions

ClutterAnimation * | clutter_animation_new ()
void | clutter_animation_set_object ()
GObject * | clutter_animation_get_object ()
void | clutter_animation_set_mode ()
gulong | clutter_animation_get_mode ()
void | clutter_animation_set_duration ()
guint | clutter_animation_get_duration ()
void | clutter_animation_set_loop ()
gboolean | clutter_animation_get_loop ()
void | clutter_animation_set_timeline ()
ClutterTimeline * | clutter_animation_get_timeline ()
void | clutter_animation_set_alpha ()
ClutterAlpha * | clutter_animation_get_alpha ()
void | clutter_animation_completed ()
ClutterAnimation * | clutter_animation_bind ()
ClutterAnimation * | clutter_animation_bind_interval ()
ClutterAnimation * | clutter_animation_update ()
void | clutter_animation_update_interval ()
gboolean | clutter_animation_has_property ()
void | clutter_animation_unbind_property ()
ClutterInterval * | clutter_animation_get_interval ()
ClutterAnimation * | clutter_actor_animate ()
ClutterAnimation * | clutter_actor_animate_with_timeline ()
ClutterAnimation * | clutter_actor_animate_with_alpha ()
ClutterAnimation * | clutter_actor_animatev ()
ClutterAnimation * | clutter_actor_animate_with_timelinev ()
ClutterAnimation * | clutter_actor_animate_with_alphav ()
ClutterAnimation * | clutter_actor_get_animation ()
void | clutter_actor_detach_animation ()

## Properties

ClutterAlpha * | alpha | Read / Write
guint | duration | Read / Write
gboolean | loop | Read / Write
gulong | mode | Read / Write
GObject * | object | Read / Write
ClutterTimeline * | timeline | Read / Write

## Signals

void | completed | Run Last
void | started | Run Last

## Types and Values

| ClutterAnimation
struct | ClutterAnimationClass

## Object Hierarchy

        GObject
        ╰── ClutterAnimation

## Implemented Interfaces

ClutterAnimation implements ClutterScriptable.

## Description

ClutterAnimation is an object providing simple, implicit animations for GObjects.

ClutterAnimation instances will bind one or more GObject properties belonging to a GObject to a ClutterInterval, and will then use a ClutterAlpha 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()`.

If you want to control the animation you should retrieve the ClutterTimeline using `clutter_animation_get_timeline()` and then use ClutterTimeline functions like `clutter_timeline_start()`, `clutter_timeline_pause()` or `clutter_timeline_stop()`.

A ClutterAnimation will emit the “completed” signal when the ClutterTimeline used by the animation is completed; unlike ClutterTimeline, though, the “completed” will not be emitted if “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 GObject instance bound to a ClutterAnimation implements the ClutterAnimatable interface it is possible for that instance to control the way the initial and final states are interpolated.

ClutterAnimations are distinguished from ClutterBehaviours because the former can only control GObject properties of a single GObject instance, while the latter can control multiple properties using accessor functions inside the ClutterBehaviour `alpha_notify` virtual function, and can control multiple ClutterActors as well.

For convenience, it is possible to use the `clutter_actor_animate()` function call which will take care of setting up and tearing down a ClutterAnimation instance and animate an actor between its current state and the specified final state.

ClutterAnimation is available since Clutter 1.0.

ClutterAnimation has been deprecated in Clutter 1.12.

#### Defining ClutterAnimationMode inside ClutterScript

When defining a ClutterAnimation inside a ClutterScript file or string the “mode” can be defined either using the ClutterAnimationMode enumeration values through their "nick" (the short string used inside GEnumValue), their numeric id, or using the following strings:

- easeInQuad, easeOutQuad, easeInOutQuad

- easeInCubic, easeOutCubic, easeInOutCubic

- easeInQuart, easeOutQuart, easeInOutQuart

- easeInQuint, easeOutQuint, easeInOutQuint

- easeInSine, easeOutSine, easeInOutSine

- easeInExpo, easeOutExpo, easeInOutExpo

- easeInCirc, easeOutCirc, easeInOutCirc

- easeInElastic, easeOutElastic, easeInOutElastic

- easeInBack, easeOutBack, easeInOutBack

- easeInBounce, easeOutBounce, easeInOutBounce

## Functions

### clutter_animation_new ()

    ClutterAnimation *
    clutter_animation_new (void);

`clutter_animation_new` has been deprecated since version 1.12 and should not be used in newly-written code.

Use ClutterPropertyTransition instead

Creates a new ClutterAnimation instance. You should set the GObject to be animated using `clutter_animation_set_object()`, set the duration with `clutter_animation_set_duration()` and the easing mode using `clutter_animation_set_mode()`.

Use `clutter_animation_bind()` or `clutter_animation_bind_interval()` to define the properties to be animated. The interval and the animated properties can be updated at runtime.

The `clutter_actor_animate()` and relative family of functions provide an easy way to animate a ClutterActor and automatically manage the lifetime of a ClutterAnimation instance, so you should consider using those functions instead of manually creating an animation.

#### Returns

the newly created ClutterAnimation. Use `g_object_unref()` to release the associated resources

Since 1.0

### clutter_animation_set_object ()

    void
    clutter_animation_set_object (ClutterAnimation *animation,
                                  GObject *object);

`clutter_animation_set_object` has been deprecated since version 1.12 and should not be used in newly-written code.

Use ClutterPropertyTransition instead

Attaches `animation` to `object` . The ClutterAnimation will take a reference on `object` .

#### Parameters

animation | a ClutterAnimation |
object | a GObject |

Since 1.0

### clutter_animation_get_object ()

    GObject *
    clutter_animation_get_object (ClutterAnimation *animation);

`clutter_animation_get_object` has been deprecated since version 1.12 and should not be used in newly-written code.

Use ClutterPropertyTransition instead

Retrieves the GObject attached to `animation` .

#### Parameters

animation | a ClutterAnimation |

#### Returns

a GObject.

[transfer none]

Since 1.0

### clutter_animation_set_mode ()

    void
    clutter_animation_set_mode (ClutterAnimation *animation,
                                gulong mode);

`clutter_animation_set_mode` has been deprecated since version 1.12 and should not be used in newly-written code.

Use ClutterPropertyTransition instead

Sets the animation `mode` of `animation` . The animation `mode` is a logical id, either coming from the ClutterAnimationMode enumeration or the return value of `clutter_alpha_register_func()`.

This function will also set “alpha” if needed.

#### Parameters

animation | a ClutterAnimation |
mode | an animation mode logical id |

Since 1.0

### clutter_animation_get_mode ()

    gulong
    clutter_animation_get_mode (ClutterAnimation *animation);

`clutter_animation_get_mode` has been deprecated since version 1.12 and should not be used in newly-written code.

Use ClutterPropertyTransition instead

Retrieves the animation mode of `animation` , as set by `clutter_animation_set_mode()`.

#### Parameters

animation | a ClutterAnimation |

#### Returns

the mode for the animation

Since 1.0

### clutter_animation_set_duration ()

    void
    clutter_animation_set_duration (ClutterAnimation *animation,
                                    guint msecs);

`clutter_animation_set_duration` has been deprecated since version 1.12 and should not be used in newly-written code.

Use ClutterPropertyTransition instead

Sets the duration of `animation` in milliseconds.

This function will set “alpha” and “timeline” if needed.

#### Parameters

animation | a ClutterAnimation |
msecs | the duration in milliseconds |

Since 1.0

### clutter_animation_get_duration ()

    guint
    clutter_animation_get_duration (ClutterAnimation *animation);

`clutter_animation_get_duration` has been deprecated since version 1.12 and should not be used in newly-written code.

Use ClutterPropertyTransition instead

Retrieves the duration of `animation` , in milliseconds.

#### Parameters

animation | a ClutterAnimation |

#### Returns

the duration of the animation

Since 1.0

### clutter_animation_set_loop ()

    void
    clutter_animation_set_loop (ClutterAnimation *animation,
                                gboolean loop);

`clutter_animation_set_loop` has been deprecated since version 1.12 and should not be used in newly-written code.

Use ClutterPropertyTransition instead

Sets whether `animation` should loop over itself once finished.

A looping ClutterAnimation will not emit the “completed” signal when finished.

This function will set “alpha” and “timeline” if needed.

#### Parameters

animation | a ClutterAnimation |
loop | `TRUE` if the animation should loop |

Since 1.0

### clutter_animation_get_loop ()

    gboolean
    clutter_animation_get_loop (ClutterAnimation *animation);

`clutter_animation_get_loop` has been deprecated since version 1.12 and should not be used in newly-written code.

Use ClutterPropertyTransition instead

Retrieves whether `animation` is looping.

#### Parameters

animation | a ClutterAnimation |

#### Returns

`TRUE` if the animation is looping

Since 1.0

### clutter_animation_set_timeline ()

    void
    clutter_animation_set_timeline (ClutterAnimation *animation,
                                    ClutterTimeline *timeline);

`clutter_animation_set_timeline` has been deprecated since version 1.12 and should not be used in newly-written code.

Use ClutterPropertyTransition instead

Sets the ClutterTimeline used by `animation` .

This function will take a reference on the passed `timeline` .

#### Parameters

animation | a ClutterAnimation |
timeline | a ClutterTimeline, or `NULL` to unset the current ClutterTimeline. | [allow-none]

Since 1.0

### clutter_animation_get_timeline ()

    ClutterTimeline *
    clutter_animation_get_timeline (ClutterAnimation *animation);

`clutter_animation_get_timeline` has been deprecated since version 1.12 and should not be used in newly-written code.

Use ClutterPropertyTransition instead

Retrieves the ClutterTimeline used by `animation`

#### Parameters

animation | a ClutterAnimation |

#### Returns

the timeline used by the animation.

[transfer none]

Since 1.0

### clutter_animation_set_alpha ()

    void
    clutter_animation_set_alpha (ClutterAnimation *animation,
                                 ClutterAlpha *alpha);

`clutter_animation_set_alpha` has been deprecated since version 1.10 and should not be used in newly-written code.

Use `clutter_animation_get_timeline()` and `clutter_timeline_set_progress_mode()` instead.

Sets `alpha` as the ClutterAlpha used by `animation` .

If `alpha` is not `NULL`, the ClutterAnimation will take ownership of the ClutterAlpha instance.

#### Parameters

animation | a ClutterAnimation |
alpha | a ClutterAlpha, or `NULL` to unset the current ClutterAlpha |

Since 1.0

### clutter_animation_get_alpha ()

    ClutterAlpha *
    clutter_animation_get_alpha (ClutterAnimation *animation);

`clutter_animation_get_alpha` has been deprecated since version 1.10 and should not be used in newly-written code.

Use `clutter_animation_get_timeline()` and `clutter_timeline_get_progress_mode()` instead.

Retrieves the ClutterAlpha used by `animation` .

#### Parameters

animation | a ClutterAnimation |

#### Returns

the alpha object used by the animation.

[transfer none]

Since 1.0

### clutter_animation_completed ()

    void
    clutter_animation_completed (ClutterAnimation *animation);

`clutter_animation_completed` has been deprecated since version 1.12 and should not be used in newly-written code.

Use ClutterPropertyTransition instead

Emits the ::completed signal on `animation`

When using this function with a ClutterAnimation created by the `clutter_actor_animate()` family of functions, `animation` will be unreferenced and it will not be valid anymore, unless `g_object_ref()` was called before calling this function or unless a reference was taken inside a handler for the “completed” signal

#### Parameters

animation | a ClutterAnimation |

Since 1.0

### clutter_animation_bind ()

    ClutterAnimation *
    clutter_animation_bind (ClutterAnimation *animation,
                            const gchar *property_name,
                            const GValue *final);

`clutter_animation_bind` has been deprecated since version 1.12 and should not be used in newly-written code.

Use ClutterPropertyTransition instead

Adds a single property with name `property_name` to the animation `animation` . For more information about animations, see `clutter_actor_animate()`.

This method returns the animation primarily to make chained calls convenient in language bindings.

#### Parameters

animation | a ClutterAnimation |
property_name | the property to control |
final | The final value of the property |

#### Returns

The animation itself.

[transfer none]

Since 1.0

### clutter_animation_bind_interval ()

    ClutterAnimation *
    clutter_animation_bind_interval (ClutterAnimation *animation,
                                     const gchar *property_name,
                                     ClutterInterval *interval);

`clutter_animation_bind_interval` has been deprecated since version 1.12 and should not be used in newly-written code.

Use ClutterPropertyTransition instead

Binds `interval` to the `property_name` of the GObject attached to `animation` . The ClutterAnimation will take ownership of the passed ClutterInterval. For more information about animations, see `clutter_actor_animate()`.

If you need to update the interval instance use `clutter_animation_update_interval()` instead.

#### Parameters

animation | a ClutterAnimation |
property_name | the property to control |
interval | a ClutterInterval. | [transfer full]

#### Returns

The animation itself.

[transfer none]

Since 1.0

### clutter_animation_update ()

    ClutterAnimation *
    clutter_animation_update (ClutterAnimation *animation,
                              const gchar *property_name,
                              const GValue *final);

`clutter_animation_update` has been deprecated since version 1.12 and should not be used in newly-written code.

Use ClutterPropertyTransition instead

Updates the `final` value of the interval for `property_name`

#### Parameters

animation | a ClutterAnimation |
property_name | name of the property |
final | The final value of the property |

#### Returns

The animation itself.

[transfer none]

Since 1.0

### clutter_animation_update_interval ()

    void
    clutter_animation_update_interval (ClutterAnimation *animation,
                                       const gchar *property_name,
                                       ClutterInterval *interval);

`clutter_animation_update_interval` has been deprecated since version 1.12 and should not be used in newly-written code.

Use ClutterPropertyTransition instead

Changes the `interval` for `property_name` . The ClutterAnimation will take ownership of the passed ClutterInterval.

#### Parameters

animation | a ClutterAnimation |
property_name | name of the property |
interval | a ClutterInterval |

Since 1.0

### clutter_animation_has_property ()

    gboolean
    clutter_animation_has_property (ClutterAnimation *animation,
                                    const gchar *property_name);

`clutter_animation_has_property` has been deprecated since version 1.12 and should not be used in newly-written code.

Use ClutterPropertyTransition instead

Checks whether `animation` is controlling `property_name` .

#### Parameters

animation | a ClutterAnimation |
property_name | name of the property |

#### Returns

`TRUE` if the property is animated by the ClutterAnimation, `FALSE` otherwise

Since 1.0

### clutter_animation_unbind_property ()

    void
    clutter_animation_unbind_property (ClutterAnimation *animation,
                                       const gchar *property_name);

`clutter_animation_unbind_property` has been deprecated since version 1.12 and should not be used in newly-written code.

Use ClutterPropertyTransition instead

Removes `property_name` from the list of animated properties.

#### Parameters

animation | a ClutterAnimation |
property_name | name of the property |

Since 1.0

### clutter_animation_get_interval ()

    ClutterInterval *
    clutter_animation_get_interval (ClutterAnimation *animation,
                                    const gchar *property_name);

`clutter_animation_get_interval` has been deprecated since version 1.12 and should not be used in newly-written code.

Use ClutterPropertyTransition instead

Retrieves the ClutterInterval associated to `property_name` inside `animation` .

#### Parameters

animation | a ClutterAnimation |
property_name | name of the property |

#### Returns

a ClutterInterval or `NULL` if no property with the same name was found. The returned interval is owned by the ClutterAnimation and should not be unreferenced.

[transfer none]

Since 1.0

### clutter_actor_animate ()

    ClutterAnimation *
    clutter_actor_animate (ClutterActor *actor,
                           gulong mode,
                           guint duration,
                           const gchar *first_property_name,
                           ...);

`clutter_actor_animate` has been deprecated since version 1.12 and should not be used in newly-written code.

Use the implicit transition for animatable properties in ClutterActor instead.

Animates the given list of properties of `actor` between the current value for each property and a new final value. The animation has a definite duration and a speed given by the `mode` .

For example, this:

    1
    2
    3
    4
    clutter_actor_animate (rectangle, CLUTTER_LINEAR, 250,
                           "width", 100.0,
                           "height", 100.0,
                           NULL);

will make width and height properties of the ClutterActor "rectangle" grow linearly between the current value and 100 pixels, in 250 milliseconds.

The animation `mode` is a logical id, either from the ClutterAnimationMode enumeration of from `clutter_alpha_register_func()`.

All the properties specified will be animated between the current value and the final value. If a property should be set at the beginning of the animation but not updated during the animation, it should be prefixed by the "fixed::" string, for instance:

    1
    2
    3
    4
    clutter_actor_animate (actor, CLUTTER_EASE_IN_SINE, 100,
                           "rotation-angle-z", 360.0,
                           "fixed::rotation-center-z", &center,
                           NULL);

Will animate the "rotation-angle-z" property between the current value and 360 degrees, and set the "rotation-center-z" property to the fixed value of the ClutterVertex "center".

This function will implicitly create a ClutterAnimation object which will be assigned to the `actor` and will be returned to the developer to control the animation or to know when the animation has been completed.

If a name argument starts with "signal::", "signal-after::", "signal-swapped::" or "signal-swapped-after::" the two following arguments are used as callback function and data for a signal handler installed on the ClutterAnimation object for the specified signal name, for instance:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    static void
    on_animation_completed (ClutterAnimation *animation,
                            ClutterActor     *actor)
    {
      clutter_actor_hide (actor);
    }

    clutter_actor_animate (actor, CLUTTER_EASE_IN_CUBIC, 100,
                           "opacity", 0,
                           "signal::completed", on_animation_completed, actor,
                           NULL);

or, to automatically destroy an actor at the end of the animation:

    1
    2
    3
    4
    5
    6
    clutter_actor_animate (actor, CLUTTER_EASE_IN_CUBIC, 100,
                           "opacity", 0,
                           "signal-swapped-after::completed",
                             clutter_actor_destroy,
                             actor,
                           NULL);

The "signal::" modifier is the equivalent of using `g_signal_connect()`; the "signal-after::" modifier is the equivalent of using `g_signal_connect_after()` or `g_signal_connect_data()` with the `G_CONNECT_AFTER`; the "signal-swapped::" modifier is the equivalent of using `g_signal_connect_swapped()` or `g_signal_connect_data()` with the `G_CONNECT_SWAPPED` flah; finally, the "signal-swapped-after::" modifier is the equivalent of using `g_signal_connect_data()` with both the `G_CONNECT_AFTER` and `G_CONNECT_SWAPPED` flags. The `clutter_actor_animate()` function will not keep track of multiple connections to the same signal, so it is your responsability to avoid them when calling `clutter_actor_animate()` multiple times on the same actor.

Calling this function on an actor that is already being animated will cause the current animation to change with the new final values, the new easing mode and the new duration - that is, this code:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    clutter_actor_animate (actor, CLUTTER_LINEAR, 250,
                           "width", 100.0,
                           "height", 100.0,
                           NULL);
    clutter_actor_animate (actor, CLUTTER_EASE_IN_CUBIC, 500,
                           "x", 100.0,
                           "y", 100.0,
                           "width", 200.0,
                           NULL);

is the equivalent of:

    1
    2
    3
    4
    5
    6
    clutter_actor_animate (actor, CLUTTER_EASE_IN_CUBIC, 500,
                           "x", 100.0,
                           "y", 100.0,
                           "width", 200.0,
                           "height", 100.0,
                           NULL);

Unless the animation is looping, the ClutterAnimation created by `clutter_actor_animate()` will become invalid as soon as it is complete.

Since the created ClutterAnimation instance attached to `actor` is guaranteed to be valid throughout the “completed” signal emission chain, you will not be able to create a new animation using `clutter_actor_animate()` on the same `actor` from within the “completed” signal handler unless you use `g_signal_connect_after()` to connect the callback function, for instance:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    static void
    on_animation_completed (ClutterAnimation *animation,
                            ClutterActor     *actor)
    {
      clutter_actor_animate (actor, CLUTTER_EASE_OUT_CUBIC, 250,
                             "x", 500.0,
                             "y", 500.0,
                             NULL);
    }

      ...
      animation = clutter_actor_animate (actor, CLUTTER_EASE_IN_CUBIC, 250,
                                         "x", 100.0,
                                         "y", 100.0,
                                         NULL);
      g_signal_connect (animation, "completed",
                        G_CALLBACK (on_animation_completed),
                        actor);
      ...

#### Parameters

actor | a ClutterActor |
mode | an animation mode logical id |
duration | duration of the animation, in milliseconds |
first_property_name | the name of a property |
... | a `NULL` terminated list of property names and property values |

#### Returns

a ClutterAnimation object. The object is owned by the ClutterActor and should not be unreferenced with `g_object_unref()`.

[transfer none]

Since 1.0

### clutter_actor_animate_with_timeline ()

    ClutterAnimation *
    clutter_actor_animate_with_timeline (ClutterActor *actor,
                                         gulong mode,
                                         ClutterTimeline *timeline,
                                         const gchar *first_property_name,
                                         ...);

`clutter_actor_animate_with_timeline` has been deprecated since version 1.12 and should not be used in newly-written code.

Use the implicit transition for animatable properties in ClutterActor instead.

Animates the given list of properties of `actor` between the current value for each property and a new final value. The animation has a definite duration given by `timeline` and a speed given by the `mode` .

See `clutter_actor_animate()` for further details.

This function is useful if you want to use an existing timeline to animate `actor` .

#### Parameters

actor | a ClutterActor |
mode | an animation mode logical id |
timeline | a ClutterTimeline |
first_property_name | the name of a property |
... | a `NULL` terminated list of property names and property values |

#### Returns

a ClutterAnimation object. The object is owned by the ClutterActor and should not be unreferenced with `g_object_unref()`.

[transfer none]

Since 1.0

### clutter_actor_animate_with_alpha ()

    ClutterAnimation *
    clutter_actor_animate_with_alpha (ClutterActor *actor,
                                      ClutterAlpha *alpha,
                                      const gchar *first_property_name,
                                      ...);

`clutter_actor_animate_with_alpha` has been deprecated since version 1.10 and should not be used in newly-written code.

Use `clutter_actor_animate_with_timeline()` instead

Animates the given list of properties of `actor` between the current value for each property and a new final value. The animation has a definite behaviour given by the passed `alpha` .

See `clutter_actor_animate()` for further details.

This function is useful if you want to use an existing ClutterAlpha to animate `actor` .

#### Parameters

actor | a ClutterActor |
alpha | a ClutterAlpha |
first_property_name | the name of a property |
... | a `NULL` terminated list of property names and property values |

#### Returns

a ClutterAnimation object. The object is owned by the ClutterActor and should not be unreferenced with `g_object_unref()`.

[transfer none]

Since 1.0

### clutter_actor_animatev ()

    ClutterAnimation *
    clutter_actor_animatev (ClutterActor *actor,
                            gulong mode,
                            guint duration,
                            gint n_properties,
                            const gchar * const properties[],
                            const GValue *values);

`clutter_actor_animatev` has been deprecated since version 1.12 and should not be used in newly-written code.

Use the implicit transition for animatable properties in ClutterActor instead.

Animates the given list of properties of `actor` between the current value for each property and a new final value. The animation has a definite duration and a speed given by the `mode` .

This is the vector-based variant of `clutter_actor_animate()`, useful for language bindings.

Unlike `clutter_actor_animate()`, this function will not allow you to specify "signal::" names and callbacks.

#### Parameters

actor | a ClutterActor |
mode | an animation mode logical id |
duration | duration of the animation, in milliseconds |
n_properties | number of property names and values |
properties | a vector containing the property names to set. | [array length=n_properties][element-type utf8]
values | a vector containing the property values to set. | [array length=n_properties]

#### Returns

a ClutterAnimation object. The object is owned by the ClutterActor and should not be unreferenced with `g_object_unref()`.

[transfer none]

Since 1.0

### clutter_actor_animate_with_timelinev ()

    ClutterAnimation *
    clutter_actor_animate_with_timelinev (ClutterActor *actor,
                                          gulong mode,
                                          ClutterTimeline *timeline,
                                          gint n_properties,
                                          const gchar * const properties[],
                                          const GValue *values);

`clutter_actor_animate_with_timelinev` has been deprecated since version 1.12 and should not be used in newly-written code.

Use the implicit transition for animatable properties in ClutterActor instead.

Animates the given list of properties of `actor` between the current value for each property and a new final value. The animation has a definite duration given by `timeline` and a speed given by the `mode` .

See `clutter_actor_animate()` for further details.

This function is useful if you want to use an existing timeline to animate `actor` .

This is the vector-based variant of `clutter_actor_animate_with_timeline()`, useful for language bindings.

Unlike `clutter_actor_animate_with_timeline()`, this function will not allow you to specify "signal::" names and callbacks.

#### Parameters

actor | a ClutterActor |
mode | an animation mode logical id |
timeline | a ClutterTimeline |
n_properties | number of property names and values |
properties | a vector containing the property names to set. | [array length=n_properties][element-type utf8]
values | a vector containing the property values to set. | [array length=n_properties]

#### Returns

a ClutterAnimation object. The object is owned by the ClutterActor and should not be unreferenced with `g_object_unref()`.

[transfer none]

Since 1.0

### clutter_actor_animate_with_alphav ()

    ClutterAnimation *
    clutter_actor_animate_with_alphav (ClutterActor *actor,
                                       ClutterAlpha *alpha,
                                       gint n_properties,
                                       const gchar * const properties[],
                                       const GValue *values);

`clutter_actor_animate_with_alphav` has been deprecated since version 1.10 and should not be used in newly-written code.

Use `clutter_actor_animate_with_timelinev()` instead

Animates the given list of properties of `actor` between the current value for each property and a new final value. The animation has a definite behaviour given by the passed `alpha` .

See `clutter_actor_animate()` for further details.

This function is useful if you want to use an existing ClutterAlpha to animate `actor` .

This is the vector-based variant of `clutter_actor_animate_with_alpha()`, useful for language bindings.

Unlike `clutter_actor_animate_with_alpha()`, this function will not allow you to specify "signal::" names and callbacks.

#### Parameters

actor | a ClutterActor |
alpha | a ClutterAlpha |
n_properties | number of property names and values |
properties | a vector containing the property names to set. | [array length=n_properties][element-type utf8]
values | a vector containing the property values to set. | [array length=n_properties]

#### Returns

a ClutterAnimation object. The object is owned by the ClutterActor and should not be unreferenced with `g_object_unref()`.

[transfer none]

Since 1.0

### clutter_actor_get_animation ()

    ClutterAnimation *
    clutter_actor_get_animation (ClutterActor *actor);

`clutter_actor_get_animation` has been deprecated since version 1.12 and should not be used in newly-written code.

Use the implicit transition for animatable properties in ClutterActor instead, and `clutter_actor_get_transition()` to retrieve the transition.

Retrieves the ClutterAnimation used by `actor` , if `clutter_actor_animate()` has been called on `actor` .

#### Parameters

actor | a ClutterActor |

#### Returns

a ClutterAnimation, or `NULL`.

[transfer none]

Since 1.0

### clutter_actor_detach_animation ()

    void
    clutter_actor_detach_animation (ClutterActor *actor);

`clutter_actor_detach_animation` has been deprecated since version 1.12 and should not be used in newly-written code.

Use the implicit transition for animatable properties in ClutterActor instead, and `clutter_actor_remove_transition()` to remove the transition.

Detaches the ClutterAnimation used by `actor` , if `clutter_actor_animate()` has been called on `actor` .

Once the animation has been detached, it loses a reference. If it was the only reference then the ClutterAnimation becomes invalid.

The “completed” signal will not be emitted.

#### Parameters

actor | a ClutterActor |

Since 1.4

## Types and Values

### ClutterAnimation

    typedef struct _ClutterAnimation ClutterAnimation;

The ClutterAnimation structure contains only private data and should be accessed using the provided functions.

Since 1.0

### struct ClutterAnimationClass

    struct ClutterAnimationClass {
      void (* started)   (ClutterAnimation *animation);
      void (* completed) (ClutterAnimation *animation);
    };

The ClutterAnimationClass structure contains only private data and should be accessed using the provided functions.

#### Members

`started` () | class handler for the “started” signal |
`completed` () | class handler for the “completed” signal |

Since 1.0

## Property Details

### The `“alpha”` property

      “alpha”                    ClutterAlpha *

The ClutterAlpha used by the animation.

`ClutterAnimation:alpha` has been deprecated since version 1.10 and should not be used in newly-written code.

Use the “timeline” property and the “progress-mode” property instead.

Flags: Read / Write

Since 1.0

### The `“duration”` property

      “duration”                 guint

The duration of the animation, expressed in milliseconds.

`ClutterAnimation:duration` has been deprecated since version 1.12 and should not be used in newly-written code.

Use ClutterPropertyTransition instead

Flags: Read / Write

Default value: 0

Since 1.0

### The `“loop”` property

      “loop”                     gboolean

Whether the animation should loop.

`ClutterAnimation:loop` has been deprecated since version 1.12 and should not be used in newly-written code.

Use ClutterPropertyTransition instead

Flags: Read / Write

Default value: FALSE

Since 1.0

### The `“mode”` property

      “mode”                     gulong

The animation mode, either a value from ClutterAnimationMode or a value returned by `clutter_alpha_register_func()`. The default value is `CLUTTER_LINEAR`.

`ClutterAnimation:mode` has been deprecated since version 1.12 and should not be used in newly-written code.

Use ClutterPropertyTransition instead

Flags: Read / Write

Since 1.0

### The `“object”` property

      “object”                   GObject *

The GObject to which the animation applies.

`ClutterAnimation:object` has been deprecated since version 1.12 and should not be used in newly-written code.

Use ClutterPropertyTransition instead

Flags: Read / Write

Since 1.0

### The `“timeline”` property

      “timeline”                 ClutterTimeline *

The ClutterTimeline used by the animation.

`ClutterAnimation:timeline` has been deprecated since version 1.12 and should not be used in newly-written code.

Use ClutterPropertyTransition instead

Flags: Read / Write

Since 1.0

## Signal Details

### The `“completed”` signal

    void
    user_function (ClutterAnimation *animation,
                   gpointer          user_data)

The ::completed signal is emitted once the animation has been completed.

The `animation` instance is guaranteed to be valid for the entire duration of the signal emission chain.

`ClutterAnimation::completed` has been deprecated since version 1.12 and should not be used in newly-written code.

Use ClutterPropertyTransition instead

#### Parameters

animation | the animation that emitted the signal |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since 1.0

### The `“started”` signal

    void
    user_function (ClutterAnimation *animation,
                   gpointer          user_data)

The ::started signal is emitted once the animation has been started

`ClutterAnimation::started` has been deprecated since version 1.12 and should not be used in newly-written code.

Use ClutterPropertyTransition instead

#### Parameters

animation | the animation that emitted the signal |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since 1.0

## See Also

ClutterAnimatable, ClutterInterval, ClutterAlpha, ClutterTimeline