JS3 is a fast and lightweight drawing and animation library for the HTML5 JavaScript Canvas

Stage API

The following properties of the Stage are read-only.


	stage = new JS3('my-canvas');
	stage.width         :Number;        // the width of the Stage
	stage.height        :Number;        // the height of the Stage
	stage.numChildren   :Number;        // the number of Sprites currently on the display list
	stage.mousePressed  :Boolean;       // whether or not the Mouse is currently pressed down
	stage.position      :Object;        // returns the global {x, y} position of the stage in the html page

The following properties of the Stage can be read as well as written, default values are shown.


	stage = new JS3('my-canvas');
	stage.interactive   = false;        // tells the Stage to listen for mouse events
	stage.drawClean     = true;         // tells the Stage to clear itself before drawing the next frame
	stage.background    = '#ffffff';    // the background color of the Stage
	stage.windowTitle   = 'My Canvas';  // the title of pop-up windows used when saving the Stage to a .png

And the following are general utility methods for controlling the Stage.


	stage = new JS3('my-canvas');
	stage.setSize( width:Number, height:Number ); // defaults to the dimensions of your canvas element
	stage.save(); 	// opens a popup window allowing the user to save the current state of the canvas as a .png
	stage.clear();  // removes all graphics and children from the Stage 
	stage.reset();  // calls clear() and also stops all tweens and functions passed to stage.run()

The Display List

The following methods allow you to modify the internal display list.


	stage = new JS3('my-canvas');
	stage.addChild( obj:JS3Object ) : void
	stage.addChildAt( obj:JS3Object, index:Number ) : void

	stage.getChildAt( index:Number ) : JS3Object
	stage.getChildAtRandom( ) : JS3Object

	stage.removeChild( obj:JS3Object ) : void
	stage.removeChildAt( index:Number ) : void

Drawing Methods

Use the following methods to draw non-persistent Shapes on the Stage.
Each method requires an Object that describes how the Shape should be positioned and drawn.
For more information about these methods and what you should pass into them, check the section on drawing.


	stage = new JS3('my-canvas');
	stage.drawLine( {} );
	stage.drawArc( {} );
	stage.drawRect( {} );
	stage.drawCircle( {} );
	stage.drawTri( {} );
	stage.drawText( {} );

The Tween Method

The JS3 Tween method takes the following form :


	target      : JS3Object     // any JS3Object
	duration    : Number        // time in seconds
	details     : Object        // an Object that describes the properties to tween and callbacks to execute.
  // put together, the syntax for a tween is as follows:
	stage.tween(target, duration, details);

The following properties can be tweened on any JS3Object.


	x           : Number        // position on the x axis
	y           : Number        // position on the y axis
	alpha       : Number        // opacity / transparency of the object
	scaleX      : Number        // horizontal scale
	scaleY      : Number        // vertical scale
	rotation    : Number        // rotation in degrees, negative values rotate counter-clockwise
  // put together, a typical tween could look like the following:
	stage.tween(target, duration, {x:100, y:100, alpha:.5, scaleX:3, scaleY:3, rotation:90} );

The following callbacks can also be executed whenever a tween begins or ends.


	onStart     : Function      // called when the tween begins
	onComplete  : Function      // called when the tween completes

You can also specify an amount of time to delay before starting the tween.


	delay       : Number        // amount of time to delay the start of the tween in seconds

All together, a tween with multiple properties and callbacks could look like the following :


	stage.tween(my-circle, 1, {x:100, alpha:.5, rotation:90, onStart:onStartFunc, onComplete:onCompleteFunc, delay:1});

Timed Animation Methods

Timed animations are controlled using the run & stop methods.
Both methods simply take the function to start and stop executing.


	stage.run( function ) : void
	stage.stop( function ) : void

The run method also accepts three additional parameters :


	delay       : Number        // the number of seconds in between calls
	repeatCount : Number        // number of times to call the function before stopping, default is infinite
	onComplete  : Function      // a callback to execute when the repeatCount is reached

With the additional parameters specified, a call to run could look like the following :


  // call the update function once a second, limit to ten times and then execute the onUpdateComplete function.
	stage.run(update, 1, 10, onUpdateComplete);

Framerate Monitor

JS3 includes a simple FPS monitor that automatically updates once per second.
Note by default the monitor is absolutely positioned within the HTML document and is never a child of the Stage.


	JS3.showFrameRate( xPosition:Number, yPosition:Number );

If you'd like to position it relative to your Stage just pass your Stage instance in as the third argument.


	stage = new JS3('my-canvas');
	JS3.showFrameRate(5, 5, stage);

Utility Methods

JS3 also includes a couple convenient utility methods to help with common tasks.


	JS3.getRandomColor() : Number
	JS3.getRandomValue() : Number

JS3.getRandomValue supports function overloading meaning that you can call it three different ways.


	JS3.getRandomValue() // returns a number between 0 and 1
	JS3.getRandomValue(n1) // returns a number between 0 and n1
	JS3.getRandomValue(n1, n2) // returns a number between n1 and n2

JS3 API