From d7c922c72a73c05b3fe9159f7300b6bf9c6308c0 Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Wed, 21 Mar 2012 13:30:28 +0000 Subject: [PATCH] docs: Clean up the animations sections of the Actor reference --- clutter/clutter-actor.c | 147 ++++++++++++++++++++++++++++-------------------- 1 file changed, 86 insertions(+), 61 deletions(-) diff --git a/clutter/clutter-actor.c b/clutter/clutter-actor.c index 5f4b90d..509a807 100644 --- a/clutter/clutter-actor.c +++ b/clutter/clutter-actor.c @@ -280,6 +280,40 @@ * 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 should also be used when using custom + * animatable properties for #ClutterAction, #ClutterConstraint, and + * #ClutterEffect instances associated to an actor; see the section on + * custom + * animatable properties below for an example. + * Finally, explicit animations are useful for creating animations + * that run continuously, for instance: + * + * /* this animation will pulse the actor's opacity continuously */ + * ClutterTransition *transition; + * ClutterInterval *interval; + * + * transition = clutter_property_transition_new ("opacity"); + * + * /* we want to animate the opacity between 0 and 255 */ + * internal = clutter_interval_new (G_TYPE_UINT, 0, 255); + * clutter_transition_set_interval (transition, interval); + * + * /* over a one second duration, running an infinite amount of times */ + * clutter_timeline_set_duration (CLUTTER_TIMELINE (transition), 1000); + * clutter_timeline_set_repeat_count (CLUTTER_TIMELINE (transition), -1); + * + * /* we want to fade in and out, so we need to auto-reverse the transition */ + * clutter_timeline_set_auto_reverse (CLUTTER_TIMELINE (transition), TRUE); + * + * /* and we want to use an easing function that eases both in and out */ + * clutter_timeline_set_progress_mode (CLUTTER_TIMELINE (transition), + * CLUTTER_EASE_IN_OUT_CUBIC); + * + * /* add the transition to the desired actor; this will + * * start the animation. + * */ + * clutter_actor_add_transition (actor, "opacityAnimation", transition); + * * * * @@ -335,9 +369,9 @@ * * * Custom animatable properties - * #ClutterActor allows accessing properties of #ClutterAction - * and #ClutterConstraint instances associated to an actor instance - * for animation purposes. + * #ClutterActor allows accessing properties of #ClutterAction, + * #ClutterEffect, and #ClutterConstraint instances associated to an actor + * instance for animation purposes. * In order to access a specific #ClutterAction or a #ClutterConstraint * property it is necessary to set the #ClutterActorMeta:name property on the * given action or constraint. @@ -358,8 +392,7 @@ * The example below animates a #ClutterBindConstraint applied to an * actor using clutter_actor_animate(). The rect has * a binding constraint for the origin actor, and in - * its initial state is fully transparent and overlapping the actor to - * which is bound to. + * its initial state is overlapping the actor to which is bound to. * * constraint = clutter_bind_constraint_new (origin, CLUTTER_BIND_X, 0.0); * clutter_actor_meta_set_name (CLUTTER_ACTOR_META (constraint), "bind-x"); @@ -369,67 +402,59 @@ * clutter_actor_meta_set_name (CLUTTER_ACTOR_META (constraint), "bind-y"); * clutter_actor_add_constraint (rect, constraint); * - * clutter_actor_set_reactive (rect, TRUE); - * clutter_actor_set_opacity (rect, 0); + * clutter_actor_set_reactive (origin, TRUE); * - * g_signal_connect (rect, "button-press-event", + * g_signal_connect (origin, "button-press-event", * G_CALLBACK (on_button_press), - * NULL); + * rect); * * On button press, the rectangle "slides" from behind the actor to - * which is bound to, using the #ClutterBindConstraint:offset property and - * the #ClutterActor:opacity property. - * - * float new_offset = clutter_actor_get_width (origin) + h_padding; - * - * clutter_actor_animate (rect, CLUTTER_EASE_OUT_CUBIC, 500, - * "opacity", 255, - * "@constraints.bind-x.offset", new_offset, - * NULL); - * - * - * - * - * Animatable properties - * Certain properties on #ClutterActor are marked as "animatable"; - * these properties will be automatically tweened between the current - * value and the new value when one is set. - * For backward compatibility, animatable properties will only be - * tweened if the easing duration is greater than 0, or if a new easing - * state is set, for instance the following example: + * which is bound to, using the #ClutterBindConstraint:offset property to + * achieve the effect: * - * clutter_actor_save_easing_state (actor); - * clutter_actor_set_position (actor, 200, 200); - * clutter_actor_restore_easing_state (actor); - * - * will tween the actor to the (200, 200) coordinates using the default - * easing mode and duration of a new easing state. The example above is - * equivalent to the following code: - * - * clutter_actor_set_easing_mode (actor, CLUTTER_EASE_OUT_CUBIC); - * clutter_actor_set_easing_duration (actor, 250); - * clutter_actor_set_position (actor, 200, 200); - * clutter_actor_restore_easing_state (actor); - * - * It is possible to nest easing states to tween animatable - * properties using different modes and durations, for instance: - * - * clutter_actor_save_easing_state (actor); /* outer state */ - * - * /* set the duration of the animation to 2 seconds and change position */ - * clutter_actor_set_easing_duration (actor, 2000); - * clutter_actor_set_position (actor, 0, 0); - * - * clutter_actor_save_easing_state (actor); /* inner state */ - * - * /* set the duration of the animation to 5 seconds and change depth and opacity */ - * clutter_actor_set_easing_duration (actor, 5000); - * clutter_actor_set_depth (actor, 200); - * clutter_actor_set_opacity (actor, 0); - * - * clutter_actor_restore_easing_state (actor); - * - * clutter_actor_restore_easing_state (actor); + * gboolean + * on_button_press (ClutterActor *origin, + * ClutterEvent *event, + * 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 + * * the origin, plus a padding value. + * */ + * float new_offset = clutter_actor_get_width (origin) + h_padding; + * + * /* the property we wish to animate; the "@constraints" section + * * tells Clutter to check inside the constraints associated + * * with the actor; the "bind-x" section is the name of the + * * constraint; and the "offset" is the name of the property + * * on the constraint. + * */ + * const char *prop = "@constraints.bind-x.offset"; + * + * /* create a new transition for the given property */ + * transition = clutter_property_transition_new (prop); + * + * /* set the easing mode and duration */ + * clutter_timeline_set_progress_mode (CLUTTER_TIMELINE (transition), + * CLUTTER_EASE_OUT_CUBIC); + * 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); + * + * /* add the transition to the actor; this causes the animation + * * to start. the name "offsetAnimation" can be used to retrieve + * * the transition later. + * */ + * clutter_actor_add_transition (rect, "offsetAnimation", transition); + * + * /* we handled the event */ + * return CLUTTER_EVENT_STOP; + * } * * */ -- 2.7.4