Animator (class jsgl.util.Animator)

Class jsgl.util.Animator is a simple utility for creating Animations. It provides an automated mechanism for periodic execution of time-parametrized functions.

Although the class is especially useful for programming graphics, its scope goes beyond graphics applications.

To create an instance of the Animator, use the jsgl.util.Animator constructor:

var myAnimator = new jsgl.util.Animator();

Sets the duration of the animation in milliseconds.

Set the animation be 1 second long:

myAnimator.setStartValue(20);
myAnimator.setEndValue(230);
myAnimator.addStepListener(function(t) {
    myCircle.setCenterX(t);
  });
 
myAnimator.setDuration(1000);
 
myPanel.addClickListener(function() {
    myAnimator.rewind();
    myAnimator.play();
  });

Click the below panel to see the sample 1000 ms along animation:

To make the animation 5 seconds long, set the duration to 5000 ms:

myAnimator.setDuration(5000);

Again, you can click the below panel to see a sample 5000 ms long animation:

version 2.0

Sets the new start value for the animation's control parameter.

Make the control parameter for the ellipse's opacity transition start from 0:

myAnimator.setStartValue(0);
 
myAnimator.setEndValue(1);
myAnimator.setDuration(3000);
myAnimator.addStepListener(function(t) {
    myEllipse.getFill().setOpacity(t);
  });
myPanel.addClickListener(function() {
    myAnimator.rewind();
    myAnimator.play();
  });

Click the below panel to see sample result of the above example:

If, in the above example, start value was set to 0.5 using

myAnimator.setStartValue(0.5);

then the opacity transition would start at 50 % opaque. Again, click the below panel to see the result:

version 2.0

Sets the new end value for the animation's control parameter.

Make the end parameter for the rectangle's rotation end at 90:

myAnimator.setStartValue(0);
myAnimator.setEndValue(90);
 
myRect.setSizeWH(120,80);
myRect.setLocationXY(75,75);
myRect.setHorizontalAnchor(jsgl.HorizontalAnchor.CENTER);
myRect.setVerticalAnchor(jsgl.VerticalAnchor.MIDDLE);
 
myAnimator.addStepListener(function(t) {
    myRect.setRotation(t);
  });
myPanel.addClickListener(function() {
    myAnimator.rewind();
    myAnimator.play();
  });

Click the below panel to see a sample result that can be produced using the above example:

If, in the above example, instead of 90, the end value was set to 360:

myAnimator.setEndValue(360);

then the result would be following. Click the panel to see:

version 2.0

Gets the currently set duration of the animation in milliseconds.

Number

Make the animation twice as long as it currently is:

myAnimator.setDuration(2*myAnimator.getDuration());

version 2.0

Gets the currently set start value of the animation's control parameter.

Number

Increase the current starting value by 1:

myAnimator.setStartValue(myAnimator.getStartValue()+1);

version 2.0

Gets the currently set end value of the animation's control parameter.

Number

Make the ending value twice as large as it currently is:

myAnimator.setEndValue(2*myAnimator.getEndValue());

version 2.0

Plays the animation. If the animation is currently stopped, it start playing from the beginning. If the animation has been previously paused, it is continued from the point when the pause was invoked.

See the other examples on this page. To start playing the animation, simply use:

myAnimator.play();

version 2.0

Allows the animated objects to be correctly initialized before the animation starts. This will simply invoke the step event without actually playing the animation.

var myCircle = myPanel.createCircle();
myPanel.addElement(myCircle);  // now the circle has radius=0
 
var myAnimator = new jsgl.util.Animator();
myAnimator.setStartValue(20);
myAnimator.setEndValue(50);
myAnimator.setDuration(1000);
 
myAnimator.addStepListener(function(t) {
    myCircle.setRadius(t);
  });
 
myAnimator.init();  // now the circle has radius=20
 
myAnimator.play();  // now the radius transitions from 20 to 50

version 2.0

Pauses the animation at the current point, allowing the play to continue later.

Play/Pause on mouse clicks:

// initialize a repeating animator
var myAnimator = new jsgl.util.Animator();
myAnimator.setStartValue(0);
myAnimator.setEndValue(360);
myAnimator.setDuration(5000);
myAnimator.setRepeating(true);
 
// add image-rotating step listener
myAnimator.addStepListener(function(t) {
    myImage.setRotation(t);
  });
 
// add click listener to the image
myImage.addClickListener(function(eventArgs) {
    if(myAnimator.isPlaying()) {
      myAnimator.pause();  // pause if playing
    }
    else {
      myAnimator.play();  // resume if paused
    }
  });

The above code can be used to produce the following result. Click the image to start/pause the animation:

version 2.0

Stops the animation, rewinding it to the start.

Play/Stop on mouse clicks. Compare with the above example at pause().

myImage.addClickListener(function(eventArgs) {
    if(myAnimator.isPlaying()) {
      myAnimator.stop();
    }
    else {
      myAnimator.play();
    }
  });

The above code can be used to produce the following result. Click the image to Play/Stop the animation:

version 2.0

Rewinds the animation to the start. This does not stop the animation if it is playing.

Rewind the animation to the start:

myAnimator.rewind();

version 2.0

Adds a step function to be invoked on each step of the animation.

Although a single function will usually be enough to control the animation, multiple independent functions can be added as shown in the below example.

Add two step listener functions:

1. The circle-moving function,
2. The rectangle-moving function.

/* Initialize a repeating animator transitioning
   from 0 to 2Ļ€ in 2 seconds */
var myAnimator = new jsgl.util.Animator();
myAnimator.setStartValue(0);
myAnimator.setEndValue(2*Math.PI);
myAnimator.setDuration(2000);
myAnimator.setRepeating(true);
 
// Add two independent step listeners
myAnimator.addStepListener(function(t) {  // circle-moving listener
    myCircle.setCenterX(75+40*Math.cos(t));
    myCircle.setCenterY(75+40*Math.sin(t));
  });
myAnimator.addStepListener(function(t) {  // rectangle-moving listener
    myRect.setY(75+40*Math.sin(t+Math.PI));
  });
 
/* Call the step listeners once to position the circle
   and the rectangle correctly at the beginning */
myAnimator.init();
 
/* Make the animator play/pause as the panel is clicked */
myPanel.setCursor(jsgl.Cursor.POINTER);
myPanel.addClickListener(function(eventArgs) {
    if(myAnimator.isPlaying()) {
      myAnimator.pause();
    }
    else {
      myAnimator.play();
    }
  });

The above code can be used to produce the following result. Click to play!

version 2.0

Removes a listener function from the pool of animation-step event listeners, making it to not listen anymore.

// create sample handler function
function handler(t) {
  myCircle.setRadius(t);
}
 
// register the handler function as a step listener
myAnimator.addStepListener(handler);
 
/* ... */
 
/* Remove the handler later, making it not update the circle
   when the animation runs anymore */
myAnimator.removeStepListener(handler);

version 2.0

Sets whether or not the animation should be played in a loop.

Sample endless animation ā€“ comprehensive example:

// create a rectangle and add it to the panel's viewport
var myRect = myPanel.createRectangle();
myPanel.addElement(myRect);
 
// make the rectangle positioned at and rotated around its center
myRect.setHorizontalAnchor(jsgl.HorizontalAnchor.CENTER);
myRect.setVerticalAnchor(jsgl.VerticalAnchor.MIDDLE);
 
// configure the rectangle
myRect.setSizeWH(40,40);
myRect.getFill().setColor('#dfe');
with(myRect.getStroke()) {
  setColor('#090');
  setWeight(3);
}
 
// create sample animator transiting from 0 to 2*PI in 10 seconds
var myAnimator = new jsgl.util.Animator();
myAnimator.setStartValue(0);
myAnimator.setEndValue(2*Math.PI);
myAnimator.setDuration(10000);
 
// sample step function -- we work with radians
myAnimator.addStepListener(function(t) {
    myRect.setX(75+30*Math.cos(t));
    myRect.setY(75+30*Math.sin(t));
    myRect.setRotation(-3*180*t/Math.PI);
  });
 
// make the animation repeat endlessly and start playing
myAnimator.setRepeating(true);
myAnimator.play();

The above code produces the following result:

version 2.0

Sets whether or not the animation should be reversed.

In the following example, whenever the image is clicked, two things happen:

1. The animation is reversed,
2. If the animation isn't playing, the play is started.

// create an image, add it to the panel's viewport
var myImage = myPanel.createImage();
myPanel.addElement(myImage);
 
// configure the initial image
myImage.setHorizontalAnchor(jsgl.HorizontalAnchor.CENTER);
myImage.setVerticalAnchor(jsgl.VerticalAnchor.MIDDLE);
myImage.setUrl('great-blue-heron.jpg');
myImage.setLocationXY(100,75);
 
// create an animator transiting from 0.0 to 1.0 in 3 seconds
var myAnimator = new jsgl.util.Animator();
myAnimator.setStartValue(0);
myAnimator.setEndValue(1);
myAnimator.setDuration(3000);
 
// the step function for sizing the image / setting its opacity
myAnimator.addStepListener(function(t) {
    myImage.setSizeWH(80+t*80, 60+t*60);
    myImage.setOpacity(0.5*(1+t));
  });
 
/* Set the initial size and opacity of the image
   (before the animation starts) */
myAnimator.init();
 
/* Initially, set the mode to reversed
   (this will be negated after the first click) */
myAnimator.setReversed(true);
 
/* Set the cursor to pointer, say the animator to reverse
   and play (if not playing) whenever the image is clicked */
myImage.setCursor(jsgl.Cursor.POINTER);
myImage.addClickListener(function(eventArgs) {
    myAnimator.setReversed(!myAnimator.isReversed());
    myAnimator.play();
  });

The above example produces the following result. Click the image several times!

version 2.0

Sets the number of steps that the Animator should invoke per second. This overrides the default setting, which is 10 FPS for MSIE and 20 FPS for other browsers.

When the CPU is too busy and the browser does not manage to perform as many FPS as required, some frames may be dropped. The Animator primarily aims to meet the required duration of the animation, not to execute every single step according to the desired FPS. It is recommended, however, not to set the FPS value to high, because using too much CPU will definitely not result in a pleasurable user experience.

Set the animator to work with 12 FPS:

myAnimator.setFps(12);

version 2.0

Determines whether the animation is currently in repeat mode or not.

Boolean

Make the animation repeat if it currently does not repeat, and vice versa:

myAnimator.setRepeating(!myAnimator.isRepeating());

version 2.0

Determines whether or not the animation is currently in reversed mode.

Boolean

Reverse the animation whenever the ellipse is clicked:

var myAnimator = new jsgl.util.Animator();
myAnimator.setStartValue(0);
myAnimator.setEndValue(360);
myAnimator.setDuration(10000);
myAnimator.addStepListener(function(t) {
    myEllipse.setRotation(t);
  });
myAnimator.setRepeating(true);
myAnimator.play();
 
myEllipse.setCursor(jsgl.Cursor.POINTER);
myEllipse.addClickListener(function(eventArgs) {
    myAnimator.setReversed(!myAnimator.isReversed());
  });

The above code can be used to produce the following result. Click the ellipse to reverse!

version 2.0

Gets the current FPS of the Animator. If no FPS has been set manually before, the value returned may be browser-dependent.

Number ā€“ The current number of steps that the Animator tends to invoke per second.

Make the animator work with at least 15 FPS:

myAnimator.setFps(Math.max(15, myAnimator.getFps()));

Adds a listener function to be invoked when the animation starts.

Set a random fill color of the circle when the radius animation starts:

// Create an animator transiting from 20 to 40 in 3 seconds
var addStartAnimator = new jsgl.util.Animator();
addStartAnimator.setStartValue(20);
addStartAnimator.setEndValue(40);
addStartAnimator.setDuration(3000);
 
// Register animation-start listener that sets the fill color randomly
addStartAnimator.addStartListener(function() {
    addStartCircle.getFill().setColor('rgb('+
      Math.round(255*Math.random())+','+
      Math.round(255*Math.random())+','+
      Math.round(255*Math.random())+')');
  });
 
// Register radius-setting step listener
addStartAnimator.addStepListener(function(t) {
    addStartCircle.setRadius(t);
  });
 
// Initialize the radius to 20
addStartAnimator.init();
 
// Play the animation from the start whenever the panel is clicked
addStartPanel.setCursor(jsgl.Cursor.POINTER);
addStartPanel.addClickListener(function(eventArgs) {
    addStartAnimator.rewind();
    addStartAnimator.play();
  });

The above code can be used to produce the following result. Click the panel several times!

version 2.0

Adds a listener function to be invoked when the animation ends.

When the Animator is in the repeat mode, the end event is raised at the end of each cycle.

Reverse the animation whenever it finishes and let it play again:

// create an Animator transiting from 40 to 130 in 3 seconds
var myAnimator = new jsgl.util.Animator();
myAnimator.setStartValue(40);
myAnimator.setEndValue(130);
myAnimator.setDuration(3000);
 
// register step listener that updates the 3rd vertex of the polygon
myAnimator.addStepListener(function(t) {
    myPolygon.setPointXYAt(t,t,2);
  });
 
/* Register animation-end listener that reverses the animation
   and makes it play again. */
myAnimator.addEndListener(function() {
    myAnimator.setReversed(!myAnimator.isReversed());
    myAnimator.play();
  });
 
/* Play/Pause the animation whenever the panel is clicked. */
myPanel.setCursor(jsgl.Cursor.POINTER);
myPanel.addClickListener(function(eventArgs) {
    if(myAnimator.isPlaying()) {
      myAnimator.pause();
    }
    else {
      myAnimator.play();
    }
  });

The above code can be used to produce the following result. Click the panel to play/pause the animation:

version 2.0

Removes a listener function from the pool of animation-start event listeners, making it to not listen anymore.

myAnimator.removeStartListener(listener);

See the equivalent example at removeStepListener() method.

version 2.0

Removes a listener function from the pool of animation-end event listeners, making it to not listen anymore.

myAnimator.removeEndListener(listener);

See the equivalent example at the removeStepListener() method.

version 2.0