Drawing Shapes
JS3 makes it easy to draw a number of basic primitive shapes : Circles, Ellipses, Squares, Rectangles, Triangles, Lines, Arcs.
Shapes Vs. Sprites
JS3 allows you to create non-persistent and persistent graphics, respectively called Shapes & Sprites.
The main difference is that Shapes are drawn to the canvas and then immediately removed from memory whereas Sprites persist allowing you to tween and interact with them after they are drawn.
You can draw a Shape by calling the desired Stage method and passing in a generic Object that describes how the Shape should be drawn.
A full list of properties that can be used to describe how an Object is created are listed below in drawing basics.
var stage = new JS3('my-canvas');
stage.drawCircle( { x:50, y:25, size:50 } );
stage.drawRect( { x:120, y:25, width:80, height:50 } );
stage.drawLine( { x:220, y:25, x1:0, y1:50, x2:50, y2:0 } );
stage.drawArc( { x:280, y:25, x1:0, y1:50, xc:40, yc:-50, x2:80, y2:50 } );
stage.drawTri( { x:380, y:25, size:58 } );
These methods essentially stain the canvas with whatever type of Shape you tell it to draw.
Shapes are much more performant than Sprites. If tweening and interactivity are not needed, always draw Shapes instead of Sprites.
Sprites are analogous to DisplayObjects in AS3 in that you create them by using the new keyword and then manually add them to the Stage.
Sprites can be removed and added to the Stage as often as desired as well be animated and told to listen for mouse events.
var stage = new JS3('my-canvas');
// create a Sprite using the new keyword //
var c = new JS3Circle();
c.x = 50;
c.y = 25;
c.size = 50;
stage.addChild( c );
// or you can optionally pass an Object definition into the Sprite's constructor //
var c = new JS3Circle( {x:50, y:25, size:50} );
stage.addChild( c );
Drawing Basics
All Shapes & Sprites inherit from a base graphics object with the following properties and default settings.
Each of these properties can be tweened by setting them to a different value.
x :Number = 0;
y :Number = 0;
alpha :Number = 1;
scaleX :Number = 1;
scaleY :Number = 1;
rotation :Number = 1;
In addition to the base object properties defined above, Circles, Rectangles, & Triangles also define fill & stroke values.
To disable the fill or stroke of a Shape, set its fill or stroke property to false.
xfill :Boolean = true;
xfillColor :String = '#DDD';
xfillAlpha :Number = 1;
xstroke :Boolean = true;
xstrokeColor :String = '#CCC';
xstrokeAlpha :Number = 1;
xstrokeWidth :Number = 4;
Colors & Gradients
You can fill any shape, including the background with a single color or a gradient made up of several colors.
Simply set an array of colors to either of the two gradient options, radial or linear as shown below.
xvar stage = new JS3('my-canvas');
xstage.linear = ['#EEEEEE', '#CCCCCC'];
xvar r1 = new JS3Rect({size:50, x:25, y:25});
xr1.color = 'green';
xstage.addChild( r1 );
xvar c1 = new JS3Circle({size:50, x:125, y:25});
xc1.radial = ['#ff0000', '#000000'];
xstage.addChild( c1 );
xvar r2 = new JS3Rect({size:50, x:225, y:25});
xr2.linear = ['red', 'black'];
xstage.addChild( r2 );
xvar c2 = new JS3Circle({size:50, x:325, y:25});
xc2.radial = ['#00C9FF', '#000000', '00C9FF', '#000000'];
xstage.addChild( c2 );
Quick Tip : You can set colors by either using their hex values or with any of the 17 standard color names.
Positioning, Scaling & Rotation
It is very important to note that all Shapes and Sprites are positioned on the Stage relative to their top left coordinate.
This is exactly the same as the default positioning you are probably used to working with in the Flash authoring environment.
Objects are scaled and rotated however from their center, which is automatically calculated from the Object's width, height and size.
The following example shows a Square positioned at 10 pixels on the X and Y axis.
var stage = new JS3('my-canvas');
var r = new JS3Rect();
r.x = 10;
r.y = 10;
stage.addChild( r );
Now note when scaling and rotation are applied, the Object scales and rotates from its center.
var stage = new JS3('my-canvas');
var r = new JS3Rect();
r.x = 10;
r.y = 10;
r.scaleX = 1.5;
r.scaleY = 1.5;
r.rotation = 45;
stage.addChild( r );
Circles and Rectangles
The dimensions of Circles, Rectangles, & Triangles are defined by setting either their size property or their width and height.
Setting a Shape's size property constrains the Shape to equal dimensions.
// draw a circle with a diameter of 50 pixels //
var c = new JS3Circle();
c.size = 50;
stage.addChild(c);
// draw an Ellipse by setting separate values for a Circle's width and height.
var c = new JS3Circle();
c.width = 80;
c.height = 40;
stage.addChild(c);
Quick Tip : Setting a Shape's size will overwrite any previous values that have been set for its width and height.
The following examples show how to draw a Square and Rectangle.
// draw a 50 pixels x 50 pixels Square //
var r = new JS3Rect();
r.size = 50;
stage.addChild(r);
// draw a Rectangle that is 80 pixels wide by 40 pixels tall.
var r = new JS3Rect();
r.width = 80;
r.height = 40;
stage.addChild(r);
Triangles
There are three ways to draw Triangles.
In addition to setting its size, width & height you can also draw custom Triangles by specifying the x and y location of each of its three points.
Quick Tip : Whenever you specify custom coordinate points, these points are always drawn relative to the Object's x & y position on the Stage.
// draw a Triangle whose sides are each 50 pixels in length //
var t = new JS3Tri();
t.size = 50;
stage.addChild(t);
// draw a Triangle with a varying width and height //
var t = new JS3Tri();
t.width = 80;
t.height = 40;
stage.addChild(t);
// draw a custom Triangle by specifying its three points //
var t = new JS3Tri();
// position this Triangle at 50 pixels on the x and y axis //
t.x = 50;
t.y = 50;
// x1 will be drawn at the global coordinate of 80, y1 at 100 etc... //
t.x1 = 30;
t.y1 = 50;
t.x2 = 60;
t.y2 = 0;
t.x3 = 90;
t.y3 = 50;
stage.addChild(c);
Lines and Arcs
In addition to the base object properties, Lines & Arcs also have the following unique properites :
color :Number = '#333';
thickness :Number = 4;
capStyle :String = 'butt'; // (valid values are 'butt, round, or square')
To draw a line, simply define the x and y points to draw to.
All lines & arcs start drawing from their x1 & y1 coordinates.
If these are not set the line will start drawing from the line's x and y coordinates and if these are not set it will start from 0,0
var line = new JS3Line();
line.color = '#ff0000';
line.x = 50;
line.y = 130;
line.y2 = -100;
line.x2 = 340;
stage.addChild(line);
Drawing an Arc is simple and just requires an additional point to "pull" the Line in one direction or another.
This third point is a control point defined with the properties xc and yc.
var arc = new JS3Arc();
arc.color = '#ff0000';
arc.x = 50;
arc.y = 190;
arc.x1 = 0;
arc.y1 = 0;
arc.yc = -250;
arc.xc = 170;
arc.x2 = 340;
sarc.y2 = 0;
stage.addChild(arc);