Timing Framework (part 2) - Triggers

In the last blog, I showed a simple demonstration of how the Timing Framework can help reduce the amount of boilerplate code required to code animations. In this entry I'll show how to use triggers to reduce this even further.

In the last entry we used code like this to start an animation when a button was clicked.

button.addActionListener(new ActionListener() {
public void actionPerformed(ActionEvent e) {
  Animator anim = new Animator(2000, 5,
      Animator.RepeatBehavior.REVERSE, new ButtonTimingTarget());
  anim.setAcceleration(0.4f);
  anim.setDeceleration(0.4f);
  anim.start();
}
});

The Timing Framework provides triggers which extend the basic functionality of the framework. The framework provides a number of trigger classes which can trigger animations.

We can simplify the above code using an action trigger which corresponds to ActionEvents and so is perfect to use with a button. The trigger may be instantiated directly by client code but of more convenience is the static addTrigger method which also takes the object on which the trigger should operate.

For example, to add an action trigger to the button we'd do the following:

Animator anim = new Animator(2000, 5,
  Animator.RepeatBehavior.REVERSE, new ButtonTimingTarget());
anim.setAcceleration(0.4f);
anim.setDeceleration(0.4f);

ActionTrigger.addTrigger(button, anim);

This may not seem like a huge reduction but it removes the boilerplate of the action listener implementation and removes the need for the anonymous inner class making the code arguably much more readable.

Currently the framework provides four trigger implementations:

1. ActionTrigger - as shown above, may be used on any component that fires action events.
2. FocusTrigger - may be used on components that fire focus events such as text fields
3. MouseTrigger - may be used on components that fire mouse events (pretty much every component) such as when the mouse enters or leaves a component
4. TimingTrigger - allows sequencing of different animations, for example starting an animation when another animation ends

The ActionTrigger is the simplest of the triggers and takes no special parameters. The more specialised triggers have a corresponding Event class (e.g. FocusTriggerEvent for the FocusTrigger or MouseTriggerEvent for the MouseTrigger) which specify the specific event(s) on which the trigger should operate. The key point is that the trigger class handles the setting of the listeners on the component to fire the animation at the appropriate time. All the developer needs to do is create the animation instance, set the trigger and let the framework ensure that the animation is fired appropriately.

Next time I'll take this a step further and use a property setter to simplify the code even more.

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.