Merge branch 'Deprecated'

CreateJS · Jun 29, 2017 · b2650b0 · b2650b0
2 parents 4cd4bf5 + 43c85f8
commit b2650b0
Show file tree

Hide file tree

Showing 5 changed files with 191 additions and 40 deletions.
diff --git a/build/config.json b/build/config.json
@@ -4,6 +4,7 @@
 
 		"../src/createjs/utils/extend.js",
 		"../src/createjs/utils/promote.js",
+		"../src/createjs/utils/deprecate.js",
 		"../src/createjs/utils/indexOf.js",
 		"../src/createjs/utils/proxy.js",
 		"../src/createjs/utils/BrowserDetect.js",

diff --git a/src/createjs/utils/deprecate.js b/src/createjs/utils/deprecate.js
@@ -0,0 +1,69 @@
+/*
+* extend
+* Visit http://createjs.com/ for documentation, updates and examples.
+*
+* Copyright (c) 2010 gskinner.com, inc.
+*
+* Permission is hereby granted, free of charge, to any person
+* obtaining a copy of this software and associated documentation
+* files (the "Software"), to deal in the Software without
+* restriction, including without limitation the rights to use,
+* copy, modify, merge, publish, distribute, sublicense, and/or sell
+* copies of the Software, and to permit persons to whom the
+* Software is furnished to do so, subject to the following
+* conditions:
+*
+* The above copyright notice and this permission notice shall be
+* included in all copies or substantial portions of the Software.
+*
+* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+* OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+* NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+* WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+* FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+* OTHER DEALINGS IN THE SOFTWARE.
+*/
+
+/**
+ * @module CreateJS
+ */
+
+// namespace:
+this.createjs = this.createjs||{};
+
+/**
+ * @class Utility Methods
+ */
+
+/**
+ * Wraps deprecated methods so they still be used, but throw warnings to developers.
+ *
+ *	obj.deprecatedMethod = createjs.deprecate("Old Method Name", obj._fallbackMethod);
+ *
+ * The recommended approach for deprecated properties is:
+ *
+ *	try {
+ *		Obj	ect.defineProperties(object, {
+ *			readyOnlyProp: { get: createjs.deprecate("readOnlyProp", function() { return this.alternateProp; }) },
+ *			readWriteProp: {
+ *				get: createjs.deprecate("readOnlyProp", function() { return this.alternateProp; }),
+ *				set: createjs.deprecate("readOnlyProp", function(val) { this.alternateProp = val; })
+ *		});
+ *	} catch (e) {}
+ *
+ * @method deprecate
+ * @param {Function} [fallbackMethod=null] A method to call when the deprecated method is used. See the example for how
+ * @param {String} [name=null] The name of the method or property to display in the console warning.
+ * to deprecate properties.
+ * @return {Function} If a fallbackMethod is supplied, returns a closure that will call the fallback method after
+ * logging the warning in the console.
+ */
+createjs.deprecate = function(fallbackMethod, name) {
+	"use strict";
+	return function() {
+		console && (console.warn || console.log)("Deprecated property or method '"+name+"'. See docs for info.");
+		return fallbackMethod && fallbackMethod.apply(this, arguments);
+	}
+};
diff --git a/src/preloadjs/loaders/AbstractLoader.js b/src/preloadjs/loaders/AbstractLoader.js
@@ -194,6 +194,30 @@ this.createjs = this.createjs || {};
 	var p = createjs.extend(AbstractLoader, createjs.EventDispatcher);
 	var s = AbstractLoader;
 
+	// Remove these @deprecated properties after 1.0
+	try {
+		Object.defineProperties(s, {
+			POST: { get: createjs.deprecate(function() { return createjs.Methods.POST; }, "AbstractLoader.POST") },
+			GET: { get: createjs.deprecate(function() { return createjs.Methods.GET; }, "AbstractLoader.GET") },
+
+			BINARY: { get: createjs.deprecate(function() { return createjs.Types.BINARY; }, "AbstractLoader.BINARY") },
+			CSS: { get: createjs.deprecate(function() { return createjs.Types.CSS; }, "AbstractLoader.CSS") },
+			FONT: { get: createjs.deprecate(function() { return createjs.Types.FONT; }, "AbstractLoader.FONT") },
+			FONTCSS: { get: createjs.deprecate(function() { return createjs.Types.FONTCSS; }, "AbstractLoader.FONTCSS") },
+			IMAGE: { get: createjs.deprecate(function() { return createjs.Types.IMAGE; }, "AbstractLoader.IMAGE") },
+			JAVASCRIPT: { get: createjs.deprecate(function() { return createjs.Types.JAVASCRIPT; }, "AbstractLoader.JAVASCRIPT") },
+			JSON: { get: createjs.deprecate(function() { return createjs.Types.JSON; }, "AbstractLoader.JSON") },
+			JSONP: { get: createjs.deprecate(function() { return createjs.Types.JSONP; }, "AbstractLoader.JSONP") },
+			MANIFEST: { get: createjs.deprecate(function() { return createjs.Types.MANIFEST; }, "AbstractLoader.MANIFEST") },
+			SOUND: { get: createjs.deprecate(function() { return createjs.Types.SOUND; }, "AbstractLoader.SOUND") },
+			VIDEO: { get: createjs.deprecate(function() { return createjs.Types.VIDEO; }, "AbstractLoader.VIDEO") },
+			SPRITESHEET: { get: createjs.deprecate(function() { return createjs.Types.SPRITESHEET; }, "AbstractLoader.SPRITESHEET") },
+			SVG: { get: createjs.deprecate(function() { return createjs.Types.SVG; }, "AbstractLoader.SVG") },
+			TEXT: { get: createjs.deprecate(function() { return createjs.Types.TEXT; }, "AbstractLoader.TEXT") },
+			XML: { get: createjs.deprecate(function() { return createjs.Types.XML; }, "AbstractLoader.XML") }
+		});
+	} catch (e) {}
+
 // Events
 	/**
 	 * The {{#crossLink "ProgressEvent"}}{{/crossLink}} that is fired when the overall progress changes. Prior to

diff --git a/src/soundjs/Sound.js b/src/soundjs/Sound.js
@@ -442,36 +442,63 @@ this.createjs = this.createjs || {};
 
 
 // class getter / setter properties
+
 	/**
 	 * Set the master volume of Sound. The master volume is multiplied against each sound's individual volume.  For
 	 * example, if master volume is 0.5 and a sound's volume is 0.5, the resulting volume is 0.25. To set individual
-	 * sound volume, use AbstractSoundInstance {{#crossLink "AbstractSoundInstance/volume:property"}}{{/crossLink}} instead.
+	 * sound volume, use AbstractSoundInstance {{#crossLink "AbstractSoundInstance/volume:property"}}{{/crossLink}}
+	 * instead.
 	 *
 	 * <h4>Example</h4>
 	 *
 	 *     createjs.Sound.volume = 0.5;
 	 *
-	 *
 	 * @property volume
 	 * @type {Number}
 	 * @default 1
 	 * @since 0.6.1
 	 */
+
+	/**
+	 * The internal volume level. Use {{#crossLink "Sound/volume:property"}}{{/crossLink}} to adjust the master volume.
+	 * @property _masterVolume
+	 * @type {number}
+	 * @default 1
+	 * @private
+	 */
 	s._masterVolume = 1;
-	Object.defineProperty(s, "volume", {
-		get: function () {return this._masterVolume;},
-		set: function (value) {
-				if (Number(value) == null) {return false;}
-				value = Math.max(0, Math.min(1, value));
-				s._masterVolume = value;
-				if (!this.activePlugin || !this.activePlugin.setVolume || !this.activePlugin.setVolume(value)) {
-					var instances = this._instances;
-					for (var i = 0, l = instances.length; i < l; i++) {
-						instances[i].setMasterVolume(value);
-					}
-				}
+
+	/**
+	 * Use the {{#crossLink "Sound/volume:property"}}{{/crossLink}} property instead.
+	 * @method _getMasterVolume
+	 * @private
+	 * @static
+	 * @return {Number}
+	 **/
+	s._getMasterVolume = function() {
+		return this._masterVolume;
+	};
+	// Sound.getMasterVolume is @deprecated. Remove for 1.1+
+	s.getVolume = createjs.deprecate(s._getMasterVolume, "Sound.getVolume");
+	/**
+	 * Use the {{#crossLink "Sound/volume:property"}}{{/crossLink}} property instead.
+	 * @method _setMasterVolume
+	 * @static
+	 * @private
+	 **/
+	s._setMasterVolume = function(value) {
+		if (Number(value) == null) { return; }
+		value = Math.max(0, Math.min(1, value));
+		s._masterVolume = value;
+		if (!this.activePlugin || !this.activePlugin.setVolume || !this.activePlugin.setVolume(value)) {
+			var instances = this._instances;
+			for (var i = 0, l = instances.length; i < l; i++) {
+				instances[i].setMasterVolume(value);
 			}
-	});
+		}
+	};
+	// Sound.stMasterVolume is @deprecated. Remove for 1.1+
+	s.setVolume = createjs.deprecate(s._setMasterVolume, "Sound.setVolume");
 
 	/**
 	 * Mute/Unmute all audio. Note that muted audio still plays at 0 volume. This global mute value is maintained
@@ -489,22 +516,39 @@ this.createjs = this.createjs || {};
 	 * @since 0.6.1
 	 */
 	s._masterMute = false;
-	// OJR references to the methods were not working, so the code had to be duplicated here
-	Object.defineProperty(s, "muted", {
-		get: function () {return this._masterMute;},
-		set: function (value) {
-				if (value == null) {return false;}
-
-				this._masterMute = value;
-				if (!this.activePlugin || !this.activePlugin.setMute || !this.activePlugin.setMute(value)) {
-					var instances = this._instances;
-					for (var i = 0, l = instances.length; i < l; i++) {
-						instances[i].setMasterMute(value);
-					}
-				}
-				return true;
+
+	/**
+	 * Use the {{#crossLink "Sound/muted:property"}}{{/crossLink}} property instead.
+	 * @method _getMute
+	 * @returns {Boolean}
+	 * @static
+	 * @private
+	 */
+	s._getMute = function () {
+		return this._masterMute;
+	};
+	// Sound.getMute is @deprecated. Remove for 1.1+
+	s.getMute = createjs.deprecate(s._getMute, "Sound.getMute");
+
+	/**
+	 * Use the {{#crossLink "Sound/muted:property"}}{{/crossLink}} property instead.
+	 * @method _setMute
+	 * @param {Boolean} value The muted value
+	 * @static
+	 * @private
+	 */
+	s._setMute = function (value) {
+		if (value == null) { return; }
+		this._masterMute = value;
+		if (!this.activePlugin || !this.activePlugin.setMute || !this.activePlugin.setMute(value)) {
+			var instances = this._instances;
+			for (var i = 0, l = instances.length; i < l; i++) {
+				instances[i].setMasterMute(value);
 			}
-	});
+		}
+	};
+	// Sound.setMute is @deprecated. Remove for 1.1+
+	s.setMute = createjs.deprecate(s._setMute, "Sound.setMute");
 
 	/**
 	 * Get the active plugins capabilities, which help determine if a plugin can be used in the current environment,
@@ -540,12 +584,23 @@ this.createjs = this.createjs || {};
 	 * @readOnly
 	 * @since 0.6.1
 	 */
-	Object.defineProperty(s, "capabilities", {
-		get: function () {
-					if (s.activePlugin == null) {return null;}
-					return s.activePlugin._capabilities;
-				},
-		set: function (value) { return false;}
+
+	/**
+	 * Use the {{#crossLink "Sound/capabilities:property"}}{{/crossLink}} property instead.
+	 * @returns {null}
+	 * @private
+	 */
+	s._getCapabilities = function() {
+		if (s.activePlugin == null) { return null; }
+		return s.activePlugin._capabilities;
+	};
+	// Sound.getCapabilities is @deprecated. Remove for 1.1+
+	s.getCapabilities = createjs.deprecate(s._getCapabilities, "Sound.getCapabilities");
+
+	Object.defineProperties(s, {
+		volume: { get: s._getMasterVolume, set: s._setMasterVolume },
+		muted: { get: s._getMute, set: s._setMute },
+		capabilities: { get: s._getCapabilities }
 	});
 
 

diff --git a/src/soundjs/data/PlayPropsConfig.js b/src/soundjs/data/PlayPropsConfig.js
@@ -153,10 +153,12 @@ this.createjs = this.createjs || {};
 	 * @static
 	 */
 	s.create = function (value) {
-		if (value == null || value instanceof s || value instanceof Object) {
-			var ppc = new createjs.PlayPropsConfig();
-			ppc.set(value);
-			return ppc;
+		if (typeof(value) === "string") {
+			// Handle the old API gracefully.
+			console && (console.warn || console.log)("Deprecated behaviour. Sound.play takes a configuration object instead of individual arguments. See docs for info.");
+			return createjs.PlayPropsConfig().set({interrupt:value});
+		} else if (value == null || value instanceof s || value instanceof Object) {
+			return new createjs.PlayPropsConfig().set(value);
 		} else if (value == null) {
 			throw new Error("PlayProps configuration not recognized.");
 		}