Fork me on GitHub

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