[clutter-tutorial] Replaced the effects section with a new animations section

[Johannes Schmid <jhs src gnome org>]

commit 8e65071171c386a6be74c0b9c6090ff486fbf614
Author: Johannes Schmid <jhs gnome org>
Date:   Mon Apr 20 09:47:30 2009 +0200

    Replaced the effects section with a new animations section
    
    ClutterEffects was removed from clutter 0.9 and replaced by ClutterAnimation which is now covered by the tutorial
---
 docs/tutorial/clutter-tut.xml |   73 +++++++++++++-----------------
 examples/effects/main.c       |   98 -----------------------------------------
 2 files changed, 32 insertions(+), 139 deletions(-)

diff --git a/docs/tutorial/clutter-tut.xml b/docs/tutorial/clutter-tut.xml
index a739d76..0c3d2e0 100644
--- a/docs/tutorial/clutter-tut.xml
+++ b/docs/tutorial/clutter-tut.xml
@@ -522,7 +522,7 @@ The following example demonstrates handing of clicks on an actor:
 <title>Using Timelines</title>
 <para>
 A <classname>ClutterTimeline</classname> can be used to change the position or appearance of an actor over time. 
-These can be used directly as described in this chapter, or together with an effect or behaviour, as you will see in 
+These can be used directly as described in this chapter, or together with an animation or behaviour, as you will see in 
 the following chapters.</para> 
 
 <para>
@@ -597,66 +597,57 @@ second timeline moves the rectangle horizontally.
 </chapter>
 
 
-<chapter id="sec-effects">
-<title>Effects</title>
+<chapter id="sec-animations">
+<title>Animations</title>
 
 <sect1>
-<title>Using Effects</title>
+<title>Using Animations</title>
 
 <para>
-&clutter; provides several effects functions that can be used together with a timeline to change the properties of 
-a single actor over time, using a simple numeric calculation. In many cases this is an easier way to implement animation. 
-For instance, <function>clutter_effect_fade()</function> gradually changes the opacity of an 
-actor or <function>clutter_effect_rotate()</function> gradually changes the rotation of an actor, calculating the opacity or 
-rotation by calling the supplied <literal>alpha</literal> callback.
-</para>
-<para>To use a clutter effect, you should first create a <classname>ClutterEffectTemplate</classname>, specifying your 
-timeline object and a <classname>ClutterAlphaFunc</classname> callback. This callback will need to call 
-<function>clutter_alpha_get_timeline()</function> so it can return a value based on the timeline's current frame number 
-and total number of frames, using <function>clutter_timeline_get_current_frame()</function> and 
-<function>clutter_timeline_get_n_frames()</function>. The result should be between 0 and CLUTTER_ALPHA_MAX, with the meaning of 
-the result depending on the effect used. For instance, CLUTTER_ALPHA_MAX would be 100% opacity when using <function>clutter_effect_fade()</function>. 
-Several built-in callbacks, such as <function>CLUTTER_ALPHA_SINE</function>, allow you to easily specify natural movement. 
-</para>
-
-<figure id="figure-alpha-func">
-  <title>Graphic representation of some alpha functions.</title>
-  <screenshot>
-    <graphic format="PNG" fileref="&url_figures_base;alpha-func.png"/>
-  </screenshot>
-</figure>
-
-<para>You should then provide this <classname>ClutterEffectTemplate</classname> to one of the <function>clutter_effect</function> 
-functions, along with the actor and any extra parameters required by that function. Remember to unref the effect template after providing it to the effect function 
-(which will take a reference). Unlike actors, these do not have &quot;floating references&quot;.
+Animations in &clutter; are used to change properties of a <classname>ClutterActor</classname>
+over time. For a new <classname>ClutterAnimation</classname> you need a
+<classname>ClutterTimeline</classname> and either a <classname>ClutterActor</classname>
+or one of the given standard animation modes to control the property change.
 </para>
-<para>To make it easier to use different timelines with different effects, you can use <function>clutter_effect_template_set_timeline_clone()</function> to cause the 
-effect to clone (copy instead of just referencing) the timeline, allowing you to change the original timeline and supply it to a second effect, without 
-influencing the first effect.</para>
-
-<para>The effects API is actually a simplified API that wraps the <classname>ClutterBehaviour</classname> objects. 
-However, the effect functions can only control one actor at a time and do not allow you to change the effects while the timeline 
-is running. To do this you can use the behaviours directly, as described in the <link linkend="sec-behaviours">Behaviours</link> section.
+<para>
+To create a new <classname>ClutterAnimation</classname> use 
+<function>clutter_actor_animate_with_timeline()</function> for standard modes or
+<function>clutter_actor_animate_with_actor()</function> for using an actor. These
+functions take a list of <classname>GObject</classname>-properties of the 
+<classname>ClutterActor</classname> to change and the value the property should have
+when the timeline finishes. To set the start value of the property you can just
+use <function>g_object_set()</function> or one of the available _set methods. It is
+possible to add/remove properties from the <classname>ClutterAnimation</classname>
+using <function>clutter_animation_bind()</function> and 
+<function>clutter_animation_unbind()</function>.
+</para>
+<para>
+In most cases you may be able to avoid using a custom <classname>ClutterAlpha</classname>
+by using on the the standard modes provided by &clutter;. Those modes are available
+in the <classname>ClutterAnimationMode</classname> enum.
 </para>
+<para><ulink url="&url_refdocs_base_clutter;Actor.html">ClutterActor Reference</ulink></para>
+<para><ulink url="&url_refdocs_base_clutter;Animations.html">ClutterAnimation Reference</ulink></para>
+<para><ulink url="&url_refdocs_base_clutter;Animations.html#ClutterAnimationMode">ClutterAnimationMode Reference</ulink></para>
 
-<para><ulink url="&url_refdocs_base_clutter_alt;Effects.html">Reference</ulink></para>
 </sect1>
 
 
-<sect1 id="effects-example"><title>Example</title>
+<sect1 id="effects-animations"><title>Example</title>
 <para>
-The following example demonstrates the use of both a fade effect and a path effect on the same actor,
+The following example demonstrates the use of an animation for a fade effect and a 
+path effect on the same actor,
 changing a rectangle's opacity while it is moved a long a straight line:
 </para>
 
-<figure id="figure-effects">
-  <title>Behaviour</title>
+<figure id="figure-animations">
+  <title>Animation</title>
   <screenshot>
     <graphic format="PNG" fileref="&url_figures_base;effects.png"/>
   </screenshot>
 </figure>
 
-<para><ulink url="&url_examples_base;effects">Source Code</ulink></para>
+<para><ulink url="&url_examples_base;animation">Source Code</ulink></para>
 </sect1>
 
 </chapter>
diff --git a/examples/effects/main.c b/examples/effects/main.c
deleted file mode 100644
index 33e15d0..0000000
--- a/examples/effects/main.c
+++ /dev/null
@@ -1,98 +0,0 @@
-/* Copyright 2007 Openismus GmbH
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License version 2
- * as published by the Free Software Foundation.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
- */
-
-#include <clutter/clutter.h>
-#include <stdlib.h>
-
-ClutterActor *rect = NULL;
-
-/* This must return a value between 0 and CLUTTER_ALPHA_MAX_ALPHA,
- * where 0 means the start of the path, 
- * and CLUTTER_ALPHA_MAX_ALPHA is the end of the path.
- *
- * This will be called as many times per seconds as specified in our call to clutter_timeline_new().
- *
- * See also, for instance CLUTTER_ALPHA_SINE_HALF for a useful built-in callback.
- */
-guint32
-on_alpha (ClutterAlpha *alpha, gpointer data)
-{
-  /* Get the position in the timeline, 
-   *  so we can base our value upon it:
-   */
-  ClutterTimeline *timeline = clutter_alpha_get_timeline (alpha);
-  const int current_frame_num = clutter_timeline_get_current_frame (timeline);
-  const int n_frames = clutter_timeline_get_n_frames (timeline);
-
-  /* Return a value that is simply proportional to the frame position: */
-  return (CLUTTER_ALPHA_MAX_ALPHA * current_frame_num / n_frames);
-}
-
-
-int main(int argc, char *argv[])
-{
-  ClutterColor stage_color = { 0x00, 0x00, 0x00, 0xff };
-  ClutterColor rect_color = { 0xff, 0xff, 0xff, 0x99 };
-
-  clutter_init (&argc, &argv);
-
-  /* Get the stage and set its size and color: */
-  ClutterActor *stage = clutter_stage_get_default ();
-  clutter_actor_set_size (stage, 200, 200);
-  clutter_stage_set_color (CLUTTER_STAGE (stage), &stage_color);
-
-  /* Add a rectangle to the stage: */
-  rect = clutter_rectangle_new_with_color (&rect_color);
-  clutter_actor_set_size (rect, 40, 40);
-  clutter_actor_set_position (rect, 10, 10);
-  clutter_container_add_actor (CLUTTER_CONTAINER (stage), rect);
-  clutter_actor_show (rect);
-
-  /* Show the stage: */
-  clutter_actor_show (stage);
-
-  ClutterTimeline *timeline = clutter_timeline_new(100 /* frames */, 30 /* frames per second. */);
-  clutter_timeline_set_loop(timeline, TRUE); 
-  clutter_timeline_start(timeline);
-
-  /* Instead of our custom callback, 
-   * we could use a standard callback. For instance, CLUTTER_ALPHA_SINE_INC. 
-   */
-  ClutterEffectTemplate *effect_template = clutter_effect_template_new (timeline, &on_alpha);
-
-  ClutterKnot knot[2];
-  knot[0].x = 10;
-  knot[0].y = 10;
-  knot[1].x= 150;
-  knot[1].y= 150;
- 
-  // Move the actor along the path:
-  clutter_effect_path (effect_template, rect, knot, sizeof(knot) / sizeof(ClutterKnot), NULL, NULL);
-
-  // Also change the actor's opacity while moving it along the path:
-  // (You would probably want to use a different ClutterEffectTemplate, 
-  // so you could use a different alpha callback for this.)
-  clutter_effect_fade (effect_template, rect, 50, NULL, NULL);
-
-  g_object_unref (effect_template);
-  g_object_unref (timeline);
-
-  /* Start the main loop, so we can respond to events: */
-  clutter_main ();
-
-  return EXIT_SUCCESS;
-
-}