https://wonder-wall.com/assets/lib/SpriteContainer.js

1/*
2* SpriteContainer
3* Visit http://createjs.com/ for documentation, updates and examples.
4*
5* Copyright (c) 2010 gskinner.com, inc.
6*
7* Permission is hereby granted, free of charge, to any person
8* obtaining a copy of this software and associated documentation
9* files (the "Software"), to deal in the Software without
10* restriction, including without limitation the rights to use,
11* copy, modify, merge, publish, distribute, sublicense, and/or sell
12* copies of the Software, and to permit persons to whom the
13* Software is furnished to do so, subject to the following
14* conditions:
15*
16* The above copyright notice and this permission notice shall be
17* included in all copies or substantial portions of the Software.
18*
19* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
20* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
21* OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
22* NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
23* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
24* WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
25* FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
26* OTHER DEALINGS IN THE SOFTWARE.
27*/
28
29// namespace:
30this.createjs = this.createjs||{};
31
32(function() {
33	"use strict";
34
35
36	/**
37	 * A SpriteContainer is a nestable display list that enables aggressively optimized rendering of bitmap content.
38	 * In order to accomplish these optimizations, SpriteContainer enforces a few restrictions on its content.
39	 *
40	 * Restrictions:
41	 *     - only Sprite, SpriteContainer, BitmapText and DOMElement are allowed to be added as children.
42	 *     - a spriteSheet MUST be either be passed into the constructor or defined on the first child added.
43	 *     - all children (with the exception of DOMElement) MUST use the same spriteSheet.
44	 *
45	 * <h4>Example</h4>
46	 *
47	 *      var data = {
48	 *          images: ["sprites.jpg"],
49	 *          frames: {width:50, height:50},
50	 *          animations: {run:[0,4], jump:[5,8,"run"]}
51	 *      };
52	 *      var spriteSheet = new createjs.SpriteSheet(data);
53	 *      var container = new createjs.SpriteContainer(spriteSheet);
54	 *      container.addChild(spriteInstance, spriteInstance2);
55	 *      container.x = 100;
56	 *
57	 * <strong>Note:</strong> SpriteContainer is not included in the minified version of EaselJS.
58	 *
59	 * @class SpriteContainer
60	 * @extends Container
61	 * @constructor
62	 * @param {SpriteSheet} [spriteSheet] The spriteSheet to use for this SpriteContainer and its children.
63	 **/
64	function SpriteContainer(spriteSheet) {

65		this.Container_constructor();
66		
67		
68	// public properties:
69		/**
70		 * The SpriteSheet that this container enforces use of.
71		 * @property spriteSheet
72		 * @type {SpriteSheet}
73		 * @readonly
74		 **/
75		this.spriteSheet = spriteSheet;
76	}
77	var p = createjs.extend(SpriteContainer, createjs.Container);
78
79	/**
80	 * <strong>REMOVED</strong>. Removed in favor of using `MySuperClass_constructor`.
81	 * See {{#crossLink "Utility Methods/extend"}}{{/crossLink}} and {{#crossLink "Utility Methods/promote"}}{{/crossLink}}
82	 * for details.
83	 *
84	 * There is an inheritance tutorial distributed with EaselJS in /tutorials/Inheritance.
85	 *
86	 * @method initialize
87	 * @protected
88	 * @deprecated
89	 */
90	// p.initialize = function() {}; // searchable for devs wondering where it is.
91	
92
93// public methods:
94	/**
95	 * Adds a child to the top of the display list.
96	 * Only children of type SpriteContainer, Sprite, Bitmap, BitmapText, or DOMElement are allowed.
97	 * The child must have the same spritesheet as this container (unless it's a DOMElement).
98	 * If a spritesheet hasn't been defined, this container uses this child's spritesheet.
99	 *
100	 * <h4>Example</h4>
101	 *      container.addChild(bitmapInstance);
102	 *
103	 *  You can also add multiple children at once:
104	 *
105	 *      container.addChild(bitmapInstance, shapeInstance, textInstance);
106	 *
107	 * @method addChild
108	 * @param {DisplayObject} child The display object to add.
109	 * @return {DisplayObject} The child that was added, or the last child if multiple children were added.
110	 **/
111	p.addChild = function(child) {
112		if (child == null) { return child; }
113		if (arguments.length > 1) {
114			return this.addChildAt.apply(this, Array.prototype.slice.call(arguments).concat([this.children.length]));
115		} else {
116			return this.addChildAt(child, this.children.length);
117		}
118	};
119
120	/**
121	 * Adds a child to the display list at the specified index, bumping children at equal or greater indexes up one, and
122	 * setting its parent to this Container.
123	 * Only children of type SpriteContainer, Sprite, Bitmap, BitmapText, or DOMElement are allowed.
124	 * The child must have the same spritesheet as this container (unless it's a DOMElement).
125	 * If a spritesheet hasn't been defined, this container uses this child's spritesheet.
126	 *
127	 * <h4>Example</h4>
128	 *      addChildAt(child1, index);
129	 *
130	 * You can also add multiple children, such as:
131	 *
132	 *      addChildAt(child1, child2, ..., index);
133	 *
134	 * The index must be between 0 and numChildren. For example, to add myShape under otherShape in the display list,
135	 * you could use:
136	 *
137	 *      container.addChildAt(myShape, container.getChildIndex(otherShape));
138	 *
139	 * This would also bump otherShape's index up by one. Fails silently if the index is out of range.
140	 *
141	 * @method addChildAt
142	 * @param {DisplayObject} child The display object to add.
143	 * @param {Number} index The index to add the child at.
144	 * @return {DisplayObject} Returns the last child that was added, or the last child if multiple children were added.
145	 **/
146	p.addChildAt = function(child, index) {
147		var l = arguments.length;
148		var indx = arguments[l-1]; // can't use the same name as the index param or it replaces arguments[1]
149		if (indx < 0 || indx > this.children.length) { return arguments[l-2]; }
150		if (l > 2) {
151			for (var i=0; i<l-1; i++) { this.addChildAt(arguments[i], indx+i); }
152			return arguments[l-2];
153		}
154		if (child._spritestage_compatibility >= 1) {
155			// The child is compatible with SpriteStage/SpriteContainer.
156		} else {
157			console && console.log("Error: You can only add children of type SpriteContainer, Sprite, BitmapText, or DOMElement [" + child.toString() + "]");
158			return child;
159		}
160		if (child._spritestage_compatibility <= 4) {
161			var spriteSheet = child.spriteSheet;
162			if ((!spriteSheet || !spriteSheet._images || spriteSheet._images.length > 1) || (this.spriteSheet && this.spriteSheet !== spriteSheet)) {
163				console && console.log("Error: A child's spriteSheet must be equal to its parent spriteSheet and only use one image. [" + child.toString() + "]");
164				return child;
165			}
166			this.spriteSheet = spriteSheet;
167		}
168		if (child.parent) { child.parent.removeChild(child); }
169		child.parent = this;
170		this.children.splice(index, 0, child);
171		return child;
172	};
173
174	/**
175	 * Returns a string representation of this object.
176	 * @method toString
177	 * @return {String} a string representation of the instance.
178	 **/
179	p.toString = function() {
180		return "[SpriteContainer (name="+  this.name +")]";
181	};
182
183
184	createjs.SpriteContainer = createjs.promote(SpriteContainer, "Container");
185}());