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.

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. 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(). 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 #ClutterAnimation::completed signal for the same notification. 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: 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);