Application Class

Matt Karl edited this page Dec 16, 2015 · 13 revisions

Application is the first class you need to create to get started using the framework. Application is included in the core and accessible from the namespace springroll.Application.

Usage

It's assumed that there can only ever be a single springroll.Application instance created. Here's a basic HTML page setup.

<html>
	<head>
		<!-- PreloadJS is required if loading assets -->
		<script src="bower_components/preloadjs/lib/preloadjs.min.js"></script>

		<!-- Core is required! -->
		<script src="bower_components/springroll/dist/core.min.js"></script>
		<script src="bower_components/springroll/dist/modules/display-native.min.js"></script>
	</head>
	<body>
		<canvas id="stage" width="600" height="400"></canvas>
		<script>

			// Create the application, provide additional options
			var app = new springroll.Application({
				canvasId: "stage",
				display: springroll.native.NativeDisplay
			});

			// Listen for when the application
			// has been fully initialized
			app.on('init', function(){
				// Ready!
			});

		</script>
	</body>
</html>

Options

The application provides options to be passed in through the constructor (e.g., new springroll.Application(options)).

options.fps

  • Type: int
  • Default: 60

The number of frames per second that Application attempts to run at. If you're using CreateJS assets which are animated at a specific frame (say 15 fps), it's better to use SpringRoll's fork of EaselJS which allows for framerate-independent MovieClips.

options.raf

  • Type: boolean
  • Default: true

If the Application should try to use the requestAnimationFrame API. This is not available in all browser, but Application internally will take care of this. Set raf to false if you NEVER want to use the requestAnimationFrame API in JavaScript.

options.versionFile

  • Type: string
  • Default: null

Web browsers manage their own cache. If you deploy a new version of your application, you'll want to make sure that any assets that are changed get busted (or removed) from the browser cache. You can do this manually by calling adding a unique query string to a file request (e.g. assets/images/background.jpg becomes assets/images/background.jpg?v=1) or by using the versionFile option. Define the path to a text file which contains the asset path and a version number. For instance if versionFile was set to a string of versions.txt and versions.txt looked something like this:

assets/images/background.jpg 1
assets/images/playButton.png 2
assets/config/config.json 10

Every time once of those assets changes, simply increment the version number. This is recommended for a production environment.

options.cacheBust

  • Type: boolean
  • Default: false

Similar to versionFile but all file request are given a unique query string to ensure that every load invalidates the web browser's cache. This should be use only for development and debugging purposes only!

var app = new springroll.Application({
	cacheBust: true
});

app.on('init', function(){
	// Since cacheBust is one, the file that is requested would be 
	// "assets/config.json?v=230942890", where v is some random number
	Loader.instance.load("assets/config.json", function(result){
		// File returned!
	});
});

options.basePath

  • Type: string
  • Default: null

The prepended path to any files being loaded by the Loader class. Normally, all assets are loaded relatively from the HTML file where the Application was created. The basePath option can allow for absolute path where to load the assets from. This could be used, for example, to load all your assets from a CDN.

var app = new springroll.Application({
	basePath: 'http://cdn.example.com/'
});

app.on('init', function(){
	// pasePath will be appended to the file requested
	// e.g., "http://cdn.example.com/assets/config.json"
	Loader.instance.load("assets/config.json", function(result){
		// File returned
	});
});

options.resizeElement

  • Type: string, DOMElement, Window
  • Default: null

If you want your application to automatically resize the canvas to the size of a specific element. This can either be a string of the id of a DOM element, the actual DOMElement or the Window object. The application will change the width and height properties of the displays to fill the fit the width and height of the resize element.

options.responsive

  • Type: Boolean
  • Default: false

If responsive is true, the width and height properties on the <canvas> element are changed on Application resize. If responsive is false, the style attribute width and height are set on Application resize. It's assumed that responsive applications will adjust their own elements.

options.uniformResize

  • Type: boolean
  • Default: true

By default, elements which are resize using options.resizeElement are resized proportional to the original width and height of the canvas. If you wish to un-uniformly resize the canvas, set uniformResize to false.

options.maxWidth

If doing uniform resizing, optional parameter to add a maximum width relative to the original height. This allows for "title-safe" responsiveness. Must be greater than the original width of the canvas.

  • Type: int
  • Default: 0

options.maxHeight

If doing uniform resizing, optional parameter to add a maximum height relative to the original width. This allows for "title-safe" responsiveness. Must be greater than the original height of the canvas.

  • Type: int
  • Default: 0

options.debug

  • Type: boolean
  • Default: false

Most debugging in JavaScript is done using the console API. This can trace out information to the web browser's console display. The Application comes with it's own special flavor of console (called Debug) which comes with some useful features. Instead of console.log, use Debug.log in your application. This Application option will automatically turn on/off all output of the Debug class.

options.minLogLevel

  • Type: int
  • Default: 0

If you use Debug in your Application (see options.debug above), the minimum log level to can be useful to filter log spamming. A value of 0 (default) shows all log types sent with Debug.log(),Debug.debug(), Debug.info(), Debug.warn() and Debug.error(). A value of 4, by comparison, will only show log types sent from Debug.error().

var app = new springroll.Application({
	debug: true, // required to use minLogLevel
	minLogLevel: 2
});

Debug.log("General trace"); // 0 = Silenced
Debug.debug("Debugging trace");  // 1 = Silenced
Debug.info("Info trace"); // 2 = Shown
Debug.warn("Warning trace"); // 3 = Shown
Debug.error("Erroring trace");  // 4 = Shown

options.debugRemote

  • Type: string
  • Default: null

The Debug class (see options.debug above) can support remote debugging over the network using JavaScript's WebSockets. For older Android tablets which don't support remote debugging, you can specify the local network IP address or host name and any logs sent through Debug will be broadcasted to that IP address.

options.queryStringParameters

  • Type: boolean
  • Default: false

Useful for debugging, will allow Application options to be set by the query string in the browser. For instance, if this is set to a value of true, "?fps=10&debug=true" will set the Application options fps and debug.

options.updateTween

  • Type: boolean
  • Default: true

If using TweenJS, setting this to true, the Application will update the Tween itself. If set to false, you're responsible for updating Tween.

options.canvasId

  • Type: string
  • Default: null

The DOM element id to use as the default display. Requires options.display to be set. If you don't specify the default display, you can optionally add the display later using Application's addDisplay() method.

options.display

  • Type: function
  • Default: null

The JavaScript "class" to use when creating a new display. Options could include springroll.easeljs.EaselJSDisplay for a CreateJS canvas renderer, springroll.pixi.PixiDisplay for a PixiJS canvas renderer, or springroll.native.NativeDisplay for a native canvas renderer.

options.displayOptions

  • Type: object
  • Default: null

Optional, additional options that get passed to the constructor of the display being created. See the displays for information about specific options.

Methods

addDisplay(id, displayConstructor, [options])

Add a new display to the list of application display. A display is a specific renderer (EaselJS, PIXI, native) attached to a canvas DOMElement on the stage.

Parameters

  • id string The id attribute of the canvas DOMElement
  • displayConstructor function The function to create the new display from. Options include: springroll.easeljs.EaselJSDisplay, springroll.pixi.PixiDisplay, or springroll.native.NativeDisplay
  • options object (optional) Display-specific options

Return object The new display object created.

var display = app.addDisplay(
	"stage", 
	springroll.easeljs.EaselJSDisplay, {
		clearView: true,
		mouseOverRate: 20
	}
);

###getDisplay(id) Get an Application's display by id.

Parameters

  • id string The id attribute of the canvas DOMElement

Return The display object if found, null if not.

var display = app.getDisplay("stage");
Debug.log("Canvas size [" + display.width + ", " + display.height + "]");

###getDisplays() Get a collection of all the current displays.

Return array The list of displays

###removeDisplay(id) Remove an Application's display by an id.The canvas element is not removed from the DOM, only the SpringRoll Display object is destroyed.

Parameters

  • id string The id attribute of the canvas DOMElement
app.removeDisplay("stage");

Events

Event handling is very similar to JQuery or other popular JavaScript libraries. Here are some examples of adding events to the Application:

app.on('init', function(){
	// Ready!
});
app.on({
	init: function(){
		// Ready!
	},
	destroy: function(){
		// Cleanup!
	}
});

init

When the application is initialized and ready to use. All plugins have been preloaded at this point. The default display, if supplied in the options, is available and ready to use. The application is unpaused and updating at this point. This event is the best place to start application logic.

destroy

When the application is destroyed by calling app.destroy(). Other modules and components and listen to the destroy event and do any required clean-up of timers, event listeners, etc.

update

The main frame update, or tick of the application. No need to create your own setInterval, just listen to the update event.

Arguments

  • elapsed int The number of milliseconds since the last frame update was completed.

pause

The pause event happen whenever a change in either pausing or resuming the Application.

Arguments

  • paused boolean What the paused state of the application is.

paused

The paused event happens when the Application becomes paused.

resumed

The resume event happens when the Application resumes from a paused state.

resize

The resize event happens whenever the Application displays are resized.

Arguments

  • width number The new width of the Application
  • height height The new height of the Application
var center;
app.on('resize', function(width, height){
	// Get the new center point of the application	
	center = {
		x : width / 2,
		y : height / 2
	};
});

API Documentation

To see the full list of methods available to springroll.Application please see the full documentation.