## Migrating from ClutterEffect

### Emmanuele Bassi

`<ebassi`linux.intel.com`>`

Since version 1.0, Clutter provides the ClutterAnimation API and the `clutter_actor_animate()` family of functions as replacements for the ClutterEffectTemplate and clutter_effect_* API for creating simple, one-off animations.

## Using ``clutter_actor_animate()``

Prior to Clutter 1.0, the way to create simple, one-off animations involving a single actor was the ClutterEffect API. The major downside of this API was that to abstract the duration and easing function of the animation the application developer had to create a ClutterEffectTemplate and keep it around for the duration of the application.

The `clutter_actor_animate()` function performs all of the memory management that was delegated to the ClutterEffectTemplate, freeing the developer from having to deal with object bookkeeping.

Another downside of the ClutterEffect API is that every possible animation has its own function (scaling, opacity, rotation, movement, etc.), and new functions cannot be added outside of Clutter.

Example 1. Effect example

The following code shows a simple animation using the ClutterEffect API. It animates an actor linearly in 500 milliseconds, by moving it to the (100, 100) coordinates while fading it out.

      ClutterEffectTemplate *tmpl;

      tmpl = clutter_effect_template_new_for_duration (500, clutter_ramp_inc_func);
      clutter_effect_move (tmpl, actor, 100, 100, NULL, NULL);
      clutter_effect_fade (tmpl, actor, 0, NULL, NULL);

      g_object_unref (tmpl);

The `clutter_actor_animate()` function will implicitely create a ClutterAnimation with the passed duration and easing mode, and will bind all the passed properties. All readable and writable properties specified by a ClutterActor are animatable through `clutter_actor_animate()`.

Example 2. Animation example

The following code shows the `clutter_actor_animate()` call equivalent to the previous ClutterEffect example.

      clutter_actor_animate (actor, CLUTTER_LINEAR, 500,
                             "x", 100.0,
                             "y", 100.0,
                             "opacity", 0,
                             NULL);

The ClutterEffect API provided a way to be notified of the effect completion. Since the `clutter_actor_animate()` function creates a ClutterAnimation instance it's possible to use the “completed” signal for the same notification.

Example 3. Effect complete example

The following code shows how to receive notification of the completion of the animation.

    static void
    on_fade_complete (ClutterActor *actor,
                      gpointer      data)
    {
      clutter_actor_hide (actor);
    }

      ClutterEffectTemplate *tmpl;

      tmpl = clutter_effect_template_new_for_duration (500, clutter_ramp_inc_func);
      clutter_effect_fade (tmpl, actor, 0, on_fade_complete, NULL);

      g_object_unref (tmpl);

The `clutter_actor_animate()` function also has a convenience wrapper that allows to inline the signal connection:

Example 4. Animation completed example

The following code shows how to get the same notification as the example above.

      ClutterAnimation *animation;

      animation = clutter_actor_animate (actor, CLUTTER_LINEAR, 500,
                                         "opacity", 0,
                                         NULL);
      g_signal_connect_swapped (animation,
                                "completed", G_CALLBACK (clutter_actor_hide),
                                actor);

      /* OR */

      clutter_actor_animate (actor, CLUTTER_LINEAR, 500,
                             "opacity", 0,
                             "signal-swapped::completed", clutter_actor_hide, actor,
                             NULL);