AppManager

The AppManager is a class that assists with the management of application assets. These assets can be canvas elements, iio Objects, or a Box2D world.

The main iio start functions are designed to provide an application script with a new instantiation of an AppManager:

MyApplication = function(AppManager){
  
  //AppManager's properties are ready to go
  alert(AppManager.canvas.width);

}; iio.start(MyApplication, 'canvasId');

Note that you can name the AppManager parameter anything you want. I always shorten it to io for convenience.

All code samples on this documentation page are assumed to be inside a main application function where a reference to the AppManager exists.

 

Properties

Your AppManager has references to your application's canvas elements and to those canvas' 2d contexts.

The initial canvas element assigned to the application - either specified in start or auto generated - is referred to as the 'base canvas'.

The base canvas is the most accessible canvas element and should be used for whichever object layer is updated most frequently.

You can create additional canvases by using the addCanvas function.

All canvas elements are stored in the array property cnvs. The base canvas is at index 0 and can also be accessed through the property canvas.

 

.canvas :: Canvas

- The base canvas of the application

//get the dimenstions of the base canvas element
var w = io.canvas.width;
var h = io.canvas.height;
 

.context :: Canvas 2d Context

- The 2d context of the base canvas element.

//get the base canvas' 2d context
var context = io.context;
 

.cnvs :: Array

- An array of this application's canvas elements. In many cases, applications will only need one canvas, so the property .canvas also exists.

- .canvas and .cnvs[0] are pointers to the same Canvas object.

//create a new canvas element and get its width
iio.addCanvas();
//assuming this is the first call to addCanvas..
var w = io.cnvs[1].width;
 

.ctxs :: Array

- An array of this application's canvas' contexts. In many cases, applications will only need one canvas, so the property .context also exists.

.context and .ctxs[0] are pointers to the same Canvas 2d context.

//get the context of a second canvas element
var context = io.ctxs[1];
 

Framerate Control Functions

You can use these functions to start, pause, and cancel a continuous update loop on a canvas or an object. The loop will automatically update objects based on their properties and re-render them when required.

In general, it is best to set a framerate on a canvas if you need to have a lot of objects moving around. If movement is occasional, large efficiency gains can be made by attaching framerates to objects instead of their parent canvas.

Combining both of these methods on mutliple canvas layers can sometimes be the best solution for apps that require both static and dynamic content.

 

setFramerate( Number fps, Function callback, Number c )

setFramerate( Number fps, Obj obj, Context ctx, Function callback )

:: Returns this

- this function sets a framerate on the given object or canvas at the given speed (frames per second).

- A canvas with a framerate will update all its objects and call the specified callback function, then clear the canvas and re-render it, on each frame update. c is a cnvs index. If c is undefined, this function will act on the base canvas.

- An object with a framerate will call its own update function on each new frame. If the object changes its position, rotation, or animation frame, it will clear itself and re-render (which is why you have to give it a context). This technique is useful when you have few moving objects that don't overlap because the only part of the canvas that gets cleared and redrawn is the space the object occupies.

//set a 60fps framerate on the base canvas
io.setFramerate(60);

//set a framerate and specify a callback function
io.setFramerate(60, function(){
  //code called 60x a second...
});

//set a framerate on a background canvas
//without a callback function
io.setFramerate(5,null,1);

//set a framerate on an object
//in the base canvas
io.setFramerate(60, new iio.Rect(0,0,60)
                    .enableKinematics()
                    .setVel(2,2));
 

pauseFramerate( Boolean pause )

pauseFramerate( Boolean pause, Obj obj obj )

:: Returns this || obj

- pauses a previously set framerate.

- if no object is specified, all canvas framerates are paused. Otherwise the framerate loop set on the object is paused.

- the default value for pause is true if this function has not been called before. Otherwise, this function will act as a toggle.

//pause canvas framerates
io.pauseFramerate();

//unpause canvas framerates
io.pauseFramerate();
 

cancelFramerate( Number canvasIndex )

cancelFramerate( Obj obj )

:: Returns this || obj

- cancels a previously set framerate.

- if no parameters are given, the framerate on the base canvas is cancelled. If a canvas index is given, the framerate on that canvas will be cancelled.

- if an Obj is given, the framerate set on that object will be cancelled and this function will return the object.

//cancel base canvas framerate
io.cancelFramerate();

//cancel framerate on object
io.cancelFramerate( obj );
 

setAnimFPS( Number fps, Obj obj, Number canvasId )

:: Returns Number

- Sets a callback on the given object that changes its animation frame, and clears and redraws itself on each step.

//animate an object at 24fps
io.setAnimFPS(24, myAnimObject);
 

Canvas Control Functions

These functions give you control over your application's canvas elements. Most applications are best off using just one canvas, but an addCanvas function exists for cases in which an application has object layers that do not have to be redrawn on every update.

 

draw( Number c )

:: Returns this

- clears and re-renders the canvas at cnvs index c. If c is undefined, this function acts on the base canvas.

//render a canvas with objects
//(see object control)
io.draw();

//render a background canvas
io.draw(1);
 

addCanvas()

addCanvas( String canvasId )

addCanvas( Number zIndex )

addCanvas( Number: zIndex, w, h )

addCanvas( Number: zIndex, w, h, Array cssClasses )

addCanvas( Number: zIndex, w, h, String attachElementId )

addCanvas( Number: zIndex, w, h, String: attachElementId, cssClass )

addCanvas( Number zIndex, w, h, String attachElementId, Array cssClasses )

:: Returns Number :: the index of the new canvas

- Creates a new canvas element. This canvas will be positioned absolutely behind the base canvas unless a canvasId or attachElementId is specified.

- The zIndex controls the new canvas' position in the stack - a higher number puts it closer to the top, a lower number puts it closer to the bottom. This number may be negative. The base canvas has a zIndex of 0. If zIndex is not provided, the new canvas will be given a zIndex equal to the negative value of its index.

- If a canvasId is provided, the new canvas index will refer to the given element. If an attachElementId is provided, a new canvas will be created and attached to the given element. No css properties will be altered in either of these cases. If no ids are specified though, the new canvas will be auto generated and given the css class ioCanvas.

- The css class's referred to in the cssClass or cssClasses parameters will applied to the new canvas object.

- If you send null as a parameter value, the function will get the value from the base canvas.


//the base canvas already exists
//we can get properties from it like this:
var w = io.canvas.width;
//or
var w = io.cnvs[0].width;

//create a red background canvas
io.setBGColor('red',io.addCanvas());

//add a canvas that already exists
io.addCanvas('myCanvasId');

//add a foreground canvas
io.addCanvas(10); //zIndex will be 10

//add a new canvas and assign it a class
//use null so we keep the dimensions of the base canvas
io.addCanvas(-10, null, null, ['myCssClass']);

//add a 400x600 canvas 
//attach it to a specified element
//assign it a list of class's
io.addCanvas(0, 400, 600, 'myElementId', ['class1', 'class2']);
 

getEventPosition( DOM Event event, Number c )

:: Returns Vec

- returns the event's position as an Vec relative to the specified canvas's origin (its top-left corner). If no c is specified, the base canvas is used.

- this function can handle all canvas positioning possibilities. It doesn't matter where a canvas is or if the user has scrolled across the page - this function will give you the accurate event position relative to the canvas's origin.

//alert with mouse click position
io.canvas.addEventListener('mousedown', function(event){
    alert(io.getEventPosition(event).toString());
});
 

setBGColor( String color, Number c )

:: Returns AppManager

- Sets the css background-color property to the given color. This function will act on the base canvas unless a different c is specified.

- Colors can be specified as css color keywords, hexadecimal values, rgb values, or rgba values. See w3schools for a good hexadecimal color picker.

//set background color to white
//using a css color keyword
io.setBGColor('white');

//set background color to red
//using rbg values
io.setBGColor('rgb(255,0,0)');

//add a background canvas
//set its background color to blue
//using a hexadecimal value
io.addCanvas();
io.setBGColor('#00F',1);

//add a foreground canvas
//set its background color to semi-transparent black
//using rgba values
io.addCanvas();
io.setBGColor('rgba(0,0,0,.5)',2);
 

setBGPattern( String imagePath )

setBGPattern( String imagePath, Number c )

:: Returns Boolean

- Sets the css background image of this canvas to the given image. Horizontal and vertical image repetition are active by default. This function will act on the base canvas unless a different c is specified.

//set a background image
io.setBGPattern('myBGPattern.png');

//add a canvas and give it a background pattern
io.setBGPattern('myBGPattern.png', io.addCanvas());
 

setBGImage( String imagePath )

setBGImage( String imagePath, Number c )

:: Returns AppManager

- Sets the css background image of this canvas to the given image and disables vertical and horizontal repeats. This function will act on the base canvas unless a different c is specified.

//set a background image
io.setBGImage('myBG.jpg');

//add a canvas and give it a background image
io.setBGImage('myBG.jpg', io.addCanvas());
 

Object Control Functions

The AppManager can help you manage objects by automatically calling their update and draw functions when you need to re-render the screen.

Objects are always stored in a group structure, but you can simplify dealing with a mono-group by using the addObj and rmvObj functions.

 

addObj( Obj obj, Number c )

:: Returns Obj - the object you gave it

- Adds the given object to the canvas at the given index. If no index is specified, the object is added to the base canvas.

//give a new blue box to the base canvas
io.addObj(new iio.Rect(0,0,60)
    .setFillStyle('blue'));

//give a new blue box to a second canvas
io.addObj(new iio.Rect(0,0,60)
    .setFillStyle('blue'), 1);
 

rmvObj( Obj obj, Number c )

:: Returns Boolean - tells you if it was successful

- removes the given object from the canvas at the given index. If no index is specified, the object is removed from the base canvas.

//remove an object from the base canvas
io.rmvObj(myObj);

//remove an object from the second canvas
io.rmvObj(myObj, 1);
 

rmvAll( Number c )

:: Returns this

- removes all objects from the canvas at the given index. If no index is specified, the objects are removed from the base canvas.

//remove all objects from the base canvas
io.rmvAll();

//remove all objects from the second canvas
io.rmvAll(1);
 

addGroup( String tag, Number zIndex, Number c )

:: Returns Number

- creates a new group in the specified canvas with the given tag at the given z-index. 0 is the default zIndex, and the function will act on the base canvas if no c is given.

//add a group for box objects
//at zIndex 10
io.addGroup('boxes', 10);
 

addToGroup( String tag, Obj obj, Number zIndex, Number c )

:: Returns Obj

- adds the given object to the given group in the specified canvas. If the group does not exist, a new group is created and added. 0 is the default zIndex, and the function will act on the base canvas if no c is given.

//add a new box to a new 'boxes' group
io.addToGroup('boxes', new iio.Rect(0,0,60), 10);
 

rmvFromGroup( String tag, Obj obj, Number c )

rmvFromGroup( String tag, Number c )

:: Returns Boolean

NOTE: this is an updated function available in the 1.2.2+ version of iio (download on Github). The previous verions of iio have a rmvFromGroup(obj, tag, c) function.

- removes the given object from the given group in the specified canvas. This function will act on the base canvas if no c is given.

- if no obj is specified, all objects will be removed from the group.

//remove an object from a group
io.rmvFromGroup('boxes', myBox);

//remove all objects from a group
io.rmvFromGroup('boxes');

//remove objects from a second canvas group
io.rmvFromGroup('boxes', 1);
 

getGroup( String tag, Number: canvasId, from, to )

:: Returns Array

- returns an array containing the objects in the specified group.

- if from and to are specified, the returned array will contain the objects in the group in the range [from, to).

- if only from is specified, the returned array will only contain the object at that that index.

//get all objects in 'boxes' group
var boxes = io.getGroup('boxes');

//get the second object in 'boxes' group
var scndBox = io.getGroup('boxes', 0, 2)[0];
 

setCollisionCallback( String tag, Function callback, Number c )

setCollisionCallback( String tag1, String tag2, Function callback, Number c )

:: Returns Number

- Sets a callback function for the collision between objects in a single group or between two groups in the specified canvas. If no c is given, this method acts on the base canvas

- See this page for an in depth look at a collision example.

//set a collision callback on objects of two groups
io.setCollisionCallback(groupTag1, groupTag2, function(obj1, obj2){
    //Collision callback code...
});

//set a collision callback on objects in the same group
io.setCollisionCallback(groupTag, function(obj1, obj2){
    //Collision callback code...
});