Timing Framework 101

One of the most important factors in computer animation is that it needs to be time based. Otherwise the animation may be impacted by the performance of the underlying system when run on platforms with differing performance characteristics; what looks impressive and realistic on the development system may look terrible on a system with differing performance. Time based animation removes this; the animation is given a duration and the state of the animation is interpolated based on the fraction of the duration that has passed. This helps ensure that animations look consistent when run on different platforms.

As of JSE6 there are 3 timer classes supplied; java.util.Timer, javax.swing.Timer and javax.management.Timer. For Swing based applications, the most useful of these is the javax.swing.Timer class which ensures that all events it fires are fired on the Event Dispatch Thread. This is important if the event is to subsequently update the state of the UI which is the case for UI animation.

The Swing timer class fires instances of ActionEvent and so components register ActionListener instances with the timer which are informed of events. This excerpt from the JSE6 javadoc illustrates one method of instantiating a timer which might be used for animation purposes.

int delay = 1000; //milliseconds
ActionListener taskPerformer = new ActionListener() {
public void actionPerformed(ActionEvent evt) {
    //...Perform a task...
}
};
new Timer(delay, taskPerformer).start();

If the animation is fired in response to some other action such as a button click then the code rapidly becomes unwieldy. The button fires an action event which has a listener that sets up a timer, which fires an action event of its own. The listener for this event then performs the necessary animation. In doing so, it must calculate the fraction of the animation duration that has passed in order for the animation to be properly time based.

There's a large amount of boilerplate code that is required in order to set up the actions and timers and to calculate the animation fraction. The timing framework helps to abstract this away from the developer so they may concentrate on the action of the animation itself. The framework handles the setup of the timer and calculating the fraction of the animation. It uses callbacks which the developer can use to perform the animation.

The core class of the Timing Framework is the Animator class. This is the class used to create and control animations. It provides 3 constructors, one of which is shown below. The others are simpler versions that use defaults for one or more of the options.

Animator(int duration,
       double repeatCount,
       Animator.RepeatBehavior repeatBehavior,
       TimingTarget target)

The duration is the length of the animation; repeatCount specifies the number of times the animation should repeat; repeatBehaviour specifies the behaviour of the animation when it begins a new cycle, should it perform the previous cycle in reverse or loop back to the beginning and repeat; finally the target is the object that receives the animation events.

Once the Animator instance has been created, further options may be specified by calling methods on the Animator.

The animation is started by calling the start method.

The final parameter in the above constructor is an instance of TimingTarget. This object is used by the Animator to perform callbacks to perform the animation. The TimingTarget interface specifies the following methods:

begin()
end()
repeat()
timingEvent(float fraction)

The begin, end and repeat methods are self explanatory and are called when the animation begins, ends and repeats a cycle respectively. The key method is the timingEvent method. As can be seen, this callback passes the fraction of the animation that has passed which is calculated by the framework. This value, which is always between 0 and 1, is used to perform the appropriate animation.

A simple example will help illustrate. If we have a panel containing a button that we wish to animate along the x axis when it is clicked, we could do the following:

button = new JButton("Click Me!");
button.addActionListener(new ActionListener() {
 public void actionPerformed(ActionEvent e) {
   Animator anim = new Animator(2000, 5,
       Animator.RepeatBehavior.REVERSE,
       new ButtonTimingTarget());
   anim.start();
 }
});

This specifies an animation of 2 seconds duration that repeats 5 times with each cycle reversing the previous cycle. The ButtonTimingTarget which receives the callbacks is shown below:

class ButtonTimingTarget extends TimingTargetAdapter {
  @Override
  public void timingEvent(float fraction) {
   // Calculate button location bounds...
   ...
   loc = ....
   // Alter x location based on animation fraction.
   button.setLocation(loc.x * fraction), loc.y);
 }
}

The TimingTargetAdapter class is a convenience class that implements the TimingTarget interface with empty methods.

Screenshots of this animation are below.

1. Initial position



2. Mid way through the animation



3. After animation completion.



Although this is a simple example, it illustrates the simplicity of setting up an animation using the TimingFramework.

However, there's still no small amount of boilerplate in this example. We still have to add the action listener to the button in order to set up and start the animation. We also calculate and set the new location of the button ourselves based on the fraction of the animation. In the next blog I'll demonstrate the use of Triggers and PropertySetters to remove more of this boilerplate and make animations even simpler.