JavaScript Graphics Library (JSGL.org) Draw and move interactive vector graphics easily in Javascript!

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.

Creation

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

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

Method Summary

Control Parameters

Setters
setDuration(milliseconds: Number) Sets the duration of the animation in milliseconds.
setStartValue(newValue: Number) Sets the new start value for the animation's control parameter.
setEndValue(newValue: Number) Sets the new end value for the animation's control parameter.
Getters
getDuration() : Number Gets the duration of the animation in milliseconds.
getStartValue() : Number Gets the start value of the animation's control parameter.
getEndValue() : Number Gets the end value of the animation's control parameter.

Playing

Name Description
play() Plays the animation.
init() Allows the animated objects to be correctly initialized before the animation starts.
pause() Pauses the animation at the current point, allowing the play to continue later.
stop() Stops the animation, rewinding it to the start.
rewind() Rewinds the animation to the start.

Animating Functions

Name Description
addStepListener(listener: Function(t: Number)) Adds a step function to be invoked on each step of the animation. This is the crucial function that should control graphic elements to make the animation work.
removeStepListener(listener: Function(t: Number)) Removes a listener function from the pool of animation-step event listeners, making it to not listen anymore.

Animation Parameters

Setters
setRepeating(repeating: Boolean) Sets whether or not the animation should be played in a loop.
setReversed(reversed: Boolean) Sets whether or not the animation should be reversed.
setFps(newFps: Number) Sets the number of steps that the Animator should invoke per second, overriding the default setting.
Getters
isRepeating() : Boolean Determines whether the animation is currently in repeat mode or not.
isReversed() : Boolean Determines whether the animation is currently in reversed mode.
getFps() : Number Gets the current FPS of the Animator.

Start/End Events

Name Description
addStartListener(listener: Function) Adds a listener function to be invoked when the animation starts.
addEndListener(listener: Function) Adds a listener function to be invoked when the animation ends.
removeStartListener(listener: Function) Removes a listener function from the pool of animation-start event listeners, making it to not listen anymore.
removeEndListener(listener: Function) Removes a listener function from the pool of animation-end event listeners, making it to not listen anymore.

Method Detail

setDuration(milliseconds: Number)

Sets the duration of the animation in milliseconds.

Parameters

Name Type Description
milliseconds Number The new duration in milliseconds.

Example

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:

Since

version 2.0

setStartValue(newValue: Number)

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

Parameters

Name Type Value
newValue Number The new start value of the control parameter.

Example

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:

Since

version 2.0

setEndValue(newValue: Number)

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

Parameters

Name Type Description
newValue Number The new end value for the control parameter.

Example

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:

Since

version 2.0

getDuration() : Number

Gets the currently set duration of the animation in milliseconds.

Returns

Number

Example

Make the animation twice as long as it currently is:

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

Since

version 2.0

getStartValue() : Number

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

Returns

Number

Example

Increase the current starting value by 1:

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

Since

version 2.0

getEndValue() : Number

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

Returns

Number

Example

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

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

Since

version 2.0

play()

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.

Example

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

myAnimator.play();

Since

version 2.0

init()

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

Example

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

Since

version 2.0

pause()

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

Example

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:

Since

version 2.0

stop()

Stops the animation, rewinding it to the start.

Example

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:

Since

version 2.0

rewind()

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

Example

Rewind the animation to the start:

myAnimator.rewind();

Since

version 2.0

addStepListener(listener: Function(t: Number))

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.

Parameters

Name Type Description
listener Function(t: Number) The listener function to be added. This is the crucial function that should control graphic elements to make the animation work. When the function is executed, current parameter value, t, is passed to the function as an argument by the Animator. Based on the parameter value t, the function should perform desirable operations.

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!

Since

version 2.0

removeStepListener(listener: Function(t: Number))

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

Parameters

Name Type Description
listener Function(t: Number) The listener to be removed.

Example

// 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);

Since

version 2.0

setRepeating(repeating: Boolean)

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

Parameters

Name Type Description
repeating Boolean true if the animation should repeat, false if not.

Example

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:

Since

version 2.0

setReversed(reversed: Boolean)

Sets whether or not the animation should be reversed.

Parameters

Name Type Description
reversed Boolean true if the animation should be reversed, false if not.

Example

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!

Since

version 2.0

setFps(newFps: Number)

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.

Parameters

Name Type Description
newFps Number The new number of frames per second.

Example

Set the animator to work with 12 FPS:

myAnimator.setFps(12);

Since

version 2.0

isRepeating() : Boolean

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

Returns

Boolean

Example

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

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

Since

version 2.0

isReversed() : Boolean

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

Returns

Boolean

Example

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!

Since

version 2.0

getFps() : Number

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

Returns

Number – The current number of steps that the Animator tends to invoke per second.

Example

Make the animator work with at least 15 FPS:

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

addStartListener(listener: Function)

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

Parameters

Name Type Description
listener Function The animation-start event listener to be added.

Example

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!

Since

version 2.0

addEndListener(listener: Function)

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.

Parameters

Name Type Description
listener Function The listener to be added.

Example

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:

Since

version 2.0

removeStartListener(listener: Function)

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

Parameters

Name Type Description
listener Function The listener function to be removed.

Example

myAnimator.removeStartListener(listener);

See the equivalent example at removeStepListener() method.

Since

version 2.0

removeEndListener(listener: Function)

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

Parameters

Name Type Description
listener Function The listener to be removed.

Example

myAnimator.removeEndListener(listener);

See the equivalent example at the removeStepListener() method.

Since

version 2.0

 
animation.txt · Last modified: 2013/03/14 03:16 (external edit)
 
Except where otherwise noted, content on this wiki is licensed under the following license: GNU Free Documentation License 1.3
Driven by DokuWiki Powered by PHP Valid XHTML 1.0 Valid CSS