animate

Warning: animate is deprecated since 1.12.

Animates the given list of properties of this 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:

  clutter_actor_animate (rectangle, CLUTTER_LINEAR, 250,
                         "width", 100.0,
                         "height", 100.0,
                         NULL);

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

The animation mode is a logical id, either from the AnimationMode enumeration of from 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:

  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 Vertex "center".

This function will implicitly create a Animation object which will be assigned to the this 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 Animation object for the specified signal name, for instance:

  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:

  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 connect; the "signal-after::" modifier is the equivalent of using connect_after or connect_data with the AFTER; the "signal-swapped::" modifier is the equivalent of using connect_swapped or connect_data with the SWAPPED flah; finally, the "signal-swapped-after::" modifier is the equivalent of using connect_data with both the AFTER and SWAPPED flags. The animate function will not keep track of multiple connections to the same signal, so it is your responsability to avoid them when calling 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:

  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:

  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 Animation created by animate will become invalid as soon as it is complete.

Since the created Animation instance attached to this is guaranteed to be valid throughout the completed signal emission chain, you will not be able to create a new animation using animate on the same this from within the completed signal handler unless you use connect_after to connect the callback function, for instance:

  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:

this	a Actor
mode	an animation mode logical id
duration	duration of the animation, in milliseconds
...	a null terminated list of property names and property values
first_property_name	the name of a property

Returns:

a Animation object. The object is owned by the Actor and should not be unreferenced with unref