From 7af1d4b847ed86d14da87c7821c2c51fd258b087 Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Tue, 20 Mar 2012 11:55:41 +0000 Subject: [PATCH] docs: Add a section on actor animations Detail the implicit and explicit animation models used by ClutterActor. --- clutter/clutter-actor.c | 72 ++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 71 insertions(+), 1 deletion(-) diff --git a/clutter/clutter-actor.c b/clutter/clutter-actor.c index d067ae5..5f4b90d 100644 --- a/clutter/clutter-actor.c +++ b/clutter/clutter-actor.c @@ -213,6 +213,76 @@ * returning %CLUTTER_EVENT_PROPAGATE. * * + * + * Animation + * Animation is a core concept of modern user interfaces; Clutter + * provides a complete and powerful animation framework that automatically + * tweens the actor's state without requiring direct, frame by frame + * manipulation from your application code. + * + * Implicit animations + * The implicit animation model of Clutter assumes that all the + * changes in an actor state should be gradual and asynchronous; Clutter + * will automatically transition an actor's property change between the + * current state and the desired one without manual intervention. + * 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(): + * + * /* assume that the actor is currently positioned at (100, 100) */ + * clutter_actor_save_easing_state (actor); + * clutter_actor_set_position (actor, 500, 500); + * clutter_actor_restore_easing_state (actor); + * + * The example above will trigger an implicit animation of the + * actor between its current position to a new position. + * It is possible to animate multiple properties of an actor + * at the same time, and you can animate multiple actors at the same + * time as well, for instance: + * + * /* animate the actor's opacity and depth */ + * clutter_actor_save_easing_state (actor); + * clutter_actor_set_opacity (actor, 0); + * clutter_actor_set_depth (actor, -100); + * clutter_actor_restore_easing_state (actor); + * + * /* animate another actor's opacity */ + * clutter_actor_save_easing_state (another_actor); + * clutter_actor_set_opacity (another_actor, 255); + * clutter_actor_set_depth (another_actor, 100); + * clutter_actor_restore_easing_state (another_actor); + * + * Implicit animations use a default duration of 250 milliseconds, + * 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. + * + * + * Explicit animations + * The explicit animation model supported by Clutter requires that + * you create a #ClutterTransition object, and set the initial and + * final values. The transition will not start unless you add it to the + * #ClutterActor. + * + * ClutterTransition *transition; + * + * transition = clutter_property_transition_new ("opacity"); + * clutter_timeline_set_duration (CLUTTER_TIMELINE (transition), 3000); + * clutter_timeline_set_repeat_count (CLUTTER_TIMELINE (transition), 2); + * clutter_timeline_set_auto_reverse (CLUTTER_TIMELINE (transition), TRUE); + * clutter_transition_set_interval (transition, clutter_interval_new (G_TYPE_UINT, 255, 0)); + * + * clutter_actor_add_transition (actor, "animate-opacity", transition); + * + * The example above will animate the #ClutterActor:opacity property + * 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. + * + * + * * * Implementing an actor * Careful consideration should be given when deciding to implement @@ -263,7 +333,7 @@ * the valid units and syntax. * * - * + * * Custom animatable properties * #ClutterActor allows accessing properties of #ClutterAction * and #ClutterConstraint instances associated to an actor instance -- 2.7.4