From Emitrom

Back to Index

---

Animating an IPrimitive (i.e. Shape or Group) is easy. We currently support three types of animations:

• Tweening Animation - useful for animating the change of one or more property values
• Timed Animation - animation that runs for a certain duration
• Indefinite Animation - animation that runs forever (until you cancel it)

Animation Frame demo Tweener demo 3 Point Transform Transform 3 points demo

Contents 1 Tweening Animation 1.1 AnimationProperties 1.2 AnimationTweener 1.3 IAnimationHandle 2 Timed Animation 2.1 IAnimateCallback 3 Indefinite Animation 4 AnimationManager 5 Future Plans

Tweening Animation

A tweening animation modifies the value of one or more Node Attributes gradually over a specified duration (in milliseconds.)

In this example, the Circle is moved from location (100,100) to location (200,200) and its scale is changed from 1 to 2. The animation takes 5 seconds to complete.

AnimationProperties props = new AnimationProperties();
props.push(Properties.X(200));
props.push(Properties.Y(200));
props.push(Properties.SCALE(2));

Circle c = new Circle(30);
c.setX(100).setY(100).setFillColor(ColorName.GREEN);
IAnimationHandle handle = c.animate(AnimationTweener.LINEAR, props, 5000); 

AnimationProperties

AnimationProperties specifies which Node Attributes are modified and what their ultimate values are at the end of the animation.

Note that if the node has a Transform attribute defined, you can't animate the following attributes: rotation, shear, scale and offset!

This is because the Transform overrides those attributes. See Shape Transformations for a detailed explanation.

AnimationProperties Javadoc Properties Javadoc

AnimationTweener

The AnimationTweener defines how the attributes change over time.

E.g. AnimationTweener.LINEAR applies a linear change from the original value to the resulting value. E.g. if the initial value is 100 and the target value is 200, the intermediate value would be 100 + p * (200 - 100), where p is a value that grows from 0 to 1 over the duration of the animation.

The AnimationTweener class provides several predefined tweeners, but you can customize them with TweenerBuilder. Or you can create you own AnimationTweener from scratch.

Tweener	Description
LINEAR	Linear progression
EASE_IN	This animation starts slowly and speeds up as it nears the end. This predefined tweener sets strength to 2. To create a tweener with a different strength use TweenerBuilder.makeEASE_IN(int)
EASE_OUT	This animation starts fast and slows down near the end. This predefined tweener sets strength to 2. To create a tweener with a different strength use TweenerBuilder.makeEASE_OUT(int)
EASE_IN_OUT	This animation starts slow, moves fast in the middle and slows down near the end.
ELASTIC	This animation speeds up right away and shoots past its target, after which it bounces back and forth a few times, kind of like a rubberband... This predefined tweener sets the number of passes to 3. To create a tweener with a different number of passes use TweenerBuilder.makeELASTIC(int)

Tweener demo AnimationTweener Javadoc TweenerBuilder Javadoc

IAnimationHandle

The animation handle can be used to terminate an animation via the cancel method. It provides additional methods to indicate it is running (isRunning method) and to start the animation (run method.) Note that the animate methods of Shapes and Group automatically call run for you.

IAnimationHandle Javadoc

Timed Animation

A timed animation is an animation that runs for a specific duration (in milliseconds.) The IAnimateCallback is invoked when the animation starts and ends, and once for every animation frame in between.

IAnimateCallback

IAnimateCallback has several methods that are invoked by the AnimationManager during the lifetime of an animation:

Method	Description
onStart	invoked when the animation starts
onFrame	invoked once for every frame
onDone	invoked when the animation ends

Lienzo provides a defaults implementation of IAnimationCallback with methods that don't do anything, called AnimationCallback Javadoc, so you only have to implement the methods that you actually use.

Each callback method take several parameters

Method	Description
IPrimitive	Shape or Group node that is being animated
IAnimationHandle	See IAnimationHandle
duration	Amount of time that has passed since the start of the animation (in milliseconds)
perc	Relative amount of time that has passed, i.e. 0 at the start and 1 at the end of the animation (similar to a percentage.) For indefinite animations, this value is always 0.

Here's an example. it does the same thing as the example above that uses an AnimationTweener:

final Circle c = new Circle(30);
c.setX(100).setY(100).setFillColor(ColorName.GREEN);

IAnimationCallback callback = new IAnimationCallback() {
  public void onStart(IPrimitive<?> prim, IAnimationHandle handle, long duration, double percent)
  {
    c.setFillColor(ColorName.RED); // the Circle will be red during the animation
  }
            
  public void onFrame(IPrimitive<?> prim, IAnimationHandle handle, long duration, double percent)
  {
    c.setX(100 + percent * 100); // animate circle from (100,100)
    c.setY(100 + percent * 100); //   to (200,200)
  }
            
  public void onDone(IPrimitive<?> prim, IAnimationHandle handle, long duration, double percent)
  { 
    c.setFillColor(ColorName.BLUE); // make the Circle blue when it's done
  }
};
IAnimationHandle handle = c.animate(callback, 5000);

IAnimationCallback Javadoc AnimationCallback Javadoc

Indefinite Animation

An indefinite animation is similar to a Timed Animation except that it will run forever, until the cancel method of the IAnimationCallback is called.

This example does the same thing as the two examples above:

final Circle c = new Circle(30);
c.setX(100).setY(100).setFillColor(ColorName.GREEN);

IAnimationCallback callback = new IAnimationCallback() {
  public void onStart(IPrimitive<?> prim, IAnimationHandle handle, long duration, double percent)
  {
    c.setFillColor(ColorName.RED); // the Circle will be red during the animation
  }
            
  public void onFrame(IPrimitive<?> prim, IAnimationHandle handle, long duration, double percent)
  {
    if (duration >= 5000)
    {
        handle.cancel();
        return;
    }

    double percent = duration / 5000.0;
    c.setX(100 + percent * 100); // animate circle from (100,100)
    c.setY(100 + percent * 100); //   to (200,200)
  }
            
  public void onDone(IPrimitive<?> prim, IAnimationHandle handle, long duration, double percent)
  {
    c.setX(200).setY(200);
    c.setFillColor(ColorName.BLUE); // make the Circle blue when it's done
  }
};
IAnimationHandle handle = c.animate(callback);

AnimationManager

AnimationManager is the class that actually runs the animations. It provides methods for adding animations and starting them. Note that the animate methods of Shapes and Groups are just convenience methods that interact with the AnimationManager, e.g. this is how one of the Shape methods is implemented:

public IAnimationHandle animate(AnimationTweener tweener, AnimationProperties properties, int duration)
{
  AnimationManager manager = AnimationManager.getInstance();
  IAnimationHandle handle = manager.add(this, tweener, properties, duration, null);
  handle.run();
  return handle;
}

AnimationManager Javadoc

Future Plans

The animation framework is not finished. We intend to enhance it in the next major release. Stay tuned!

Animation Frame demo Tweener demo 3 Point Transform Transform 3 points demo