From 24495918bbbb2b54f7ba3069690d69a6937d1426 Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Sat, 9 Jun 2012 10:08:46 +0100 Subject: [PATCH] docs: Further clarifications on implicit vs explicit animations The wording is a bit terse, so it's better to clarify it. --- clutter/clutter-actor.c | 32 ++++++++++++++++++++------------ 1 file changed, 20 insertions(+), 12 deletions(-) diff --git a/clutter/clutter-actor.c b/clutter/clutter-actor.c index 2cde2b036..f2ced6079 100644 --- a/clutter/clutter-actor.c +++ b/clutter/clutter-actor.c @@ -226,11 +226,12 @@ * will automatically transition an actor's property change between the * current state and the desired one without manual intervention, if the * property is defined to be animatable in its documentation. - * By default, in the 1.0 API series, the transition happens with - * a duration of zero milliseconds, and the implicit animation is an - * opt in feature to retain backwards compatibility. In order to enable - * implicit animations, it is necessary to change the easing state of - * an actor by using clutter_actor_save_easing_state(): + * By default, in the 1.0 API series, the transition happens + * with a duration of zero milliseconds, and the implicit animation is an + * opt in feature to retain backwards compatibility. + * Implicit animations depend on the current easing state; in order + * to use the default easing state for an actor you should call the + * clutter_actor_save_easing_state() function: * * /* assume that the actor is currently positioned at (100, 100) */ * clutter_actor_save_easing_state (actor); @@ -259,6 +260,8 @@ * and a default easing mode of %CLUTTER_EASE_OUT_CUBIC, unless you call * clutter_actor_set_easing_mode() and clutter_actor_set_easing_duration() * after changing the easing state of the actor. + * Changing the easing state will affect all the following property + * transitions, but will not affect existing transitions. * It is important to note that if you modify the state on an * animatable property while a transition is in flight, the transition's * final value will be updated, as well as its duration and progress @@ -266,17 +269,20 @@ * example: * * clutter_actor_save_easing_state (actor); + * clutter_actor_set_easing_duration (actor, 1000); * clutter_actor_set_x (actor, 200); * clutter_actor_restore_easing_state (actor); * * clutter_actor_save_easing_state (actor); + * clutter_actor_set_easing_duration (actor, 500); * clutter_actor_set_x (actor, 100); * clutter_actor_restore_easing_state (actor); * * the first call to clutter_actor_set_x() will begin a transition - * of the #ClutterActor:x property to the value of 200; the second call - * to clutter_actor_set_x() will change the transition's final value to - * 100. + * of the #ClutterActor:x property from the current value to the value of + * 200 over a duration of one second; the second call to clutter_actor_set_x() + * will change the transition's final value to 100 and the duration to 500 + * milliseconds. * It is possible to retrieve the #ClutterTransition used by the * animatable properties by using clutter_actor_get_transition() and using * the property name as the transition name. @@ -303,7 +309,10 @@ * of an actor between fully opaque and fully transparent, and back, over * a span of 3 seconds. The animation does not begin until it is added to * the actor. - * The explicit animation API applies to all #GObject properties. + * The explicit animation API applies to all #GObject properties, + * as well as the custom properties defined through the #ClutterAnimatable + * interface, regardless of whether they are defined as implicitly + * animatable or not. * The explicit animation API should also be used when using custom * animatable properties for #ClutterAction, #ClutterConstraint, and * #ClutterEffect instances associated to an actor; see the section on @@ -457,7 +466,6 @@ * ClutterActor *rect) * { * ClutterTransition *transition; - * ClutterInterval *interval; * * /* the offset that we want to apply; this will make the actor * * slide in from behind the origin and rest at the right of @@ -482,8 +490,8 @@ * clutter_timeline_set_duration (CLUTTER_TIMELINE (transition), 500); * * /* create the interval with the initial and final values */ - * interval = clutter_interval_new (G_TYPE_FLOAT, 0, new_offset); - * clutter_transition_set_interval (transition, interval); + * clutter_transition_set_from (transition, G_TYPE_FLOAT, 0.f); + * clutter_transition_set_to (transition, G_TYPE_FLOAT, new_offset); * * /* add the transition to the actor; this causes the animation * * to start. the name "offsetAnimation" can be used to retrieve