diff --git a/.eslintrc.json b/.eslintrc.json index 3df3a43cf..c683cd504 100644 --- a/.eslintrc.json +++ b/.eslintrc.json @@ -9,7 +9,8 @@ "WEBGL_RENDERER": true, "CANVAS_RENDERER": true, "Phaser": true, - "p2": true + "p2": true, + "ActiveXObject": true }, "rules": { diff --git a/src/dom/AddToDOM.js b/src/dom/AddToDOM.js index 79707915d..3cf6146ea 100644 --- a/src/dom/AddToDOM.js +++ b/src/dom/AddToDOM.js @@ -1,14 +1,15 @@ /** - * [description] + * Adds the given element to the DOM. If a parent is provided the element is added as a child of the parent, providing it was able to access it. + * If no parent was given or falls back to using `document.body`. * * @function Phaser.Dom.AddToDOM * @since 3.0.0 * - * @param {any} element - [description] - * @param {any} parent - [description] + * @param {object} element - The element to be added to the DOM. Usually a Canvas object. + * @param {string|object} [parent] - The parent in which to add the element. Can be a string which is passed to `getElementById` or an actual DOM object. * @param {boolean} [overflowHidden=true] - [description] * - * @return {any} [description] + * @return {object} The element that was added to the DOM. */ var AddToDOM = function (element, parent, overflowHidden) { diff --git a/src/dom/DOMContentLoaded.js b/src/dom/DOMContentLoaded.js index b7be4c09d..2dd9167bc 100644 --- a/src/dom/DOMContentLoaded.js +++ b/src/dom/DOMContentLoaded.js @@ -3,7 +3,9 @@ var OS = require('../device/OS'); var isBooted = false; /** - * [description] + * Inspects the readyState of the document. If the document is already complete then it invokes the given callback. + * If not complete it sets up several event listeners such as `deviceready`, and once those fire, it invokes the callback. + * Called automatically by the Phaser.Game instance. Should not usually be access directly. * * @function Phaser.Dom.DOMContentLoaded * @since 3.0.0 diff --git a/src/dom/ParseXML.js b/src/dom/ParseXML.js index a358bf948..4335ae7e8 100644 --- a/src/dom/ParseXML.js +++ b/src/dom/ParseXML.js @@ -1,12 +1,14 @@ /** - * [description] + * Takes the given data string and parses it as XML. + * First tries to use the window.DOMParser and reverts to the Microsoft.XMLDOM if that fails. + * The parsed XML object is returned, or `null` if there was an error while parsing the data. * * @function Phaser.Dom.ParseXML * @since 3.0.0 * * @param {string} data - The XML source stored in a string. * - * @return {any} [description] + * @return {any} The parsed XML data, or `null` if the data could not be parsed. */ var ParseXML = function (data) { diff --git a/src/dom/RemoveFromDOM.js b/src/dom/RemoveFromDOM.js index 55432103f..253625e20 100644 --- a/src/dom/RemoveFromDOM.js +++ b/src/dom/RemoveFromDOM.js @@ -1,10 +1,10 @@ /** - * [description] + * Attempts to remove the element from its parentNode in the DOM. * * @function Phaser.Dom.RemoveFromDOM * @since 3.0.0 * - * @param {any} element - [description] + * @param {any} element - The DOM element to remove from its parent node. */ var RemoveFromDOM = function (element) { diff --git a/src/dom/RequestAnimationFrame.js b/src/dom/RequestAnimationFrame.js index 02507de92..a1f339b83 100644 --- a/src/dom/RequestAnimationFrame.js +++ b/src/dom/RequestAnimationFrame.js @@ -1,67 +1,149 @@ +var Class = require('../utils/Class'); var NOOP = require('../utils/NOOP'); -// Abstracts away the use of RAF or setTimeOut for the core game update loop. -var RequestAnimationFrame = function () -{ - // @property {boolean} isRunning - true if RequestAnimationFrame is running, otherwise false. - this.isRunning = false; +var RequestAnimationFrame = new Class({ - this.callback = NOOP; + initialize: - this.tick = 0; - - // @property {boolean} isSetTimeOut - True if the browser is using setTimeout instead of rAf. - this.isSetTimeOut = false; - - // @property {number} timeOutID - The callback setTimeout or rAf callback ID used when calling cancel. - this.timeOutID = null; - - var _this = this; - - // timestamp = DOMHighResTimeStamp - var step = function (timestamp) + /** + * Abstracts away the use of RAF or setTimeOut for the core game update loop. + * This is invoked automatically by the Phaser.Game instance. + * + * @class RequestAnimationFrame + * @memberOf Phaser.DOM + * @constructor + * @since 3.0.0 + */ + function RequestAnimationFrame () { - _this.tick = timestamp; + /** + * True if RequestAnimationFrame is running, otherwise false. + * + * @property {boolean} isRunning + * @default false + * @since 3.0.0 + */ + this.isRunning = false; - _this.callback(timestamp); + /** + * The callback to be invoked each step. + * + * @property {function} callback + * @since 3.0.0 + */ + this.callback = NOOP; - _this.timeOutID = window.requestAnimationFrame(step); - }; + /** + * The most recent timestamp. Either a DOMHighResTimeStamp under RAF or `Date.now` under SetTimeout. + * + * @property {DOMHighResTimeStamp|number} tick + * @default 0 + * @since 3.0.0 + */ + this.tick = 0; - var stepTimeout = function () - { - var d = Date.now(); + /** + * True if the step is using setTimeout instead of RAF. + * + * @property {boolean} isSetTimeOut + * @default false + * @since 3.0.0 + */ + this.isSetTimeOut = false; - _this.tick = d; + /** + * The setTimeout or RAF callback ID used when canceling them. + * + * @property {?number} timeOutID + * @default null + * @since 3.0.0 + */ + this.timeOutID = null; - _this.callback(d); + /** + * The previous time the step was called. + * + * @property {number} lastTime + * @default 0 + * @since 3.0.0 + */ + this.lastTime = 0; - _this.timeOutID = window.setTimeout(stepTimeout, _this.timeToCall); - }; + var _this = this; - this.step = step; - this.stepTimeout = stepTimeout; -}; + /** + * The RAF step function. + * Updates the local tick value, invokes the callback and schedules another call to requestAnimationFrame. + * + * @property {function} step + * @since 3.0.0 + */ + this.step = function step (timestamp) + { + // DOMHighResTimeStamp + _this.lastTime = _this.tick; -RequestAnimationFrame.prototype.constructor = RequestAnimationFrame; + _this.tick = timestamp; -RequestAnimationFrame.prototype = { + _this.callback(timestamp); - // Starts the requestAnimationFrame running or setTimeout if unavailable in browser + _this.timeOutID = window.requestAnimationFrame(step); + }; + + /** + * The SetTimeout step function. + * Updates the local tick value, invokes the callback and schedules another call to setTimeout. + * + * @property {function} stepTimeout + * @since 3.0.0 + */ + this.stepTimeout = function stepTimeout () + { + var d = Date.now(); + + var delay = Math.max(16 + _this.lastTime - d, 0); + + _this.lastTime = _this.tick; + + _this.tick = d; + + _this.callback(d); + + _this.timeOutID = window.setTimeout(stepTimeout, delay); + }; + }, + + /** + * Starts the requestAnimationFrame or setTimeout process running. + * + * @method Phaser.DOM.RequestAnimationFrame#start + * @since 3.0.0 + * + * @param {function} callback - The callback to invoke each step. + * @param {boolean} forceSetTimeOut - Should it use SetTimeout, even if RAF is available? + */ start: function (callback, forceSetTimeOut) { + if (this.isRunning) + { + return; + } + this.callback = callback; this.isSetTimeOut = forceSetTimeOut; this.isRunning = true; - var _this = this; - - this.timeOutID = (forceSetTimeOut) ? window.setTimeout(_this.stepTimeout, 0) : window.requestAnimationFrame(_this.step); + this.timeOutID = (forceSetTimeOut) ? window.setTimeout(this.stepTimeout, 0) : window.requestAnimationFrame(this.step); }, - // Stops the requestAnimationFrame from running. + /** + * Stops the requestAnimationFrame or setTimeout from running. + * + * @method Phaser.DOM.RequestAnimationFrame#stop + * @since 3.0.0 + */ stop: function () { this.isRunning = false; @@ -76,6 +158,12 @@ RequestAnimationFrame.prototype = { } }, + /** + * Stops the step from running and clears the callback reference. + * + * @method Phaser.DOM.RequestAnimationFrame#destroy + * @since 3.0.0 + */ destroy: function () { this.stop(); @@ -83,6 +171,6 @@ RequestAnimationFrame.prototype = { this.callback = NOOP; } -}; +}); module.exports = RequestAnimationFrame; diff --git a/src/events/EventEmitter.js b/src/events/EventEmitter.js index 1193bd59f..396f32898 100644 --- a/src/events/EventEmitter.js +++ b/src/events/EventEmitter.js @@ -2,24 +2,43 @@ var Class = require('../utils/Class'); var EE = require('eventemitter3'); var PluginManager = require('../plugins/PluginManager'); -// Phaser.EventEmitter - var EventEmitter = new Class({ Extends: EE, initialize: + /** + * EventEmitter is a Scene Systems plugin compatible version of eventemitter3. + * + * @class EventEmitter + * @extends eventemitter3 + * @memberOf Phaser.Events + * @constructor + * @since 3.0.0 + */ function EventEmitter () { EE.call(this); }, + /** + * Removes all listeners. + * + * @method Phaser.Events.EventEmitter#shutdown + * @since 3.0.0 + */ shutdown: function () { this.removeAllListeners(); }, + /** + * Removes all listeners. + * + * @method Phaser.Events.EventEmitter#destroy + * @since 3.0.0 + */ destroy: function () { this.removeAllListeners();