From c0adf4582ca41f046bfb67458ac1ca5d6d416f33 Mon Sep 17 00:00:00 2001
From: Emmanuele Bassi <ebassi@linux.intel.com>
Date: Thu, 26 Feb 2009 15:35:20 +0000
Subject: [PATCH] [docs] Clarify clutter_actor_animate() behaviour

When calling clutter_actor_animate() on an actor that is being
currently animated the default behaviour is to update the duration
of the animation; the easing mode; update all the common properties;
and finally add the new properties.

This:

  clutter_actor_animate (actor, 500, CLUTTER_LINEAR,
                         "width", 100,
                         "height", 100,
                         NULL);

  clutter_actor_animate (actor, 250, CLUTTER_EASE_IN_CUBIC,
                         "x", 100,
                         "y", 100,
                         "height", 200,
                         NULL);

Is logically equivalent to:

  clutter_actor_animate (actor, 250, CLUTTER_EASE_IN_CUBIC,
                         "x", 100,
                         "y", 100,
                         "width", 100,
                         "height", 200,
                         NULL);

The documentation of the function should be slightly more verbose
in describing the default behaviour.
---
 clutter/clutter-animation.c | 26 +++++++++++++++++++++++++-
 1 file changed, 25 insertions(+), 1 deletion(-)

diff --git a/clutter/clutter-animation.c b/clutter/clutter-animation.c
index e1340c333..0ff2d073e 100644
--- a/clutter/clutter-animation.c
+++ b/clutter/clutter-animation.c
@@ -1418,7 +1418,31 @@ clutter_actor_animate_with_timeline (ClutterActor    *actor,
  * completed.
  *
  * Calling this function on an actor that is already being animated
- * will cause the current animation to change with the new final value.
+ * 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, 250, CLUTTER_LINEAR,
+ *                          "width", 100,
+ *                          "height", 100,
+ *                          NULL);
+ *   clutter_actor_animate (actor, 500, CLUTTER_EASE_IN_CUBIC,
+ *                          "x", 100,
+ *                          "y", 100,
+ *                          "width", 200,
+ *                          NULL);
+ * ]|
+ *
+ * is the equivalent of:
+ *
+ * |[
+ *   clutter_actor_animate (actor, 500, CLUTTER_EASE_IN_CUBIC,
+ *                          "x", 100,
+ *                          "y", 100,
+ *                          "width", 200,
+ *                          "height", 100,
+ *                          NULL);
+ * ]|
  *
  * <note>Unless the animation is looping, it will become invalid as soon
  * as it is complete. To avoid this, you should keep a reference on the