mutter/doc/reference/clutter/migrating-ClutterBehaviour.xml

<?xml version="1.0"?>
<!DOCTYPE chapter PUBLIC
  "-//OASIS//DTD DocBook XML V4.3//EN"
  "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
]>
<chapter id="migrating-ClutterBehaviour">

  <chapterinfo>
    <author>
      <firstname>Emmanuele</firstname>
      <surname>Bassi</surname>
      <affiliation>
        <address>
          <email>ebassi@linux.intel.com</email>
        </address>
      </affiliation>
    </author>
  </chapterinfo>

  <title>Migrating from ClutterBehaviour</title>

  <para>The #ClutterBehaviour class and its sub-classes have been deprecated
  since Clutter 1.6. The animation framework provided by #ClutterAnimation,
  #ClutterAnimator and #ClutterState fully replaces all functionality from the
  #ClutterBehaviour classes.</para>

  <para>Generally, animations using #ClutterBehaviour sub-classes can be
  effectively re-implemented just by using #ClutterActor properties.</para>

  <para>Here is an example of an animation using a
  #ClutterBehaviourOpacity instance:</para>

  <informalexample>
    <programlisting>
  ClutterTimeline *timeline = clutter_timeline_new (250);
  ClutterAlpha *alpha = clutter_alpha_new_full (timeline, CLUTTER_LINEAR);
  ClutterBehaviour *behaviour = clutter_behaviour_opacity_new (alpha, 255, 0);

  clutter_behaviour_apply (behaviour, some_actor);

  clutter_timeline_start (timeline);
    </programlisting>
  </informalexample>

  <para>The same effect can be achieved by using clutter_actor_animate() and
  the #ClutterActor:opacity property:</para>

  <informalexample>
    <programlisting>
  clutter_actor_set_opacity (some_actor, 255);
  clutter_actor_animate (some_actor, CLUTTER_LINEAR, 250,
                         "opacity", 0,
                         NULL);
    </programlisting>
  </informalexample>

  <para>#ClutterBehaviour<!-- -->s used for continuous animations with looping
  timelines can still be effectively replaced by looping animations; for
  instance, the following example of a "pulsating" actor using
  #ClutterBehaviourScale:</para>

  <informalexample>
    <programlisting>
static void
reverse_timeline (ClutterTimeline *timeline)
{
  ClutterTimelineDirection dir = clutter_timeline_get_direction (timeline);

  if (dir == CLUTTER_TIMELINE_FORWARD)
    dir = CLUTTER_TIMELINE_BACKWARD;
  else
    dir = CLUTTER_TIMELINE_FORWARD;

  clutter_timeline_set_direction (timeline, dir);
}

  ClutterTimeline *timeline = clutter_timeline_new (500);
  ClutterAlpha *alpha = clutter_alpha_new_full (timeline, CLUTTER_LINEAR);
  ClutterBehaviour *behaviour;

  g_object_set (some_actor, "scale-gravity", CLUTTER_GRAVITY_CENTER, NULL);
  behaviour = clutter_behaviour_scale_new (alpha,
                                           1.0, 2.0,
                                           1.0, 2.0);
  clutter_behaviour_apply (behaviour, some_actor);

  g_signal_connect (timeline,
                    "completed", G_CALLBACK (reverse_timeline),
                    NULL);

  clutter_timeline_set_loop (timeline);
  clutter_timeline_start (timeline);
    </programlisting>
  </informalexample>

  <para>The same effect can be achieved using a #ClutterAnimation:</para>

  <informalexample>
    <programlisting>
  ClutterAnimation *animation =
    clutter_actor_animate (some_actor, CLUTTER_LINEAR, 500,
                           "scale-x", 2.0,
                           "scale-y", 2.0,
                           "fixed::scale-gravity", CLUTTER_GRAVITY_CENTER,
                           NULL);

  clutter_animation_set_loop (animation, TRUE);

  g_signal_connect (clutter_animation_get_timeline (animation),
                    "completed", G_CALLBACK (reverse_timeline),
                    NULL);
    </programlisting>
  </informalexample>

  <para>#ClutterBehaviour sub-classes can be applied to multiple actors, in
  order to share the duration and the easing mode. It is possible to use the
  same underlying #ClutterTimeline and #ClutterAlpha instances with
  #ClutterAnimation to achieve the same effect. Complex animations, spanning
  multiple actors, should use the #ClutterAnimator and #ClutterState classes
  instead.</para>

</chapter>