UNPKG

172 kBHTMLView Raw
1<!DOCTYPE html>
2
3<html lang="en">
4<head>
5 <meta charset="utf-8">
6 <meta name="viewport" content="width=device-width">
7 <title>CrossBrowdy API documentation Source: CrossBase/audiovisual/image/CB_GraphicSprites.js</title>
8
9 <!--[if lt IE 9]>
10 <script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
11 <![endif]-->
12 <link type="text/css" rel="stylesheet" href="styles/sunlight.default.css">
13
14 <link type="text/css" rel="stylesheet" href="styles/site.cosmo.css">
15
16</head>
17
18<body style="min-width:800px; overflow-wrap:break-word; word-wrap:break-word; word-break:break-word; line-break:strict; hyphens:none; -webkit-hyphens:none; -moz-hyphens:none;">
19
20<div class="navbar navbar-default navbar-fixed-top ">
21<div class="container">
22 <div class="navbar-header">
23 <a class="navbar-brand" href="index.html">CrossBrowdy API documentation</a>
24 <button class="navbar-toggle" type="button" data-toggle="collapse" data-target="#topNavigation">
25 <span class="icon-bar"></span>
26 <span class="icon-bar"></span>
27 <span class="icon-bar"></span>
28 </button>
29 </div>
30 <div class="navbar-collapse collapse" id="topNavigation">
31 <ul class="nav navbar-nav">
32
33 <li class="dropdown">
34 <a href="namespaces.list.html" class="dropdown-toggle" data-toggle="dropdown">Namespaces<b class="caret"></b></a>
35 <ul class="dropdown-menu inline">
36 <li><a href="CB_Arrays.html">CB_Arrays</a></li><li><a href="CB_AudioDetector.html">CB_AudioDetector</a></li><li><a href="CB_Client.html">CB_Client</a></li><li><a href="CB_Collisions.html">CB_Collisions</a></li><li><a href="CB_Configuration.html">CB_Configuration</a></li><li><a href="CB_Configuration.CrossBase.html">CB_Configuration.CrossBase</a></li><li><a href="CB_Configuration.CrossBrowdy.html">CB_Configuration.CrossBrowdy</a></li><li><a href="CB_Controllers.html">CB_Controllers</a></li><li><a href="CB_Controllers_Proprietary.html">CB_Controllers_Proprietary</a></li><li><a href="CB_Controllers_Proprietary.WII.html">CB_Controllers_Proprietary.WII</a></li><li><a href="CB_Controllers_Proprietary.WII_U.html">CB_Controllers_Proprietary.WII_U</a></li><li><a href="CB_Device.html">CB_Device</a></li><li><a href="CB_Device.AmbientLight.html">CB_Device.AmbientLight</a></li><li><a href="CB_Device.Battery.html">CB_Device.Battery</a></li><li><a href="CB_Device.Location.html">CB_Device.Location</a></li><li><a href="CB_Device.Motion.html">CB_Device.Motion</a></li><li><a href="CB_Device.Orientation.html">CB_Device.Orientation</a></li><li><a href="CB_Device.Proximity.html">CB_Device.Proximity</a></li><li><a href="CB_Device.Vibration.html">CB_Device.Vibration</a></li><li><a href="CB_Elements.html">CB_Elements</a></li><li><a href="CB_Events.html">CB_Events</a></li><li><a href="CB_Keyboard.html">CB_Keyboard</a></li><li><a href="CB_Keyboard.chars.html">CB_Keyboard.chars</a></li><li><a href="CB_Keyboard.extended.html">CB_Keyboard.extended</a></li><li><a href="CB_Keyboard.keys.html">CB_Keyboard.keys</a></li><li><a href="CB_Modules.html">CB_Modules</a></li><li><a href="CB_Mouse.html">CB_Mouse</a></li><li><a href="CB_Mouse.CursorImage.html">CB_Mouse.CursorImage</a></li><li><a href="CB_Net.html">CB_Net</a></li><li><a href="CB_Net.Fetch.html">CB_Net.Fetch</a></li><li><a href="CB_Net.REST.html">CB_Net.REST</a></li><li><a href="CB_Net.Sockets.html">CB_Net.Sockets</a></li><li><a href="CB_Net.Sockets.SockJS.html">CB_Net.Sockets.SockJS</a></li><li><a href="CB_Net.XHR.html">CB_Net.XHR</a></li><li><a href="CB_Pointer.html">CB_Pointer</a></li><li><a href="CB_Screen.html">CB_Screen</a></li><li><a href="CB_Speaker.html">CB_Speaker</a></li><li><a href="CB_Touch.html">CB_Touch</a></li><li><a href="CB_baseSymbols.html">CB_baseSymbols</a></li>
37 </ul>
38 </li>
39
40 <li class="dropdown">
41 <a href="classes.list.html" class="dropdown-toggle" data-toggle="dropdown">Classes<b class="caret"></b></a>
42 <ul class="dropdown-menu inline">
43 <li><a href="CB_AudioFile.html">CB_AudioFile</a></li><li><a href="CB_AudioFileCache.html">CB_AudioFileCache</a></li><li><a href="CB_AudioFileSprites.html">CB_AudioFileSprites</a></li><li><a href="CB_AudioFileSpritesPool.html">CB_AudioFileSpritesPool</a></li><li><a href="CB_AudioFile_API.AAPI.html">CB_AudioFile_API.AAPI</a></li><li><a href="CB_AudioFile_API.ACMP.html">CB_AudioFile_API.ACMP</a></li><li><a href="CB_AudioFile_API.SM2.html">CB_AudioFile_API.SM2</a></li><li><a href="CB_AudioFile_API.WAAPI.html">CB_AudioFile_API.WAAPI</a></li><li><a href="CB_Canvas.html">CB_Canvas</a></li><li><a href="CB_GraphicSprites.html">CB_GraphicSprites</a></li><li><a href="CB_GraphicSpritesScene.html">CB_GraphicSpritesScene</a></li>
44 </ul>
45 </li>
46
47 <li class="dropdown">
48 <a href="global.html" class="dropdown-toggle" data-toggle="dropdown">Global<b class="caret"></b></a>
49 <ul class="dropdown-menu inline">
50 <li><a href="global.html#CB_BASE_NAME">CB_BASE_NAME</a></li><li><a href="global.html#CB_CREDITS_DEFAULT">CB_CREDITS_DEFAULT</a></li><li><a href="global.html#CB_NAME">CB_NAME</a></li><li><a href="global.html#CB_OPTIONS">CB_OPTIONS</a></li><li><a href="global.html#CB_VERSION">CB_VERSION</a></li><li><a href="global.html#CB_addCredits">CB_addCredits</a></li><li><a href="global.html#CB_baseToBase">CB_baseToBase</a></li><li><a href="global.html#CB_baseToInt">CB_baseToInt</a></li><li><a href="global.html#CB_br2nl">CB_br2nl</a></li><li><a href="global.html#CB_brToNl">CB_brToNl</a></li><li><a href="global.html#CB_combineArraysOrObjects">CB_combineArraysOrObjects</a></li><li><a href="global.html#CB_combineAutomatically">CB_combineAutomatically</a></li><li><a href="global.html#CB_combineJSON">CB_combineJSON</a></li><li><a href="global.html#CB_combineURIParameters">CB_combineURIParameters</a></li><li><a href="global.html#CB_combineURLParameters">CB_combineURLParameters</a></li><li><a href="global.html#CB_console">CB_console</a></li><li><a href="global.html#CB_copyObject">CB_copyObject</a></li><li><a href="global.html#CB_countDecimalDigits">CB_countDecimalDigits</a></li><li><a href="global.html#CB_countDecimalPart">CB_countDecimalPart</a></li><li><a href="global.html#CB_countDecimals">CB_countDecimals</a></li><li><a href="global.html#CB_countIntegerDigits">CB_countIntegerDigits</a></li><li><a href="global.html#CB_countIntegerPart">CB_countIntegerPart</a></li><li><a href="global.html#CB_credits">CB_credits</a></li><li><a href="global.html#CB_forEach">CB_forEach</a></li><li><a href="global.html#CB_forceString">CB_forceString</a></li><li><a href="global.html#CB_getBase64StringObject">CB_getBase64StringObject</a></li><li><a href="global.html#CB_getCookie">CB_getCookie</a></li><li><a href="global.html#CB_getDatum">CB_getDatum</a></li><li><a href="global.html#CB_getJSONPropertyValue">CB_getJSONPropertyValue</a></li><li><a href="global.html#CB_getLZStringObject">CB_getLZStringObject</a></li><li><a href="global.html#CB_getValueIndex">CB_getValueIndex</a></li><li><a href="global.html#CB_getValuePath">CB_getValuePath</a></li><li><a href="global.html#CB_includeJSFile">CB_includeJSFile</a></li><li><a href="global.html#CB_indexOf">CB_indexOf</a></li><li><a href="global.html#CB_init">CB_init</a></li><li><a href="global.html#CB_intToBase">CB_intToBase</a></li><li><a href="global.html#CB_isArray">CB_isArray</a></li><li><a href="global.html#CB_isEmail">CB_isEmail</a></li><li><a href="global.html#CB_isFileLocal">CB_isFileLocal</a></li><li><a href="global.html#CB_isString">CB_isString</a></li><li><a href="global.html#CB_lastIndexOf">CB_lastIndexOf</a></li><li><a href="global.html#CB_ltrim">CB_ltrim</a></li><li><a href="global.html#CB_nl2br">CB_nl2br</a></li><li><a href="global.html#CB_nlToBr">CB_nlToBr</a></li><li><a href="global.html#CB_numberFormat">CB_numberFormat</a></li><li><a href="global.html#CB_numberOfDecimalDigits">CB_numberOfDecimalDigits</a></li><li><a href="global.html#CB_numberOfDecimals">CB_numberOfDecimals</a></li><li><a href="global.html#CB_numberOfIntegerDigits">CB_numberOfIntegerDigits</a></li><li><a href="global.html#CB_parseJSON">CB_parseJSON</a></li><li><a href="global.html#CB_parseString">CB_parseString</a></li><li><a href="global.html#CB_regularExpressionString">CB_regularExpressionString</a></li><li><a href="global.html#CB_renderString">CB_renderString</a></li><li><a href="global.html#CB_replaceAll">CB_replaceAll</a></li><li><a href="global.html#CB_rtrim">CB_rtrim</a></li><li><a href="global.html#CB_scriptPath">CB_scriptPath</a></li><li><a href="global.html#CB_scriptPathCalculate">CB_scriptPathCalculate</a></li><li><a href="global.html#CB_setCookie">CB_setCookie</a></li><li><a href="global.html#CB_setDatum">CB_setDatum</a></li><li><a href="global.html#CB_sizeOf">CB_sizeOf</a></li><li><a href="global.html#CB_sizeof">CB_sizeof</a></li><li><a href="global.html#CB_stringifyJSON">CB_stringifyJSON</a></li><li><a href="global.html#CB_symmetricCall">CB_symmetricCall</a></li><li><a href="global.html#CB_symmetricCallClear">CB_symmetricCallClear</a></li><li><a href="global.html#CB_this">CB_this</a></li><li><a href="global.html#CB_trim">CB_trim</a></li>
51 </ul>
52 </li>
53
54 </ul>
55
56 <div class="col-sm-3 col-md-3">
57 <form class="navbar-form" role="search">
58 <div class="input-group">
59 <input type="text" class="form-control" placeholder="Search" name="q" id="search-input">
60 <div class="input-group-btn">
61 <button class="btn btn-default" id="search-submit"><i class="glyphicon glyphicon-search"></i></button>
62 </div>
63 </div>
64 </form>
65 </div>
66
67 </div>
68
69</div>
70</div>
71
72
73<div class="container" id="toc-content" style="width:100%;">
74<div class="row" style="width:100%;">
75
76
77 <div class="col-md-12">
78
79 <div id="main">
80
81
82 <h1 class="page-title">Source: CrossBase/audiovisual/image/CB_GraphicSprites.js</h1>
83
84<section>
85 <article>
86 <pre
87 class="sunlight-highlight-javascript linenums">/**
88 * @file Group of graphic sprites management (2D or 3D). Contains the {@link CB_GraphicSprites} class.
89 * @author Joan Alba Maldonado &lt;workindalian@gmail.com>
90 * @license Creative Commons Attribution 4.0 International. See more at {@link https://crossbrowdy.com/about#what_is_the_crossbrowdy_copyright_and_license}.
91 */
92
93
94/**
95 * An object with the information that belongs to a sub-sprite (data which belongs to a certain source) used by a graphic sprite.
96 * @example
97 {
98 id: "my_subsprite_1",
99 src: "path/to/image.gif",
100 srcType: CB_GraphicSprites.SRC_TYPES.IMAGE,
101 srcLeft: 10,
102 srcTop: 20,
103 srcWidth: 64,
104 srcHeight: 32,
105 left: 10,
106 top: 20,
107 width: 64,
108 height: 32,
109 zIndex: 1,
110 disabled: false,
111 data: { datum_1: "value_1", datum_2: 2, datum_3: [ "a", "b", "c" ] }
112 }
113 * @memberof CB_GraphicSprites
114 * @typedef {Object} CB_GraphicSprites.SUBSPRITE_OBJECT
115 * @property {string|*} [id='CB_GraphicSprites.subSprite_' + CB_GraphicSprites._idSubSpriteUnique++] - Identifier of the sub-sprite. It should be unique. It must be a value which evaluates to true. By default, it is generated automatically (with an internal counter).
116 * @property {*} [src=this.parent.src|""] - Source of origin. Can be a path or identifier of an image, text, bitmap, 3D object, etc. They can be used for any kind of source you may think of, including (but not limited to) one sprites sheet or more, one atlas or more, etc. or even a mix of all of them. If not provided, as default it will use the value from the sprite that it belongs to.
117 * @property {string} [srcType=this.parent.srcType|{@link CB_GraphicSprites.SRC_TYPES_DEFAULT}] - Type of the source of origin. If not provided, as default it will use the value from the sprite that it belongs to. It should point to a property of the {@link CB_GraphicSprites.SRC_TYPES} object. You can use other values of the {@link CB_GraphicSprites.SRC_TYPES} object or create new ones.
118 * @property {number} [srcLeft=this.parent.srcLeft|{@link CB_GraphicSprites.LEFT_SOURCE_DEFAULT}] - Left (horizontal) position in the original source (having in mind its real width and height). Unit agnostic (only numeric values are allowed). If not provided, as default it will use the value from the sprite that it belongs to.
119 * @property {number} [srcTop=this.parent.srcTop|{@link CB_GraphicSprites.TOP_SOURCE_DEFAULT}] - Top (vertical) position in the original source (having in mind its real width and height). Unit agnostic (only numeric values are allowed). If not provided, as default it will use the value from the sprite that it belongs to.
120 * @property {number} [srcWidth=this.parent.srcWidth|{@link CB_GraphicSprites.WIDTH_SOURCE_DEFAULT}] - Width of the original source. Unit agnostic (only numeric values are allowed). If not provided, as default it will use the value from the sprite that it belongs to.
121 * @property {number} [srcHeight=this.parent.srcHeight|{@link CB_GraphicSprites.HEIGHT_SOURCE_DEFAULT}] - Height of the original source. Unit agnostic (only numeric values are allowed). If not provided, as default it will use the value from the sprite that it belongs to.
122 * @property {number} [left={@link CB_GraphicSprites.LEFT_DEFAULT}] - Left (horizontal) position in the destiny (inside the sprite). Unit agnostic (only numeric values are allowed).
123 * @property {number} [top={@link CB_GraphicSprites.TOP_DEFAULT}] - Top (vertical) position in the destiny (inside the sprite). Unit agnostic (only numeric values are allowed).
124 * @property {number} [width=this.parent.width|{@link CB_GraphicSprites.WIDTH_DEFAULT}] - Width of the destiny (inside the sprite). Unit agnostic (only numeric values are allowed). If not provided, as default it will use the value from the sprite that it belongs to.
125 * @property {number} [height=this.parent.height|{@link CB_GraphicSprites.HEIGHT_DEFAULT}] - Height of the destiny (inside the sprite). Unit agnostic (only numeric values are allowed). If not provided, as default it will use the value from the sprite that it belongs to.
126 * @property {number} [zIndex=this.parent.zIndex|{@link CB_GraphicSprites.ZINDEX_DEFAULT}] - The z-index for the destiny (inside the sprite). Only numeric values which are not zero (0) are allowed. If not provided, as default it will use the value from the sprite that it belongs to. To change the value of this property, use the "setZIndex" method of the sub-sprite or the {@link CB_GraphicSprites#setZIndexSubSprite} method (which will call the {@link CB_GraphicSpritesScene#updateSubSpritesByZIndex} method internally).
127 * @property {boolean} [disabled=this.parent.disabled|false] - Tells whether this sub-sprite is disabled or not. Regardless its value, it will be considered disabled if its sprite parent is also disabled. If not provided, as default it will use the value from the sprite that it belongs to.
128 * @property {object} [data=CB_combineJSON(this.parent.data, this.data)||this.parent.data||{ 'that' : CB_GraphicSprites.SPRITES_OBJECT, 'getThis' = function() { return this.that; } }] - Object with any additional data desired which can be any kind. If not provided, missing properties as default will use the value from the sprite that it belongs to. It will always have a "that" property pointing to the {@link CB_GraphicSprites.SUBSPRITE_OBJECT} object where it belongs to and a function in its "getThis" property returning the same value (added automatically). These properties ("that" and "getThis") cannot be overridden.
129 * @property {boolean} [byReference=false] - If set to true, when inserting the sub-sprite, the same sub-sprite itself ({@link CB_GraphicSprites.SUBSPRITE_OBJECT} object) will be inserted internally directly without making a copy of itself.
130 * @property {CB_GraphicSprites.SPRITE_OBJECT} parent - Read-only property pointing to its parent ({@link CB_GraphicSprites.SPRITE_OBJECT} object).
131 * @property {CB_GraphicSprites} container - Read-only property pointing to the {@link CB_GraphicSprites} object which contains it.
132 * @property {boolean} isSubSprite - Read-only property which is always set to true to help identify this type of object.
133 * @property {'subSprite'} type - Read-only property indicating the type of object (always "subSprite").
134 * @property {integer} position - Read-only property indicating the position of this sub-sprite in the array which is set the "subSprites" property of the sprite parent ({@link CB_GraphicSprites.SPRITE_OBJECT} object).
135 * @property {integer} positionByZIndex - Read-only property indicating the position of this sub-sprite in the array which is set the "subSpritesByZIndex" property of the sprite parent ({@link CB_GraphicSprites.SPRITE_OBJECT} object).
136 * @property {integer} time - Property which stores the time in milliseconds when its parent sprite was started being pointed for the last time (time elapsed since the [time origin]{@link https://developer.mozilla.org/en-US/docs/Web/API/DOMHighResTimeStamp#The_time_origin} which was obtained calling the {@link CB_Device.getTiming} function internally). Note that the parent could being not pointed anymore. If it has never being pointed before, it will be set to 0. It normally has the same value as the "time" property of its parent object but they can be modified independently.
137 * @property {function} setTime - Read-only property which is a method that updates the "time" property of the sub-sprite (calls {@link CB_GraphicSprites#setTime} internally and returns its returning value). With only one parameter which belongs to the "time" parameter of the {@link CB_GraphicSprites#setTime} method.
138 * @property {function} getTime - Read-only property which is a method that returns the "time" property of the sub-sprite (calls {@link CB_GraphicSprites#getTime} internally and returns its returning value). With only one parameter which belongs to the "returnValueOnFail" parameter of the {@link CB_GraphicSprites#getTime} method. If the "time" property of the sub-sprite is not found, it will use the "time" property from its sprite parent.
139 * @property {function} getTimeElapsed - Read-only property which is a method that returns how many milliseconds elapsed since the sprite was or will be pointed (checking its "time" property), comparing with the time given in milliseconds (time elapsed since the [time origin]{@link https://developer.mozilla.org/en-US/docs/Web/API/DOMHighResTimeStamp#The_time_origin} which can be obtained calling the {@link CB_Device.getTiming} function) or with the current one if none is given (calls {@link CB_GraphicSprites#getTimeElapsed} internally and returns its returning value). With only one parameter which belongs to the "timeToCompare" parameter of the {@link CB_GraphicSprites#getTimeElapsed} method. If the "time" property of the sub-sprite is not found, it will use the "time" property from its sprite parent.
140 * @property {function} getZIndex - Read-only property which is a method that returns the z-index ("z-index" property) of the sub-sprite (calls {@link CB_GraphicSprites#getZIndexSubSprite} internally and returns its returning value). With only one parameter which belongs to the "returnValueOnFail" parameter of the {@link CB_GraphicSprites#getZIndexSubSprite} method.
141 * @property {function} setZIndex - Read-only property which is a method to set the z-index ("z-index" property) of the sub-sprite (calls {@link CB_GraphicSprites#setZIndexSubSprite} internally and returns its returning value). With only one parameter which belongs to the "zIndex" parameter of the {@link CB_GraphicSprites#setZIndexSubSprite} method.
142 * @property {function} isDisabled - Read-only property which is a method that tells whether the sub-sprite is disabled or not (calls {@link CB_GraphicSprites#isDisabledSubSprite} internally and returns its returning value). With no parameters. A sub-sprite is considered disabled if its sprite parent is disabled (a sprite is considered disabled if its sprites group parent is also disabled).
143 * @property {function} setDisabled - Read-only property which is a method to disable or enable the sub-sprite (calls {@link CB_GraphicSprites#setDisabledSubSprite} internally and returns its returning value). With three parameters ("disabled", "affectParents" and "affectParentsChildren") which belong to the parameters with the same name of the {@link CB_GraphicSprites#setDisabledSubSprite} method.
144 */
145
146
147/**
148 * An object with the information that belongs to a certain graphic sprite, being able to contain more than one source used by this graphic sprite (inside sub-sprites).
149 * @example
150 {
151 //'my_sprite_1':
152 id: "my_sprite_1",
153 src: "path/to/image.gif",
154 srcType: CB_GraphicSprites.SRC_TYPES.IMAGE,
155 srcLeft: 10,
156 srcTop: 20,
157 srcWidth: 64,
158 srcHeight: 32,
159 left: 10,
160 top: 20,
161 width: 64,
162 height: 32,
163 disabled: false,
164 data: { datum_1 : "value_1", datum_2 : 2, datum_3: [ "a", "b", "c" ] },
165 subSprites:
166 [
167 //'my_subsprite_1':
168 { id: "my_subsprite_1", srcLeft: 10, srcTop: 20, zIndex: 1 },
169 //'my_subsprite_2':
170 { id: "my_subsprite_2", srcLeft: 20, srcTop: 40, zIndex: 2 }
171 ]
172 }
173 * @memberof CB_GraphicSprites
174 * @typedef {Object} CB_GraphicSprites.SPRITE_OBJECT
175 * @property {string|*} [id='CB_GraphicSprites.sprite_' + CB_GraphicSprites._idSpriteUnique++] - Identifier of the sprite. It should be unique. Recommended. It must be a value which evaluates to true. By default, it is generated automatically (with an internal counter).
176 * @property {*} [src=this.parent.src|""] - Source of origin. Can be a path or identifier of an image, text, bitmap, 3D object, etc. They can be used for any kind of source you may think of, including (but not limited to) one sprites sheet or more, one atlas or more, etc. or even a mix of all of them. If not provided, as default it will use the value from the sprites group that it belongs to.
177 * @property {string} [srcType=this.parent.srcType|{@link CB_GraphicSprites.SRC_TYPES_DEFAULT}] - Type of the source of origin. If not provided, as default it will use the value from the sprites group that it belongs to. It should point to a property of the {@link CB_GraphicSprites.SRC_TYPES} object. You can use other values of the {@link CB_GraphicSprites.SRC_TYPES} object or create new ones.
178 * @property {number} [srcLeft=this.parent.srcLeft|{@link CB_GraphicSprites.LEFT_SOURCE_DEFAULT}] - Left (horizontal) position in the original source (having in mind its real width and height). Unit agnostic (only numeric values are allowed). If not provided, as default it will use the value from the sprites group that it belongs to.
179 * @property {number} [srcTop=this.parent.srcTop|{@link CB_GraphicSprites.TOP_SOURCE_DEFAULT}] - Top (vertical) position in the original source (having in mind its real width and height). Unit agnostic (only numeric values are allowed). If not provided, as default it will use the value from the sprites group that it belongs to.
180 * @property {number} [srcWidth=this.parent.srcWidth|{@link CB_GraphicSprites.WIDTH_SOURCE_DEFAULT}] - Width of the original source. Unit agnostic (only numeric values are allowed). If not provided, as default it will use the value from the sprites group that it belongs to.
181 * @property {number} [srcHeight=this.parent.srcHeight|{@link CB_GraphicSprites.HEIGHT_SOURCE_DEFAULT}] - Height of the original source. Unit agnostic (only numeric values are allowed). If not provided, as default it will use the value from the sprites group that it belongs to.
182 * @property {number} [left={@link CB_GraphicSprites.LEFT_DEFAULT}] - Left (horizontal) position in the destiny (inside the sprites group). Unit agnostic (only numeric values are allowed).
183 * @property {number} [top={@link CB_GraphicSprites.TOP_DEFAULT}] - Top (vertical) position in the destiny (inside the sprites group). Unit agnostic (only numeric values are allowed).
184 * @property {number} [width=this.parent.width|{@link CB_GraphicSprites.WIDTH_DEFAULT}] - Width of the destiny (inside the sprites group). Unit agnostic (only numeric values are allowed). If not provided, as default it will use the value from the sprites group that it belongs to.
185 * @property {number} [height=this.parent.height|{@link CB_GraphicSprites.HEIGHT_DEFAULT}] - Height of the destiny (inside the sprites group). Unit agnostic (only numeric values are allowed). If not provided, as default it will use the value from the sprites group that it belongs to.
186 * @property {number} [zIndex=this.parent.zIndex|{@link CB_GraphicSprites.ZINDEX_DEFAULT}] - The z-index for the destiny (inside the sprites group). Only numeric values which are not zero (0) are allowed. If not provided, as default it will use the value from the sprites group that it belongs to. To change the value of this property, use the "setZIndex" method of the sprite or the {@link CB_GraphicSprites#setZIndexSprite} method (which will call the {@link CB_GraphicSpritesScene#updateSpritesByZIndex} method internally).
187 * @property {boolean} [disabled=this.parent.disabled|false] - Tells whether this sprite is disabled or not. Regardless its value, it will be considered disabled if its sprites group parent is also disabled. If not provided, as default it will use the value from the sprites group that it belongs to.
188 * @property {object} [data=CB_combineJSON(this.parent.data, this.data)||this.parent.data||{ 'that' : CB_GraphicSprites.SPRITES_OBJECT, 'getThis' = function() { return this.that; } }] - Object with any additional data desired which can be any kind. If not provided, missing properties as default will use the value from the sprites group that it belongs to. It will always have a "that" property pointing to the {@link CB_GraphicSprites.SPRITE_OBJECT} object where it belongs to and a function in its "getThis" property returning the same value (added automatically). These properties ("that" and "getThis") cannot be overridden.
189 * @property {array} [subSprites=[]] - Numeric array containing {@link CB_GraphicSprites.SUBSPRITE_OBJECT} objects with the sub-sprites that this sprite uses.
190 * @property {array} subSpritesByZIndex - Read-only property containing a numeric array of all the {@link CB_GraphicSprites.SUBSPRITE_OBJECT} objects of the sprite ordered by their z-index ("zIndex" property). It is updated automatically when the z-index of a sub-sprite is set with its "setZIndex" method (or when calling the {@link CB_GraphicSprites#setZIndexSubSprite} method) or when inserting/removing sub-sprites through the {@link CB_GraphicSprites#insertSubSprites}, {@link CB_GraphicSprites#insertSubSprite}, {@link CB_GraphicSprites#removeSubSprite} or {@link CB_GraphicSprites#removeSubSpriteById} methods.
191 * @property {boolean} [byReference=false] - If set to true, when inserting the sprite, its "subSprites" property will use exactly the object given for that property (without making a copy) and the same sprite itself ({@link CB_GraphicSprites.SPRITE_OBJECT} object) will be inserted internally directly without making a copy of itself.
192 * @property {CB_GraphicSprites.SPRITES_OBJECT} parent - Read-only property pointing to its parent ({@link CB_GraphicSprites.SPRITES_OBJECT} object).
193 * @property {CB_GraphicSprites} container - Read-only property pointing to the {@link CB_GraphicSprites} object which contains it.
194 * @property {boolean} isSprite - Read-only property which is always set to true to help identify this type of object.
195 * @property {'sprite'} type - Read-only property indicating the type of object (always "sprite").
196 * @property {integer} position - Read-only property indicating the position of this sprite in the array which is set the "sprites" property of the sprites group parent ({@link CB_GraphicSprites.SPRITES_OBJECT} object).
197 * @property {integer} positionByZIndex - Read-only property indicating the position of this sprite in the array which is set the "spritesByZIndex" property of the sprites group parent ({@link CB_GraphicSprites.SPRITES_OBJECT} object).
198 * @property {integer} time - Property which stores the time in milliseconds when the sprite was started being pointed for the last time (time elapsed since the [time origin]{@link https://developer.mozilla.org/en-US/docs/Web/API/DOMHighResTimeStamp#The_time_origin} which was obtained calling the {@link CB_Device.getTiming} function internally). Note that it could being not pointed anymore. If it has never being pointed before, it will be set to 0.
199 * @property {function} setTime - Read-only property which is a method that updates the "time" property of the sprite (calls {@link CB_GraphicSprites#setTime} internally and returns its returning value). With only one parameter which belongs to the "time" parameter of the {@link CB_GraphicSprites#setTime} method.
200 * @property {function} getTime - Read-only property which is a method that returns the "time" property of the sprite (calls {@link CB_GraphicSprites#getTime} internally and returns its returning value). With only one parameter which belongs to the "returnValueOnFail" parameter of the {@link CB_GraphicSprites#getTime} method.
201 * @property {function} getTimeElapsed - Read-only property which is a method that returns how many milliseconds elapsed since the sprite was or will be pointed (checking its "time" property), comparing with the time given in milliseconds (time elapsed since the [time origin]{@link https://developer.mozilla.org/en-US/docs/Web/API/DOMHighResTimeStamp#The_time_origin} which can be obtained calling the {@link CB_Device.getTiming} function) or with the current one if none is given (calls {@link CB_GraphicSprites#getTimeElapsed} internally and returns its returning value). With only one parameter which belongs to the "timeToCompare" parameter of the {@link CB_GraphicSprites#getTimeElapsed} method.
202 * @property {function} removeAll - Read-only property which is a method that removes all the internal sub-sprites ({@link CB_GraphicSprites.SUBSPRITE_OBJECT} objects) from the sprite which are in the "subSprites" property (calls {@link CB_GraphicSprites#removeSubSprites} internally and returns its returning value). With no parameters.
203 * @property {function} removeSubSprites - Alias for the "removeAll" method.
204 * @property {function} insertSubSprites - Read-only property which is a method that inserts the given sub-sprites ({@link CB_GraphicSprites.SUBSPRITE_OBJECT} objects) in the sprite, adding them to the "subSprites" property (calls {@link CB_GraphicSprites#insertSubSprites} internally and returns its returning value). With only one parameter which belongs to the "subSprites" parameter of the {@link CB_GraphicSprites#insertSubSprites} method.
205 * @property {function} remove - Read-only property which is a method that removes an internal sub-sprite ({@link CB_GraphicSprites.SUBSPRITE_OBJECT} object) by its index (position in the "subSprites" array) from the sprite, removing it from the "subSprites" property (calls {@link CB_GraphicSprites#removeSubSprite} internally and returns its returning value). With only one parameter which belongs to the "index" parameter of the {@link CB_GraphicSprites#removeSubSprite} method.
206 * @property {function} removeById - Read-only property which is a method that removes an internal sub-sprite ({@link CB_GraphicSprites.SUBSPRITE_OBJECT} object) by its identifier from the sprite, removing it from the "subSprites" property (calls {@link CB_GraphicSprites#removeSubSpriteById} internally and returns its returning value). With only one parameter which belongs to the "id" parameter of the {@link CB_GraphicSprites#removeSubSpriteById} method.
207 * @property {function} insert - Read-only property which is a method that inserts a given sub-sprite ({@link CB_GraphicSprites.SUBSPRITE_OBJECT} object) in the sprite, adding it to the "subSprites" property (calls {@link CB_GraphicSprites#insertSubSprite} internally and returns its returning value). With only one parameter which belongs to the "subSprite" parameter of the {@link CB_GraphicSprites#insertSubSprite} method.
208 * @property {function} getAll - Read-only property which is a method that returns all the internal sub-sprites ({@link CB_GraphicSprites.SUBSPRITE_OBJECT} objects) in the sprite, getting them from the "subSprites" property (calls {@link CB_GraphicSprites#getAll} internally and returns its returning value). With two parameters ("orderedByZIndex" and "returnValueOnFail") which belong to the parameters with the same name of the {@link CB_GraphicSprites#getAll} method.
209 * @property {function} getSubSprites - Alias for the "getAll" method.
210 * @property {function} get - Read-only property which is a method that returns a sub-sprite ({@link CB_GraphicSprites.SUBSPRITE_OBJECT} object) by its index (position in the "subSprites" array) from the sprite, getting it from the "subSprites" property (calls {@link CB_GraphicSprites#getSubSprite} internally and returns its returning value). With two parameters ("index" and "returnValueOnFail") which belong to the parameters with the same name of the {@link CB_GraphicSprites#getSubSprite} method.
211 * @property {function} getById - Read-only property which is a method that returns a sub-sprite ({@link CB_GraphicSprites.SUBSPRITE_OBJECT} object) by its identifier from the sprite, getting it from the "subSprites" property (calls {@link CB_GraphicSprites#getSubSpriteById} internally and returns its returning value). With two parameters ("id" and "returnValueOnFail") which belong to the parameters with the same name of the {@link CB_GraphicSprites#getSubSpriteById} method.
212 * @property {function} getIndexById - Read-only property which is a method that returns the index (position in the "subSprites" array) of a sub-sprite ({@link CB_GraphicSprites.SUBSPRITE_OBJECT} object) by its identifier (calls {@link CB_GraphicSprites#getSubSpriteIndexById} internally and returns its returning value). With only one parameter which belongs to the "id" parameter of the {@link CB_GraphicSprites#getSubSpriteIndexById} method.
213 * @property {function} executeFunctionAll - Read-only property which is a method that executes the desired function for each sub-sprite ({@link CB_GraphicSprites.SUBSPRITE_OBJECT} objects which are in the "subSprites" property) in the sprite (calls {@link CB_GraphicSprites#executeFunctionAllSubSprites} internally and returns its returning value). With five parameters ("functionEach", "orderedByZIndex", "delayBetweenEach", "returnSetTimeoutsArray", "delayBetweenEachAffectsFirst" and "functionFinish") which belong to the parameters with the same name of the {@link CB_GraphicSprites#executeFunctionAllSubSprites} method.
214 * @property {function} executeAll - Alias for the "executeFunctionAll" method.
215 * @property {function} forEach - Alias for the "executeFunctionAll" method.
216 * @property {function} getZIndex - Read-only property which is a method that returns the z-index ("z-index" property) of the sprite (calls {@link CB_GraphicSprites#getZIndexSprite} internally and returns its returning value). With only one parameter which belongs to the "returnValueOnFail" parameter of the {@link CB_GraphicSprites#getZIndexSprite} method.
217 * @property {function} setZIndex - Read-only property which is a method to set the z-index ("z-index" property) of the sprite (calls {@link CB_GraphicSprites#setZIndexSprite} internally and returns its returning value). With only one parameter which belongs to the "zIndex" parameter of the {@link CB_GraphicSprites#setZIndexSprite} method.
218 * @property {function} isDisabled - Read-only property which is a method that tells whether the sprite is disabled or not (calls {@link CB_GraphicSprites#isDisabledSprite} internally and returns its returning value). With no parameters. A sprite is considered disabled if its sprites group parent is also disabled.
219 * @property {function} setDisabled - Read-only property which is a method to disable or enable the sprite (calls {@link CB_GraphicSprites#setDisabledSprite} internally and returns its returning value). With four parameters ("disabled", "affectSubSprites", "affectParent" and "affectParentChildren") which belong to the parameters with the same name of the {@link CB_GraphicSprites#setDisabledSprite} method.
220 * @property {function} getPointer - Read-only property which is a method that gets the current position of the pointer. It belongs to an index of the {@link CB_GraphicSprites#spritesGroup.sprites} array where a {@link CB_GraphicSprites.SPRITE_OBJECT} object is placed (containing a sprite). Internally, it uses the {@link CB_GraphicSprites#pointer} property. Calls {@link CB_GraphicSprites#getPointer} internally and returns its returning value. With no parameters.
221 * @property {function} getCurrentPosition - Alias for the "getPointer" method.
222 * @property {function} getPointerPrevious - Read-only property which is a method that gets the previous position of the pointer. Internally, it uses the {@link CB_GraphicSprites#pointerPrevious} property. Calls {@link CB_GraphicSprites#getPointerPrevious} internally and returns its returning value. With no parameters.
223 * @property {function} getPreviousPosition - Alias for the "getPointerPrevious" method.
224 * @property {function} setPointer - Read-only property which is a method that sets the pointer to the desired position (if possible). The position should belong to an index of the {@link CB_GraphicSprites#spritesGroup.sprites} array where a {@link CB_GraphicSprites.SPRITE_OBJECT} object is placed (containing a sprite). Internally, it modifies the {@link CB_GraphicSprites#pointer} property (if possible). If the position was updated, it will also reset the {@link CB_GraphicSprites#time} property (setting the current time in milliseconds). Calls {@link CB_GraphicSprites#setPointer} internally and returns the sprite (a {@link CB_GraphicSprites.SPRITE_OBJECT} object) which is being currently pointed (by the pointer set in the {@link CB_GraphicSprites#pointer} property). With two parameters ("position" and "loop") which belong to the parameters with the same name of the {@link CB_GraphicSprites#setPointer} method.
225 * @property {function} setCurrentPosition - Alias for the "setPointer" method.
226 * @property {function} getCurrent - Read-only property which is a method that gets the sprite (a {@link CB_GraphicSprites.SPRITE_OBJECT} object) which is being currently pointed (by the pointer set in the {@link CB_GraphicSprites#pointer} property). Calls {@link CB_GraphicSprites#getCurrent} internally and returns its returning value. With no parameters.
227 * @property {function} current - Alias for the "getCurrent" method.
228 * @property {function} now - Alias for the "getCurrent" method.
229 * @property {function} getPrevious - Read-only property which is a method that gets the sprite which was previously pointed if any or returns null otherwise. It does not modify the {@link CB_GraphicSprites#pointer} property. Calls {@link CB_GraphicSprites#getPrevious} internally and returns its returning value. With no parameters.
230 * @property {function} setPrevious - Read-only property which is a method that makes the pointer to go back to the previous position (if possible) and returns the sprite located there (if any). The position should belong to an index of the {@link CB_GraphicSprites#spritesGroup.sprites} array where a {@link CB_GraphicSprites.SPRITE_OBJECT} object is placed (containing a sprite) and it will be returned if found. Internally, it modifies the {@link CB_GraphicSprites#pointer} property (if possible). If the position was updated, it will update also the {@link CB_GraphicSprites#time} property (setting the current time in milliseconds). Calls {@link CB_GraphicSprites#setPrevious} internally and returns its returning value. With only one parameter which belongs to the "loop" parameter of the {@link CB_GraphicSprites#setPrevious} method.
231 * @property {function} previous - Alias for the "setPrevious" method.
232 * @property {function} setNext - Read-only property which is a method that makes the pointer to advance to the next position (if possible) and returns the sprite located there (if any). The position should belong to an index of the {@link CB_GraphicSprites#spritesGroup.sprites} array where a {@link CB_GraphicSprites.SPRITE_OBJECT} object is placed (containing a sprite) and it will be returned if found. Internally, it modifies the {@link CB_GraphicSprites#pointer} property (if possible). If the position was updated, it will also update the {@link CB_GraphicSprites#time} property (setting the current time in milliseconds). Calls {@link CB_GraphicSprites#setNext} internally and returns its returning value. With only one parameter which belongs to the "loop" parameter of the {@link CB_GraphicSprites#setNext} method.
233 * @property {function} next - Alias for the "setNext" method.
234 * @property {function} setPropertyCascade - Read-only property which is a method that sets the desired value of a given property name to the sprite itself and all of its sub-sprites (if any). Calls {@link CB_GraphicSprites#setPropertyCascade} internally and returns its returning value. With two parameters ("propertyName" and "value") which belong to the parameters with the same name of the {@link CB_GraphicSprites#setPropertyCascade} method.
235 */
236
237
238/**
239 * An object with the information that belongs to a group of graphic sprites.
240 * @example
241 {
242 //'my_sprites_1':
243 id: "my_sprites_1",
244 src: "path/to/image.gif",
245 srcType: CB_GraphicSprites.SRC_TYPES.IMAGE,
246 srcLeft: 10,
247 srcTop: 20,
248 srcWidth: 64,
249 srcHeight: 32,
250 left: 10,
251 top: 20,
252 width: 64,
253 height: 32,
254 data: { datum_1: "value_1", datum_2: 2, datum_3: [ "a", "b", "c" ] },
255 sprites:
256 [
257 //'my_sprite_1':
258 {
259 id: "my_sprite_1",
260 subSprites:
261 [
262 //'my_subsprite_1':
263 { id: "my_subsprite_1", srcLeft: 10, srcTop: 20, zIndex: 1 },
264 //'my_subsprite_2':
265 { id: "my_subsprite_2", srcLeft: 20, srcTop: 40, zIndex: 2 }
266 ]
267 },
268 //'my_sprite_2':
269 {
270 id: "my_sprite_2",
271 subSprites:
272 [
273 //'my_subsprite_3':
274 { id: "my_subsprite_3", srcLeft: 30, srcTop: 60, zIndex: 1 },
275 //'my_subsprite_4':
276 { id: "my_subsprite_4", srcLeft: 40, srcTop: 80, zIndex: 2 }
277 ]
278 }
279 ]
280 }
281 * @memberof CB_GraphicSprites
282 * @typedef {Object} CB_GraphicSprites.SPRITES_OBJECT
283 * @property {string|*} [id='CB_GraphicSprites_' + CB_GraphicSprites._idUnique++] - Identifier of the group of graphic sprites (also used as the {@link CB_GraphicSprites.id} property for the {@link CB_GraphicSprites} object). It should be unique. Recommended. It must be a value which evaluates to true. By default, it is generated automatically (with an internal counter).
284 * @property {*} [src=""] - Source of origin. Can be a path or identifier of an image, text, bitmap, 3D object, etc. They can be used for any kind of source you may think of, including (but not limited to) one sprites sheet or more, one atlas or more, etc. or even a mix of all of them.
285 * @property {string} [srcType={@link CB_GraphicSprites.SRC_TYPES_DEFAULT}] - Type of the source of origin. It should point to a property of the {@link CB_GraphicSprites.SRC_TYPES} object. You can use other values of the {@link CB_GraphicSprites.SRC_TYPES} object or create new ones.
286 * @property {number} [srcLeft={@link CB_GraphicSprites.LEFT_SOURCE_DEFAULT}] - Left (horizontal) position in the original source (having in mind its real width and height). Unit agnostic (only numeric values are allowed). If not provided, as default it will use the value from {@link CB_GraphicSprites.LEFT_SOURCE_DEFAULT}.
287 * @property {number} [srcTop={@link CB_GraphicSprites.TOP_SOURCE_DEFAULT}] - Top (vertical) position in the original source (having in mind its real width and height). Unit agnostic (only numeric values are allowed). If not provided, as default it will use the value from {@link CB_GraphicSprites.TOP_SOURCE_DEFAULT}.
288 * @property {number} [srcWidth={@link CB_GraphicSprites.WIDTH_SOURCE_DEFAULT}] - Width of the original source. Unit agnostic (only numeric values are allowed). If not provided, as default it will use the value from {@link CB_GraphicSprites.WIDTH_SOURCE_DEFAULT}.
289 * @property {number} [srcHeight={@link CB_GraphicSprites.HEIGHT_SOURCE_DEFAULT}] - Height of the original source. Unit agnostic (only numeric values are allowed). If not provided, as default it will use the value from {@link CB_GraphicSprites.HEIGHT_SOURCE_DEFAULT}.
290 * @property {number} [left={@link CB_GraphicSprites.LEFT_DEFAULT}] - Left (horizontal) position in the destiny. Unit agnostic (only numeric values are allowed). If not provided, as default it will use the value from {@link CB_GraphicSprites.LEFT_DEFAULT}.
291 * @property {number} [top={@link CB_GraphicSprites.TOP_DEFAULT}] - Top (vertical) position in the destiny. Unit agnostic (only numeric values are allowed). If not provided, as default it will use the value from {@link CB_GraphicSprites.TOP_DEFAULT}.
292 * @property {number} [width={@link CB_GraphicSprites.WIDTH_DEFAULT}] - Width of the destiny. Unit agnostic (only numeric values are allowed). If not provided, as default it will use the value from {@link CB_GraphicSprites.WIDTH_DEFAULT}.
293 * @property {number} [height={@link CB_GraphicSprites.HEIGHT_DEFAULT}] - Height of the destiny. Unit agnostic (only numeric values are allowed). If not provided, as default it will use the value from {@link CB_GraphicSprites.HEIGHT_DEFAULT}.
294 * @property {number} [zIndex={@link CB_GraphicSprites.ZINDEX_DEFAULT}] - The z-index for the destiny (only numeric values which are not zero (0) are allowed). Also used as the {@link CB_GraphicSprites.zIndex} property for the {@link CB_GraphicSprites} object. If not provided, as default it will use the value from {@link CB_GraphicSprites.ZINDEX_DEFAULT}. To change the value of this property, use the {@link CB_GraphicSprites#setZIndex} method (which will call the {@link CB_GraphicSpritesScene#updateGraphicSpritesByZIndex} method internally if there is a {@link CB_GraphicSpritesScene} parent object).
295 * @property {boolean} [disabled=false] - Tells whether this sprites group (and the {@link CB_GraphicSprites} object itself) is disabled or not. If not provided, as default it will be false (which means it is enabled).
296 * @property {object} [data={ 'that' : CB_GraphicSprites.SPRITES_OBJECT, 'getThis' = function() { return this.that; } }] - Object with any additional data desired which can be any kind. It will always have a "that" property pointing to the {@link CB_GraphicSprites.SPRITES_OBJECT} object where it belongs to and a function in its "getThis" property returning the same value (added automatically). These properties ("that" and "getThis") cannot be overridden.
297 * @property {array} [sprites=[]] - Numeric array containing {@link CB_GraphicSprites.SPRITE_OBJECT} objects with all the sprites that will be used. Recommended at least to provide one {@link CB_GraphicSprites.SPRITE_OBJECT} object in the first index.
298 * @property {array} spritesByZIndex - Read-only property containing a numeric array of all the {@link CB_GraphicSprites.SPRITE_OBJECT} objects ordered by their z-index ("zIndex" property). It is updated automatically when the z-index of a sprite is set with its "setZIndex" method (or when calling the {@link CB_GraphicSprites#setZIndexSprite} method) or when inserting/removing sprites through the {@link CB_GraphicSprites#insertSprites}, {@link CB_GraphicSprites#insertSprite}, {@link CB_GraphicSprites#removeSprite} or {@link CB_GraphicSprites#removeSpriteById} methods.
299 * @property {boolean} [byReference_DEFAULT=false] - Default value to use as the "byReference" parameter for the constructor and for the {@link CB_GraphicSprites#insertSprites} method. If a boolean value is not provided, it will be parsed to boolean (resulting undefined to be false).
300 * @property {*} [parent=undefined|{@link CB_GraphicSpritesScene}] - Property pointing to or containing its parent (also used as the {@link CB_GraphicSprites.parent} property for the {@link CB_GraphicSprites} object). It could be a {@link CB_GraphicSpritesScene} object.
301 * @property {CB_GraphicSprites} container - Read-only property pointing to the {@link CB_GraphicSprites} object which contains it.
302 * @property {boolean} isSpritesGroup - Read-only property which is always set to true to help identify this type of object.
303 * @property {'spritesGroup'} type - Read-only property indicating the type of object (always "spritesGroup").
304 * @property {integer} [position=undefined] - Read-only property indicating the position of this {@link CB_GraphicSprites} object in the array which is set the "items" property inside the {@link CB_GraphicSpritesScene#spritesGroups} object which is in the {@link CB_GraphicSpritesScene} object parent (if any).
305 * @property {integer} [positionByZIndex=undefined] - Read-only property indicating the position of this {@link CB_GraphicSprites} object in the array which is set the "itemsByZIndex" property inside the {@link CB_GraphicSpritesScene#spritesGroups} object which is in the {@link CB_GraphicSpritesScene} object parent (if any).
306 */
307
308
309/**
310 * Class to manage a group of graphic sprites (2D or 3D).
311 * @class
312 * @classdesc Class to manage a group of graphic sprites (2D or 3D).
313 * @param {CB_GraphicSprites.SPRITES_OBJECT} [spritesGroup] - Object with the desired sprites. The information will be used for the {@link CB_GraphicSprites#spritesGroup} property. Used as the "spritesGroup" parameter when calling the {@link CB_GraphicSprites#insertSprites} method internally.
314 * @param {boolean} [byReference=!!{@link CB_GraphicSprites.SPRITES_OBJECT.byReference_DEFAULT}] - This value will be used as the default value when the "byReference" property is not given in the sprites ({@link CB_GraphicSprites.SPRITE_OBJECT} objects) or sub-sprites ({@link CB_GraphicSprites.SUBSPRITE_OBJECT} objects). The value will be stored in the {@link CB_GraphicSprites#byReference_DEFAULT} property. If a boolean value is not provided, it will use the value of the {@link CB_GraphicSprites.SPRITES_OBJECT.byReference_DEFAULT} property of the given {@link CB_GraphicSprites.SPRITES_OBJECT} object (parsed to boolean).
315 * @returns {CB_GraphicSprites} Returns a new {@link CB_GraphicSprites} object.
316 * @todo Think about a "createCopy" parameter on different the insert methods (to insert sprites groups/graphic sprites objects, etc.) so it will make a copy of the object to avoid using/modifying the original one. If the "createCopy" is set to false, it should always use the object as reference (using/modifying it).
317 * @todo Think about a method to remove a sprite when the same sprite is received by parameter. The same with sub-sprites, receiving the sub-sprite by parameter. The same to remove the sprites group object, receiving a sprites group object by parameter. Only remove them if they match exactly.
318 */
319var CB_GraphicSprites = function(spritesGroup, byReference)
320{
321 //Creates an instance of this object and returns it in the case that it is being called from an unexpected context:
322 if (this === window || !(this instanceof CB_GraphicSprites)) { return new CB_GraphicSprites(spritesGroup, byReference); }
323
324 //Properties and variables:
325 /**
326 * Identifier of the sprites group object (the "id" property of the {@link CB_GraphicSprites.SPRITES_OBJECT} stored in the {@link CB_GraphicSprites#spritesGroup} property) and the {@link CB_GraphicSprites} object itself (same one). It should be unique. It must be a value which evaluates to true. By default, it is generated automatically (with an internal counter).
327 * @var
328 * @readonly
329 * @type {string|*}
330 * @default 'CB_GraphicSprites_' + CB_GraphicSprites._idUnique++
331 */
332 this.id = "";
333
334 /**
335 * Property pointing to or containing its parent. It could be a {@link CB_GraphicSpritesScene} object. It is the same as the "parent" property of the {@link CB_GraphicSprites.SPRITES_OBJECT} stored in the {@link CB_GraphicSprites#spritesGroup} property.
336 * @var
337 * @readonly
338 * @type {*}
339 * @default
340 */
341 this.parent = undefined;
342
343 /**
344 * Z-index of the sprites group object (the "zIndex" property of the {@link CB_GraphicSprites.SPRITES_OBJECT} stored in the {@link CB_GraphicSprites#spritesGroup} property) and the {@link CB_GraphicSprites} object itself (same one). To change the value of this property, use the {@link CB_GraphicSprites#setZIndex} method (which will call the {@link CB_GraphicSpritesScene#updateGraphicSpritesByZIndex} method internally if there is a {@link CB_GraphicSpritesScene} parent object). Only numeric values which are not zero (0) are allowed.
345 * @var
346 * @readonly
347 * @type {number}
348 * @default CB_GraphicSprites.ZINDEX_DEFAULT
349 */
350 this.zIndex = CB_GraphicSprites.ZINDEX_DEFAULT;
351
352 /**
353 * Object with information about the sprites.
354 * @var
355 * @readonly
356 * @type {CB_GraphicSprites.SPRITES_OBJECT}
357 * @default
358 */
359 this.spritesGroup = {};
360
361 /**
362 * Pointer with the position of the current sprite (belongs to an index of the {@link CB_GraphicSprites#spritesGroup.sprites} array).
363 * @var
364 * @readonly
365 * @type {integer}
366 * @default
367 */
368 this.pointer = -1;
369
370
371 /**
372 * Keeps the previous value of the {@link CB_GraphicSprites#pointer} property (if any).
373 * @var
374 * @readonly
375 * @type {integer}
376 * @default
377 */
378 this.pointerPrevious = -1;
379
380
381 /**
382 * Stores the time in milliseconds when the current sprite was started being pointed (time elapsed since the [time origin]{@link https://developer.mozilla.org/en-US/docs/Web/API/DOMHighResTimeStamp#The_time_origin} which will be obtained calling the {@link CB_Device.getTiming} function internally).
383 * @var
384 * @readonly
385 * @type {integer}
386 * @default
387 */
388 this.time = 0;
389
390
391 /**
392 * This value will be used as the default value when the "byReference" property is not given in the sprites ({@link CB_GraphicSprites.SPRITE_OBJECT} objects) or sub-sprites ({@link CB_GraphicSprites.SUBSPRITE_OBJECT} objects).
393 * @var
394 * @type {boolean}
395 * @default
396 */
397 this.byReference_DEFAULT = false;
398
399
400 //Calls the constructor of the object when creates an instance:
401 return this._init(spritesGroup, byReference);
402}
403
404
405//Constants:
406/**
407 * Property which is always set to true to help identify this type of object.
408 * @constant
409 * @type {boolean}
410 * @default
411 */
412CB_GraphicSprites.prototype.isSprites = true;
413
414
415/**
416 * Indicates the type of object (always "sprites").
417 * @constant
418 * @type {string}
419 * @default
420 */
421CB_GraphicSprites.prototype.type = "sprites";
422
423
424/**
425 * Object with some "srcType". Each property of this object belong to one source type, having an integer as value which represents it. You can define more source types here.
426 * @constant
427 * @type {object}
428 * @default
429 */
430CB_GraphicSprites.SRC_TYPES =
431{
432 DEFAULT: 0,
433 IMAGE: 0,
434 TEXT: 1,
435 SEGMENT: 2,
436 PIXEL: 3,
437 RECTANGLE: 4,
438 CIRCLE: 5,
439 ARC: 6,
440 ELLIPSE: 7,
441 TRIANGLE: 8,
442 BEZIER_CURVE: 9,
443 QUADRATIC_BEZIER_CURVE: 10,
444 BITMAP: 11,
445 MAP: 12
446}
447/**
448 * Alias for {@link CB_GraphicSprites.SRC_TYPES_DEFAULT}.
449 * @constant CB_GraphicSprites.SRC_TYPES.DEFAULT
450 * @see {@link CB_GraphicSprites.SRC_TYPES_DEFAULT}
451 */
452/**
453 * Default "srcType", the type of the original source.
454 * @constant
455 * @type {integer}
456 * @default {@link CB_GraphicSprites.SRC_TYPES.IMAGE}
457 */
458CB_GraphicSprites.SRC_TYPES_DEFAULT = CB_GraphicSprites.SRC_TYPES.DEFAULT = CB_GraphicSprites.SRC_TYPES.IMAGE;
459
460/**
461 * Default width ("srcWidth") of the original source. Unit agnostic.
462 * @constant
463 * @type {number}
464 * @default
465 */
466CB_GraphicSprites.WIDTH_SOURCE_DEFAULT = 32;
467/**
468 * Default height ("srcHeight") of the original source. Unit agnostic.
469 * @constant
470 * @type {number}
471 * @default
472 */
473CB_GraphicSprites.HEIGHT_SOURCE_DEFAULT = 32;
474
475/**
476 * Default left ("srcLeft", horizontal position) in the original source. Unit agnostic.
477 * @constant
478 * @type {number}
479 * @default
480 */
481CB_GraphicSprites.LEFT_SOURCE_DEFAULT = 0;
482/**
483 * Default top ("srcTop", vertical position) in the original source. Unit agnostic.
484 * @constant
485 * @type {number}
486 * @default
487 */
488CB_GraphicSprites.TOP_SOURCE_DEFAULT = 0;
489
490/**
491 * Default "width" of the destiny. Unit agnostic.
492 * @constant
493 * @type {number}
494 * @default
495 */
496CB_GraphicSprites.WIDTH_DEFAULT = CB_GraphicSprites.WIDTH_SOURCE_DEFAULT;
497/**
498 * Default "height" of the destiny. Unit agnostic.
499 * @constant
500 * @type {number}
501 * @default
502 */
503CB_GraphicSprites.HEIGHT_DEFAULT = CB_GraphicSprites.HEIGHT_SOURCE_DEFAULT;
504
505/**
506 * Default "left" (horizontal position) in the destiny. Unit agnostic.
507 * @constant
508 * @type {number}
509 * @default
510 */
511CB_GraphicSprites.LEFT_DEFAULT = 0;
512/**
513 * Default "top" (vertical position) in the destiny. Unit agnostic.
514 * @constant
515 * @type {number}
516 * @default
517 */
518CB_GraphicSprites.TOP_DEFAULT = 0;
519
520/**
521 * Default "zIndex" in the destiny.
522 * @constant
523 * @type {number}
524 * @default
525 */
526CB_GraphicSprites.ZINDEX_DEFAULT = 1;
527
528
529
530//Variables:
531CB_GraphicSprites._idUnique = 0; //Counter to make the sprites group id unique.
532CB_GraphicSprites._idSpriteUnique = 0; //Counter to make the sprite id unique.
533CB_GraphicSprites._idSubSpriteUnique = 0; //Counter to make the sub-sprite id unique.
534
535
536//Constructor:
537CB_GraphicSprites.prototype._init = function(spritesGroup, byReference)
538{
539 this.insertSprites(spritesGroup, byReference); //Inserts the given sprites group.
540 return this;
541}
542
543
544/**
545 * Destroys the graphic sprites object (removing all the sprites and their sub-sprites, etc.) and frees memory.
546 * @function
547 */
548CB_GraphicSprites.prototype.destructor = function()
549{
550 //Resets properties to their default value:
551 this.removeSprites();
552}
553
554
555/**
556 * Alias for {@link CB_GraphicSprites#removeSprites}.
557 * @function CB_GraphicSprites#removeAll
558 * @see {@link CB_GraphicSprites#removeSprites}
559 */
560/**
561 * Alias for {@link CB_GraphicSprites#removeSprites}.
562 * @function CB_GraphicSprites#removeSpritesGroup
563 * @see {@link CB_GraphicSprites#removeSprites}
564 */
565/**
566 * Alias for {@link CB_GraphicSprites#removeSprites}.
567 * @function CB_GraphicSprites#removeSpritesAll
568 * @see {@link CB_GraphicSprites#removeSprites}
569 */
570/**
571 * Removes all the sprites by clearing the {@link CB_GraphicSprites#spritesGroup} property.
572 * @function
573 */
574CB_GraphicSprites.prototype.removeSprites = CB_GraphicSprites.prototype.removeSpritesAll = CB_GraphicSprites.prototype.removeSpritesGroup = CB_GraphicSprites.prototype.removeAll = function()
575{
576 this.spritesGroup = {};
577 this.pointer = this.pointerPrevious = -1;
578}
579
580
581/**
582 * Alias for {@link CB_GraphicSprites#insertSprites}.
583 * @function CB_GraphicSprites#insertSpritesGroup
584 * @see {@link CB_GraphicSprites#insertSprites}
585 */
586/**
587 * Adds the desired group of graphic sprites. Calls the {@link CB_GraphicSprites#insertSprite} and {@link CB_GraphicSprites#updateSpritesByZIndex} methods internally.
588 * @function
589 * @param {CB_GraphicSprites.SPRITES_OBJECT} [spritesGroup] - Object with the desired sprites. They will be stored in the {@link CB_GraphicSprites#spritesGroup} property.
590 * @param {boolean} [byReference=!!{@link CB_GraphicSprites.SPRITES_OBJECT.byReference_DEFAULT}] - This value will be used as the default value when the "byReference" property is not given in the sprites ({@link CB_GraphicSprites.SPRITE_OBJECT} objects) or sub-sprites ({@link CB_GraphicSprites.SUBSPRITE_OBJECT} objects). The value will be stored in the {@link CB_GraphicSprites#byReference_DEFAULT} property. If a boolean value is not provided, it will use the value of the {@link CB_GraphicSprites.SPRITES_OBJECT.byReference_DEFAULT} property of the given {@link CB_GraphicSprites.SPRITES_OBJECT} object (parsed to boolean).
591 * @returns {CB_GraphicSprites.SPRITES_OBJECT} Returns the {@link CB_GraphicSprites#spritesGroup} property after updating it.
592 */
593CB_GraphicSprites.prototype.insertSprites = CB_GraphicSprites.prototype.insertSpritesGroup = function(spritesGroup, byReference)
594{
595 //Sets the properties (sanitizing them):
596 this.byReference_DEFAULT = (byReference === true || byReference === false) ? byReference : !!spritesGroup.byReference_DEFAULT;
597 this.spritesGroup = this.spritesGroup || {};
598 spritesGroup = spritesGroup || {};
599 this.spritesGroup.isSpritesGroup = true;
600 this.spritesGroup.type = "spritesGroup";
601 this.spritesGroup.container = this;
602 this.parent = this.spritesGroup.parent = spritesGroup.parent;
603 this.id = this.spritesGroup.id = spritesGroup.id = spritesGroup.id || "CB_GraphicSprites_" + CB_GraphicSprites._idUnique++;
604 this.spritesGroup.src = spritesGroup.src = spritesGroup.src || !isNaN(spritesGroup.src) &amp;&amp; spritesGroup.src !== null ? spritesGroup.src : "";
605 this.spritesGroup.srcType = spritesGroup.srcType = spritesGroup.srcType || CB_GraphicSprites.SRC_TYPES_DEFAULT;
606 spritesGroup.srcLeft = parseFloat(spritesGroup.srcLeft);
607 this.spritesGroup.srcLeft = spritesGroup.srcLeft = !isNaN(spritesGroup.srcLeft) ? spritesGroup.srcLeft : parseFloat(CB_GraphicSprites.LEFT_SOURCE_DEFAULT) || 0;
608 spritesGroup.left = parseFloat(spritesGroup.left);
609 this.spritesGroup.left = spritesGroup.left = !isNaN(spritesGroup.left) ? spritesGroup.left : parseFloat(CB_GraphicSprites.LEFT_DEFAULT) || 0;
610 spritesGroup.srcTop = parseFloat(spritesGroup.srcTop);
611 this.spritesGroup.srcTop = spritesGroup.srcTop = !isNaN(spritesGroup.srcTop) ? spritesGroup.srcTop : parseFloat(CB_GraphicSprites.TOP_SOURCE_DEFAULT) || 0;
612 spritesGroup.top = parseFloat(spritesGroup.top);
613 this.spritesGroup.top = spritesGroup.top = !isNaN(spritesGroup.top) ? spritesGroup.top : parseFloat(CB_GraphicSprites.TOP_DEFAULT) || 0;
614 spritesGroup.srcWidth = parseFloat(spritesGroup.srcWidth);
615 this.spritesGroup.srcWidth = spritesGroup.srcWidth = !isNaN(spritesGroup.srcWidth) ? spritesGroup.srcWidth : parseFloat(CB_GraphicSprites.WIDTH_SOURCE_DEFAULT) || 0;
616 spritesGroup.width = parseFloat(spritesGroup.width);
617 this.spritesGroup.width = spritesGroup.width = !isNaN(spritesGroup.width) ? spritesGroup.width : CB_GraphicSprites.WIDTH_DEFAULT;
618 spritesGroup.srcHeight = parseFloat(spritesGroup.srcHeight);
619 this.spritesGroup.srcHeight = spritesGroup.srcHeight = !isNaN(spritesGroup.srcHeight) ? spritesGroup.srcHeight : parseFloat(CB_GraphicSprites.HEIGHT_SOURCE_DEFAULT) || 0;
620 spritesGroup.height = parseFloat(spritesGroup.height);
621 this.spritesGroup.height = spritesGroup.height = !isNaN(spritesGroup.height) ? spritesGroup.height : parseFloat(CB_GraphicSprites.HEIGHT_DEFAULT) || 0;
622 this.zIndex = spritesGroup.zIndex = parseFloat(spritesGroup.zIndex);
623 this.spritesGroup.disabled = !!spritesGroup.disabled;
624 this.spritesGroup.zIndex = spritesGroup.zIndex = !isNaN(spritesGroup.zIndex) ? spritesGroup.zIndex : parseFloat(CB_GraphicSprites.ZINDEX_DEFAULT) || 0;
625 this.spritesGroup.data = typeof(spritesGroup.data) === "object" &amp;&amp; spritesGroup.data !== null ? CB_copyObject(spritesGroup.data, false) : {}; //Accepts any object but not other values.
626 this.spritesGroup.data.that = this.spritesGroup;
627 this.spritesGroup.data.getThis = function() { return this.that; };
628
629 spritesGroup.sprites = CB_isArray(spritesGroup.sprites) ? spritesGroup.sprites : [];
630
631 //Inserts the given sprites, one by one:
632 var spritesGroupLength = spritesGroup.sprites.length;
633 for (var x = 0; x &lt; spritesGroupLength; x++)
634 {
635 this.insertSprite(spritesGroup.sprites[x], true);
636 }
637
638 //Updates the array with the sprites ordered by z-index:
639 this.updateSpritesByZIndex();
640
641 //Returns the sprites:
642 return this.spritesGroup;
643}
644
645
646/**
647 * Updates (sorts again) the "spritesByZIndex" property (which is an array with the sprites ordered by z-index, whose data comes from the array in the "sprites" property of the {@link CB_GraphicSprites#spritesGroup} object) of the {@link CB_GraphicSprites#spritesGroup} object.
648 * @function
649 * @returns {array} Returns the "spritesByZIndex" array of the {@link CB_GraphicSprites#spritesGroup} object after updating it. Returns null if the property could not be obtained or updated.
650 */
651CB_GraphicSprites.prototype.updateSpritesByZIndex = function()
652{
653 this.spritesGroup.sprites = this.spritesGroup.sprites || null;
654 if (this.spritesGroup.sprites)
655 {
656 var spritesGroupLength = this.spritesGroup.sprites.length;
657 if (spritesGroupLength)
658 {
659 var elementIndex = null;
660 this.spritesGroup.spritesByZIndex = [];
661 for (var x = 0; x &lt; spritesGroupLength; x++)
662 {
663 elementIndex = CB_GraphicSpritesScene._choosePositionByZIndex(this.spritesGroup.spritesByZIndex, this.spritesGroup.sprites[x]);
664 this.spritesGroup.spritesByZIndex = CB_Arrays.insertElement(this.spritesGroup.spritesByZIndex, elementIndex, this.spritesGroup.sprites[x]);
665 this.spritesGroup.sprites[x].positionByZIndex = elementIndex;
666 }
667 return this.spritesGroup.spritesByZIndex;
668 }
669 }
670 return null;
671}
672
673
674/**
675 * Alias for {@link CB_GraphicSprites#removeSprite}.
676 * @function CB_GraphicSprites#remove
677 * @see {@link CB_GraphicSprites#removeSprite}
678 */
679/**
680 * Removes a sprite by its index (its position in the {@link CB_GraphicSprites#spritesGroup.sprites} array). Calls the {@link CB_GraphicSprites#updateSpritesByZIndex} method internally.
681 * @function
682 * @param {integer} [index=0] - The index where the sprite is located (its position in the {@link CB_GraphicSprites#spritesGroup.sprites} array).
683 * @returns {boolean} Returns true if the sprite has been deleted or false otherwise.
684 */
685CB_GraphicSprites.prototype.removeSprite = CB_GraphicSprites.prototype.remove = function(index)
686{
687 var removed = false;
688 var spritesLeft = CB_Arrays.removeElementByPosition(this.spritesGroup.sprites, index, function() { removed = true; });
689 if (removed)
690 {
691 this.spritesGroup.sprites = spritesLeft;
692 //Keeps the pointer if the position is valid or sets to the last position if the position was greater than the current limit or uses the first position otherwise:
693 this.setPointer(this.getPointer());
694
695 //Updates the array with the sprites ordered by z-index:
696 this.updateSpritesByZIndex();
697 }
698 return removed;
699}
700
701
702/**
703 * Alias for {@link CB_GraphicSprites#removeSpriteById}.
704 * @function CB_GraphicSprites#removeById
705 * @see {@link CB_GraphicSprites#removeSpriteById}
706 */
707/**
708 * Removes a sprite by its identifier. Calls the {@link CB_GraphicSprites#updateSpritesByZIndex} method internally.
709 * @function
710 * @param {string|*} [id=undefined] - The identifier of the sprite.
711 * @returns {boolean} Returns true if the sprite has been deleted or false otherwise.
712 * @todo Optimize it (perhaps using a cache matching the IDs with their position, maybe using the "position" or "positionByZIndex" properties).
713 */
714CB_GraphicSprites.prototype.removeSpriteById = CB_GraphicSprites.prototype.removeById = function(id)
715{
716 var removed = false;
717 var spritesLeft = CB_Arrays.removeDuplicated(this.spritesGroup.sprites, function(value, position, array) { if (value &amp;&amp; value.id === id) { removed = true; return true; }; return false; }, true);
718 if (removed)
719 {
720 this.spritesGroup.sprites = spritesLeft;
721 //Keeps the pointer if the position is valid or sets to the last position if the position was greater than the current limit or uses the first position otherwise:
722 this.setPointer(this.getPointer());
723
724 //Updates the array with the sprites ordered by z-index:
725 this.updateSpritesByZIndex();
726 }
727 return removed;
728}
729
730
731/**
732 * Alias for {@link CB_GraphicSprites#insertSprite}.
733 * @function CB_GraphicSprites#insert
734 * @see {@link CB_GraphicSprites#insertSprite}
735 */
736/**
737 * Adds the desired graphic sprite. Calls {@link CB_GraphicSprites#insertSubSprites} internally. If a sprite with the same identifier already exists, it will be replaced by the new one in its same position.
738 * @function
739 * @param {CB_GraphicSprites.SPRITE_OBJECT} [sprite] - Object with the desired sprite. It will be stored inside the {@link CB_GraphicSprites#spritesGroup} property.
740 * @param {boolean} [avoidUpdatingSpritesByZIndex=false] - If set to true, it will not call the {CB_GraphicSprites#updateSpritesByZIndex} method internally. Internal usage recommended only.
741 * @returns {CB_GraphicSprites.SPRITE_OBJECT} Returns the {@link CB_GraphicSprites.SPRITE_OBJECT} object which has been inserted (it could have been modified/sanitized from the given one and some missing properties or those which were wrong could have been inherited).
742 */
743CB_GraphicSprites.prototype.insertSprite = CB_GraphicSprites.prototype.insert = function(sprite, avoidUpdatingSpritesByZIndex)
744{
745 //Sets the properties (sanitizing them):
746 this.spritesGroup = this.spritesGroup || {};
747 sprite = sprite || {};
748 if (sprite.byReference !== true &amp;&amp; sprite.byReference !== false) { sprite.byReference = this.byReference_DEFAULT; }
749 sprite = sprite.byReference ? sprite : CB_copyObject(sprite);
750 sprite.isSprite = true;
751 sprite.type = "sprite";
752 sprite.container = this;
753 sprite.parent = this.spritesGroup;
754 sprite.time = !isNaN(parseInt(sprite.time)) ? parseInt(sprite.time) : 0;
755 sprite.id = sprite.id || "CB_GraphicSprites.sprite_" + CB_GraphicSprites._idSpriteUnique++;
756 sprite.src = sprite.src || !isNaN(sprite.src) &amp;&amp; sprite.src !== null ? sprite.src : this.spritesGroup.src || !isNaN(this.spritesGroup.src) &amp;&amp; this.spritesGroup.src !== null ? this.spritesGroup.src : "";
757 sprite.srcType = sprite.srcType || this.spritesGroup.srcType || CB_GraphicSprites.SRC_TYPES_DEFAULT;
758 sprite.srcLeft = parseFloat(sprite.srcLeft);
759 sprite.srcLeft = !isNaN(sprite.srcLeft) ? sprite.srcLeft : parseFloat(this.spritesGroup.srcLeft);
760 sprite.srcLeft = !isNaN(sprite.srcLeft) ? sprite.srcLeft : parseFloat(CB_GraphicSprites.LEFT_SOURCE_DEFAULT) || 0;
761 sprite.left = parseFloat(sprite.left);
762 //sprite.left = !isNaN(sprite.left) ? sprite.left : parseFloat(this.spritesGroup.left);
763 sprite.left = !isNaN(sprite.left) ? sprite.left : parseFloat(CB_GraphicSprites.LEFT_DEFAULT) || 0;
764 sprite.srcTop = parseFloat(sprite.srcTop);
765 sprite.srcTop = !isNaN(sprite.srcTop) ? sprite.srcTop : parseFloat(this.spritesGroup.srcTop);
766 sprite.srcTop = !isNaN(sprite.srcTop) ? sprite.srcTop : parseFloat(CB_GraphicSprites.TOP_SOURCE_DEFAULT) || 0;
767 sprite.top = parseFloat(sprite.top);
768 //sprite.top = !isNaN(sprite.top) ? sprite.top : parseFloat(this.spritesGroup.top);
769 sprite.top = !isNaN(sprite.top) ? sprite.top : parseFloat(CB_GraphicSprites.TOP_DEFAULT) || 0;
770 sprite.srcWidth = parseFloat(sprite.srcWidth);
771 sprite.srcWidth = !isNaN(sprite.srcWidth) ? sprite.srcWidth : parseFloat(this.spritesGroup.srcWidth);
772 sprite.srcWidth = !isNaN(sprite.srcWidth) ? sprite.srcWidth : parseFloat(CB_GraphicSprites.WIDTH_SOURCE_DEFAULT) || 0;
773 sprite.width = parseFloat(sprite.width);
774 sprite.width = !isNaN(sprite.width) ? sprite.width : parseFloat(this.spritesGroup.width);
775 sprite.width = !isNaN(sprite.width) ? sprite.width : parseFloat(CB_GraphicSprites.WIDTH_DEFAULT) || 0;
776 sprite.srcHeight = parseFloat(sprite.srcHeight);
777 sprite.srcHeight = !isNaN(sprite.srcHeight) ? sprite.srcHeight : parseFloat(this.spritesGroup.srcHeight);
778 sprite.srcHeight = !isNaN(sprite.srcHeight) ? sprite.srcHeight : parseFloat(CB_GraphicSprites.HEIGHT_SOURCE_DEFAULT) || 0;
779 sprite.height = parseFloat(sprite.height);
780 sprite.height = !isNaN(sprite.height) ? sprite.height : parseFloat(this.spritesGroup.height);
781 sprite.height = !isNaN(sprite.height) ? sprite.height : parseFloat(CB_GraphicSprites.HEIGHT_DEFAULT) || 0;
782 sprite.zIndex = parseFloat(sprite.zIndex);
783 sprite.zIndex = !isNaN(sprite.zIndex) ? sprite.zIndex : parseFloat(this.spritesGroup.zIndex);
784 sprite.zIndex = !isNaN(sprite.zIndex) ? sprite.zIndex : parseFloat(CB_GraphicSprites.ZINDEX_DEFAULT) || 0;
785 sprite.disabled = !!sprite.disabled || !!this.spritesGroup.disabled;
786 if (!sprite.disabled &amp;&amp; this.isDisabled()) { this.setDisabled(false); } //If it is enabled and its sprites group parent is not, all the sprites group must be enabled.
787 sprite.data = typeof(sprite.data) === "object" &amp;&amp; sprite.data !== null ? sprite.data : this.spritesGroup.data;
788 if (typeof(this.spritesGroup.data) === "object" &amp;&amp; this.spritesGroup.data !== null) { sprite.data = CB_combineJSON(this.spritesGroup.data, sprite.data); } //Combine objects.
789 sprite.data = typeof(sprite.data) === "object" &amp;&amp; sprite.data !== null ? CB_copyObject(sprite.data, false) : {};
790 sprite.data.that = sprite;
791 sprite.data.getThis = function() { return this.that; };
792 sprite.subSprites = CB_isArray(sprite.subSprites) ? (sprite.byReference ? sprite.subSprites : CB_Arrays.copy(sprite.subSprites)) : [];
793
794 //Inserts the methods:
795 sprite.removeAll = sprite.removeSubSprites = function() { return CB_GraphicSprites.prototype.removeSubSprites.call(this.container, sprite); }
796 sprite.insertSubSprites = function(subSprites) { return CB_GraphicSprites.prototype.insertSubSprites.call(this.container, subSprites, sprite); }
797 sprite.remove = function(index) { return CB_GraphicSprites.prototype.removeSubSprite.call(this.container, index, sprite); }
798 sprite.removeById = function(id) { return CB_GraphicSprites.prototype.removeSubSpriteById.call(this.container, id, sprite); }
799 sprite.insert = function(subSprite) { return CB_GraphicSprites.prototype.insertSubSprite.call(this.container, subSprite, sprite); }
800 sprite.getAll = sprite.getSubSprites = function(orderedByZIndex, returnValueOnFail) { return CB_GraphicSprites.prototype.getSubSprites.call(this.container, sprite, orderedByZIndex, returnValueOnFail); }
801 sprite.get = function(index, returnValueOnFail) { return CB_GraphicSprites.prototype.getSubSprite.call(this.container, index, sprite, returnValueOnFail); }
802 sprite.getById = function(id, returnValueOnFail) { return CB_GraphicSprites.prototype.getSubSpriteById.call(this.container, id, sprite, returnValueOnFail); }
803 sprite.getIndexById = function(id) { return CB_GraphicSprites.prototype.getSubSpriteIndexById.call(this.container, id, sprite); }
804 sprite.executeFunctionAll = sprite.executeAll = sprite.forEach = function(functionEach, orderedByZIndex, delayBetweenEach, returnSetTimeoutsArray, delayBetweenEachAffectsFirst, functionFinish) { return CB_GraphicSprites.prototype.executeFunctionAllSubSprites.call(this.container, functionEach, orderedByZIndex, delayBetweenEach, sprite, returnSetTimeoutsArray, delayBetweenEachAffectsFirst, functionFinish); }
805 sprite.getZIndex = function(returnValueOnFail) { return CB_GraphicSprites.prototype.getZIndexSprite.call(this.container, sprite, returnValueOnFail); }
806 sprite.setZIndex = function(zIndex) { return CB_GraphicSprites.prototype.setZIndexSprite.call(this.container, sprite, zIndex); }
807 sprite.isDisabled = function() { return CB_GraphicSprites.prototype.isDisabledSprite.call(this.container, sprite); }
808 sprite.setDisabled = function(disabled, affectSubSprites, affectParent, affectParentChildren) { return CB_GraphicSprites.prototype.setDisabledSprite.call(this.container, sprite, disabled, affectSubSprites, affectParent, affectParentChildren); }
809 sprite.setTime = function(time) { return CB_GraphicSprites.prototype.setTime.call(this, time, false, false); }
810 sprite.getTime = function(returnValueOnFail) { return CB_GraphicSprites.prototype.getTime.call(this, returnValueOnFail); }
811 sprite.getTimeElapsed = function(timeToCompare) { return CB_GraphicSprites.prototype.getTimeElapsed.call(this, timeToCompare); }
812 sprite.getPointer = sprite.getCurrentPosition = function() { return CB_GraphicSprites.prototype.getPointer.call(this.container); }
813 sprite.getPointerPrevious = sprite.getPreviousPosition = function() { return CB_GraphicSprites.prototype.getPointerPrevious.call(this.container); }
814 sprite.setPointer = sprite.setCurrentPosition = function(position, loop) { CB_GraphicSprites.prototype.setPointer.call(this.container, position, loop); return this.getCurrent(); }
815 sprite.getCurrent = sprite.current = sprite.now = function() { return CB_GraphicSprites.prototype.getCurrent.call(this.container); }
816 sprite.setNext = sprite.next = function(loop) { return CB_GraphicSprites.prototype.setNext.call(this.container, loop); }
817 sprite.setPrevious = sprite.previous = function(loop) { return CB_GraphicSprites.prototype.setPrevious.call(this.container, loop); }
818 sprite.getPrevious = function() { return CB_GraphicSprites.prototype.getPrevious.call(this.container); }
819 sprite.setPropertyCascade = function(propertyName, value) { return CB_GraphicSprites.prototype.setPropertyCascade.call(this, propertyName, value, false); }
820
821 //Inserts the given sub-sprites, one by one:
822 this.insertSubSprites(sprite.subSprites, sprite);
823
824 //Inserts the sprite:
825 this.spritesGroup.sprites = this.spritesGroup.sprites || []; ////CB_Arrays.copy(this.spritesGroup.sprites);
826 var position = this.getSpriteIndexById(sprite.id); //If there is a sprite with the same ID, it will be replaced by the new one (in the same position):
827 position = position !== -1 ? position : this.spritesGroup.sprites.length;
828 sprite.position = position;
829 this.spritesGroup.sprites[position] = sprite;
830
831 //If desired, updates the array with the sprites ordered by z-index:
832 if (!avoidUpdatingSpritesByZIndex) { this.updateSpritesByZIndex(); }
833
834 this.spritesGroup.sprites = this.spritesGroup.sprites;
835
836 //Keeps the pointer if the position is valid or sets to the last position if the position was greater than the current limit or uses the first position otherwise:
837 this.setPointer(this.getPointer());
838
839 //Returns the sprite:
840 return sprite;
841}
842
843
844/**
845 * Alias for {@link CB_GraphicSprites#removeSubSprites}.
846 * @function CB_GraphicSprites#removeSubSpritesAll
847 * @see {@link CB_GraphicSprites#removeSubSprites}
848 */
849/**
850 * Removes all the sub-sprites from a given sprite ({@link CB_GraphicSprites.SPRITE_OBJECT} object) by clearing its "subSprites" property (leaving an empty array).
851 * @function
852 * @param {CB_GraphicSprites.SPRITE_OBJECT} [sprite=CB_GraphicSprites#getCurrent()] - Object with the sprite whose sub-sprites we want to remove. If not provided, it will use the {@link CB_GraphicSprites.SPRITE_OBJECT} object which the pointer (set in the {@link CB_GraphicSprites#pointer} property) is currently pointing to (using the returning value of the {@link CB_GraphicSprites#getCurrent} method internally).
853 * @returns {boolean} Returns true if the sub-sprites have been deleted or false otherwise.
854 */
855CB_GraphicSprites.prototype.removeSubSprites = CB_GraphicSprites.prototype.removeSubSpritesAll = function(sprite)
856{
857 var removed = false;
858 sprite = sprite || this.getCurrent();
859 if (sprite)
860 {
861 if (this.spritesGroup &amp;&amp; this.spritesGroup.sprites)
862 {
863 var spritesLength = this.spritesGroup.sprites.length;
864 for (var x = 0; x &lt; spritesLength; x++)
865 {
866 if (this.spritesGroup.sprites[x] === sprite) { this.spritesGroup.sprites[x].subSprites = []; this.spritesGroup.sprites[x].subSpritesByZIndex = []; removed = true; break; } //Just removes one.
867 }
868 }
869 }
870 return removed;
871}
872
873
874/**
875 * Adds the given sub-sprites to the desired sprite. Calls the {@link CB_GraphicSprites#insertSubSprite} and {@link CB_GraphicSprites#updateSubSpritesByZIndex} methods internally.
876 * @function
877 * @param {array} subSprites - Numeric array with the desired sub-sprites ({@link CB_GraphicSprites.SUBSPRITE_OBJECT} objects). They will be stored inside the given sprite.
878 * @param {CB_GraphicSprites.SPRITE_OBJECT} [sprite=CB_GraphicSprites#getCurrent()] - Object with the desired sprite. If not provided, it will use the {@link CB_GraphicSprites.SPRITE_OBJECT} object which the pointer (set in the {@link CB_GraphicSprites#pointer} property) is currently pointing to (using the returning value of the {@link CB_GraphicSprites#getCurrent} method internally).
879 * @returns {array} Returns an array with the {@link CB_GraphicSprites.SUBSPRITE_OBJECT} objects which have been inserted (they could have been modified/sanitized from the given one and some missing properties or those which were wrong could have been inherited).
880 */
881CB_GraphicSprites.prototype.insertSubSprites = function(subSprites, sprite)
882{
883 //Sets the properties (sanitizing them):
884 sprite = sprite || this.getCurrent();
885 subSprites = CB_isArray(subSprites) ? subSprites : [];
886
887 //Inserts the given sub-sprites, one by one:
888 var subSpritesInserted = [];
889 var subSpritesLength = subSprites.length;
890 for (var x = 0; x &lt; subSpritesLength; x++)
891 {
892 subSpritesInserted[subSpritesInserted.length] = this.insertSubSprite(subSprites[x], sprite, true);
893 }
894
895 //Updates the array with the sub-sprites ordered by z-index:
896 this.updateSubSpritesByZIndex(sprite);
897
898 return subSpritesInserted;
899}
900
901
902/**
903 * Updates (sorts again) the "subSpritesByZIndex" property (which is an array with the sub-sprites ordered by z-index, whose data comes from the array in the "subSprites" property of the given {@link CB_GraphicSprites.SPRITE_OBJECT} object)) of the desired sprite.
904 * @function
905 * @param {CB_GraphicSprites.SPRITE_OBJECT} [sprite=CB_GraphicSprites#getCurrent()] - Object with the sprite whose sub-sprites we want to remove. If not provided, it will use the {@link CB_GraphicSprites.SPRITE_OBJECT} object which the pointer (set in the {@link CB_GraphicSprites#pointer} property) is currently pointing to (using the returning value of the {@link CB_GraphicSprites#getCurrent} method internally).
906 * @returns {array} Returns the "subSpritesByZIndex" array after updating it. Returns null if the property could not be obtained or updated.
907 */
908CB_GraphicSprites.prototype.updateSubSpritesByZIndex = function(sprite)
909{
910 sprite = sprite || this.getCurrent();
911 if (sprite &amp;&amp; sprite.subSprites)
912 {
913 var subSpritesLength = sprite.subSprites.length;
914 if (subSpritesLength)
915 {
916 var elementIndex = null;
917 sprite.subSpritesByZIndex = [];
918 for (var x = 0; x &lt; subSpritesLength; x++)
919 {
920 indexElement = CB_GraphicSpritesScene._choosePositionByZIndex(sprite.subSpritesByZIndex, sprite.subSprites[x]);
921 sprite.subSpritesByZIndex = CB_Arrays.insertElement(sprite.subSpritesByZIndex, indexElement, sprite.subSprites[x]);
922 sprite.subSprites[x].positionByZIndex = indexElement;
923 }
924 return sprite.subSpritesByZIndex;
925 }
926 }
927 return null;
928}
929
930
931/**
932 * Removes a sub-sprite from a given sprite ({@link CB_GraphicSprites.SPRITE_OBJECT} object) by its index (its position in the array which is in the "subSprites" property of the given {@link CB_GraphicSprites.SPRITE_OBJECT} object). Calls the {@link CB_GraphicSprites#updateSubSpritesByZIndex} method internally.
933 * @function
934 * @param {integer} [index=0] - The index where the sub-sprite is located (its position in the array which is in the "subSprites" property of the given {@link CB_GraphicSprites.SPRITE_OBJECT} object).
935 * @param {CB_GraphicSprites.SPRITE_OBJECT} [sprite=CB_GraphicSprites#getCurrent()] - Object with the sprite whose sub-sprites we want to remove. If not provided, it will use the {@link CB_GraphicSprites.SPRITE_OBJECT} object which the pointer (set in the {@link CB_GraphicSprites#pointer} property) is currently pointing to (using the returning value of the {@link CB_GraphicSprites#getCurrent} method internally).
936 * @returns {boolean} Returns true if the sub-sprite has been deleted or false otherwise.
937 */
938CB_GraphicSprites.prototype.removeSubSprite = function(index, sprite)
939{
940 var removed = false;
941 if (this.spritesGroup &amp;&amp; this.spritesGroup.sprites)
942 {
943 sprite = sprite || this.getCurrent();
944 if (sprite)
945 {
946 index = parseInt(index);
947 index = isNaN(index) ? 0 : index;
948 if (index &lt; 0) { index *= -1; } //It must be a positive integer.
949 var subSpritesLeft = null;
950 var spritesLength = this.spritesGroup.sprites.length;
951 for (var x = 0; x &lt; spritesLength; x++)
952 {
953 if (this.spritesGroup.sprites[x] === sprite)
954 {
955 removed = false;
956 subSpritesLeft = CB_Arrays.removeElementByPosition(this.spritesGroup.sprites[x].subSprites, index, function() { removed = true; });
957 if (removed)
958 {
959 this.spritesGroup.sprites[x].subSprites = subSpritesLeft;
960
961 //Updates the array with the sub-sprites ordered by z-index:
962 this.updateSubSpritesByZIndex(sprite);
963
964 break; //Just removes it from one.
965 }
966 }
967 }
968 }
969 }
970 return removed;
971}
972
973
974/**
975 * Removes a sub-sprite from a given sprite ({@link CB_GraphicSprites.SPRITE_OBJECT} object) by its identifier. Calls the {@link CB_GraphicSprites#updateSubSpritesByZIndex} method internally.
976 * @function
977 * @param {string|*} [id=undefined] - The identifier of the sprite.
978 * @param {CB_GraphicSprites.SPRITE_OBJECT} [sprite=CB_GraphicSprites#getCurrent] - Object with the sprite whose sub-sprites we want to remove.
979 * @returns {boolean} Returns true if the sub-sprite has been deleted or false otherwise.
980 * @todo Optimize it (perhaps using a cache matching the IDs with their position, maybe using the "position" or "positionByZIndex" properties).
981 */
982CB_GraphicSprites.prototype.removeSubSpriteById = function(id, sprite)
983{
984 var removed = false;
985 if (this.spritesGroup &amp;&amp; this.spritesGroup.sprites)
986 {
987 sprite = sprite || this.getCurrent();
988 if (sprite)
989 {
990 var subSpritesLeft = null;
991 var spritesLength = this.spritesGroup.sprites.length;
992 for (var x = 0; x &lt; spritesLength; x++)
993 {
994 if (this.spritesGroup.sprites[x] === sprite)
995 {
996 removed = false;
997 subSpritesLeft = CB_Arrays.removeDuplicated(this.spritesGroup.sprites[x].subSprites, function(value, position, array) { if (value &amp;&amp; value.id === id) { removed = true; return true; }; return false; }, true);
998 if (removed)
999 {
1000 this.spritesGroup.sprites[x].subSprites = subSpritesLeft;
1001
1002 //Updates the array with the sub-sprites ordered by z-index:
1003 this.updateSubSpritesByZIndex(sprite);
1004
1005 break; //Just removes it from one.
1006 }
1007 }
1008 }
1009 }
1010 }
1011 return removed;
1012}
1013
1014
1015/**
1016 * Adds the given sub-sprite to the desired sprite. If a sub-sprite with the same identifier already exists, it will be replaced by the new one in its same position.
1017 * @function
1018 * @param {CB_GraphicSprites.SUBSPRITE_OBJECT} subSprite - Object with the desired sub-sprite. It will be stored inside the given sprite.
1019 * @param {CB_GraphicSprites.SPRITE_OBJECT} sprite - Object with the desired sprite.
1020 * @param {boolean} [avoidUpdatingSubSpritesByZIndex=false] - If set to true, it will not call the {CB_GraphicSprites#updateSubSpritesByZIndex} method internally. Internal usage recommended only.
1021 * @returns {CB_GraphicSprites.SUBSPRITE_OBJECT} Returns the {@link CB_GraphicSprites.SUBSPRITE_OBJECT} object which has been inserted (it could have been modified/sanitized from the given one and some missing properties or those which were wrong could have been inherited).
1022 */
1023CB_GraphicSprites.prototype.insertSubSprite = function(subSprite, sprite, avoidUpdatingSubSpritesByZIndex)
1024{
1025 //Sets the properties (sanitizing them):
1026 this.spritesGroup = this.spritesGroup || {};
1027 sprite = sprite || {};
1028 subSprite = subSprite || {};
1029 if (sprite.byReference !== true &amp;&amp; sprite.byReference !== false) { sprite.byReference = this.byReference_DEFAULT; }
1030 subSprite = subSprite.byReference ? subSprite : CB_copyObject(subSprite);
1031 sprite.isSubSprite = true;
1032 subSprite.type = "subSprite";
1033 subSprite.container = this;
1034 subSprite.parent = sprite;
1035 subSprite.time = !isNaN(parseInt(subSprite.time)) ? parseInt(subSprite.time) : !isNaN(parseInt(sprite.time)) ? parseInt(sprite.time) : 0;
1036 subSprite.id = subSprite.id || "CB_GraphicSprites.subSprite_" + CB_GraphicSprites._idSubSpriteUnique++;
1037 subSprite.src = subSprite.src || !isNaN(subSprite.src) &amp;&amp; subSprite.src !== null ? subSprite.src : sprite.src || !isNaN(sprite.src) &amp;&amp; sprite.src !== null ? sprite.src : this.spritesGroup.src || !isNaN(this.spritesGroup.src) &amp;&amp; this.spritesGroup.src !== null ? this.spritesGroup.src : "";
1038 subSprite.srcType = subSprite.srcType || sprite.srcType || this.spritesGroup.srcType || CB_GraphicSprites.SRC_TYPES_DEFAULT;
1039 subSprite.srcLeft = parseFloat(subSprite.srcLeft);
1040 subSprite.srcLeft = !isNaN(subSprite.srcLeft) ? subSprite.srcLeft : parseFloat(sprite.srcLeft);
1041 subSprite.srcLeft = !isNaN(subSprite.srcLeft) ? subSprite.srcLeft : parseFloat(this.spritesGroup.srcLeft);
1042 subSprite.srcLeft = !isNaN(subSprite.srcLeft) ? subSprite.srcLeft : parseFloat(CB_GraphicSprites.LEFT_SOURCE_DEFAULT) || 0;
1043 subSprite.left = parseFloat(subSprite.left);
1044 //subSprite.left = !isNaN(subSprite.left) ? subSprite.left : parseFloat(sprite.left);
1045 //subSprite.left = !isNaN(subSprite.left) ? subSprite.left : parseFloat(this.spritesGroup.left);
1046 subSprite.left = !isNaN(subSprite.left) ? subSprite.left : parseFloat(CB_GraphicSprites.LEFT_DEFAULT) || 0;
1047 subSprite.srcTop = parseFloat(subSprite.srcTop);
1048 subSprite.srcTop = !isNaN(subSprite.srcTop) ? subSprite.srcTop : parseFloat(sprite.srcTop);
1049 subSprite.srcTop = !isNaN(subSprite.srcTop) ? subSprite.srcTop : parseFloat(this.spritesGroup.srcTop);
1050 subSprite.srcTop = !isNaN(subSprite.srcTop) ? subSprite.srcTop : parseFloat(CB_GraphicSprites.TOP_SOURCE_DEFAULT) || 0;
1051 subSprite.top = parseFloat(subSprite.top);
1052 //subSprite.top = !isNaN(subSprite.top) ? subSprite.top : parseFloat(sprite.top);
1053 //subSprite.top = !isNaN(subSprite.top) ? subSprite.top : parseFloat(this.spritesGroup.top);
1054 subSprite.top = !isNaN(subSprite.top) ? subSprite.top : parseFloat(CB_GraphicSprites.TOP_DEFAULT) || 0;
1055 subSprite.srcWidth = parseFloat(subSprite.srcWidth);
1056 subSprite.srcWidth = !isNaN(subSprite.srcWidth) ? subSprite.srcWidth : parseFloat(sprite.srcWidth);
1057 subSprite.srcWidth = !isNaN(subSprite.srcWidth) ? subSprite.srcWidth : parseFloat(this.spritesGroup.srcWidth);
1058 subSprite.srcWidth = !isNaN(subSprite.srcWidth) ? subSprite.srcWidth : parseFloat(CB_GraphicSprites.WIDTH_SOURCE_DEFAULT) || 0;
1059 subSprite.width = parseFloat(subSprite.width);
1060 subSprite.width = !isNaN(subSprite.width) ? subSprite.width : parseFloat(sprite.width);
1061 subSprite.width = !isNaN(subSprite.width) ? subSprite.width : parseFloat(this.spritesGroup.width);
1062 subSprite.width = !isNaN(subSprite.width) ? subSprite.width : parseFloat(CB_GraphicSprites.WIDTH_DEFAULT) || 0;
1063 subSprite.srcHeight = parseFloat(subSprite.srcHeight);
1064 subSprite.srcHeight = !isNaN(subSprite.srcHeight) ? subSprite.srcHeight : parseFloat(sprite.srcHeight);
1065 subSprite.srcHeight = !isNaN(subSprite.srcHeight) ? subSprite.srcHeight : parseFloat(this.spritesGroup.srcHeight);
1066 subSprite.srcHeight = !isNaN(subSprite.srcHeight) ? subSprite.srcHeight : parseFloat(CB_GraphicSprites.HEIGHT_SOURCE_DEFAULT) || 0;
1067 subSprite.height = parseFloat(subSprite.height);
1068 subSprite.height = !isNaN(subSprite.height) ? subSprite.height : parseFloat(sprite.height);
1069 subSprite.height = !isNaN(subSprite.height) ? subSprite.height : parseFloat(this.spritesGroup.height);
1070 subSprite.height = !isNaN(subSprite.height) ? subSprite.height : parseFloat(CB_GraphicSprites.HEIGHT_DEFAULT) || 0;
1071 subSprite.zIndex = parseFloat(subSprite.zIndex);
1072 subSprite.zIndex = !isNaN(subSprite.zIndex) ? subSprite.zIndex : parseFloat(sprite.zIndex);
1073 subSprite.zIndex = !isNaN(subSprite.zIndex) ? subSprite.zIndex : parseFloat(this.spritesGroup.zIndex);
1074 subSprite.zIndex = !isNaN(subSprite.zIndex) ? subSprite.zIndex : parseFloat(CB_GraphicSprites.ZINDEX_DEFAULT) || 0;
1075 subSprite.disabled = !!subSprite.disabled || !!sprite.disabled || !!this.spritesGroup.disabled;
1076 if (!subSprite.disabled &amp;&amp; this.isDisabledSprite(sprite)) { this.setDisabled(false); } //If it is enabled but its sprite parent is not, all the sprites group must be enabled.
1077 subSprite.data = typeof(subSprite.data) === "object" &amp;&amp; subSprite.data !== null ? subSprite.data : sprite.data;
1078 if (typeof(sprite.data) === "object" &amp;&amp; sprite.data !== null) { subSprite.data = CB_combineJSON(sprite.data, subSprite.data); } //Combine objects.
1079 subSprite.data = typeof(subSprite.data) === "object" &amp;&amp; subSprite.data !== null ? subSprite.data : this.spritesGroup.data;
1080 if (typeof(this.spritesGroup.data) === "object" &amp;&amp; this.spritesGroup.data !== null) { subSprite.data = CB_combineJSON(this.spritesGroup.data, subSprite.data); } //Combine objects.
1081 subSprite.data = typeof(subSprite.data) === "object" &amp;&amp; subSprite.data !== null ? CB_copyObject(subSprite.data, false) : {};
1082 subSprite.data.that = subSprite;
1083 subSprite.data.getThis = function() { return this.that; };
1084
1085 //Inserts the methods:
1086 subSprite.getZIndex = function(returnValueOnFail) { return CB_GraphicSprites.prototype.getZIndexSubSprite.call(this.container, subSprite, returnValueOnFail); }
1087 subSprite.setZIndex = function(zIndex) { return CB_GraphicSprites.prototype.setZIndexSubSprite.call(this.container, subSprite, zIndex); }
1088 subSprite.isDisabled = function() { return CB_GraphicSprites.prototype.isDisabledSubSprite.call(this.container, subSprite); }
1089 subSprite.setDisabled = function(disabled, affectParents, affectParentsChildren) { return CB_GraphicSprites.prototype.setDisabledSubSprite.call(this.container, subSprite, disabled, affectParents, affectParentsChildren); }
1090 subSprite.setTime = function(time) { return CB_GraphicSprites.prototype.setTime.call(this, time, false, false); }
1091 subSprite.getTime = function(returnValueOnFail) { return CB_GraphicSprites.prototype.getTime.call(this, returnValueOnFail, true); }
1092 subSprite.getTimeElapsed = function(timeToCompare) { return CB_GraphicSprites.prototype.getTimeElapsed.call(this, timeToCompare, true); }
1093
1094 //Inserts the sub-sprite:
1095 sprite.subSprites = CB_isArray(sprite.subSprites) ? (sprite.byReference ? sprite.subSprites : CB_Arrays.copy(sprite.subSprites)) : [];
1096 var position = this.getSubSpriteIndexById(subSprite.id, sprite); //If there is a sub-sprite with the same ID, it will be replaced by the new one (in the same position).
1097 position = position !== -1 ? position : sprite.subSprites.length;
1098 subSprite.position = position;
1099 sprite.subSprites[position] = subSprite;
1100
1101 //If desired, updates the array with the sub-sprites ordered by z-index:
1102 if (!avoidUpdatingSubSpritesByZIndex) { this.updateSubSpritesByZIndex(sprite); }
1103
1104 //Returns the sub-sprite:
1105 return subSprite;
1106}
1107
1108
1109/**
1110 * Gets the sprites group object (the internal {@link CB_GraphicSprites.SPRITES_OBJECT} object, if any).
1111 * @function
1112 * @param {*} [returnValueOnFail=undefined] - The value we want it to return in the case that no value is found. If not provided, undefined will be returned.
1113 * @returns {CB_GraphicSprites.SPRITES_OBJECT|*} Returns a {@link CB_GraphicSprites.SPRITES_OBJECT} object with all the sprites or the value of "returnValueOnFail" otherwise.
1114 */
1115CB_GraphicSprites.prototype.getSpritesGroup = function(returnValueOnFail)
1116{
1117 return this.spritesGroup || returnValueOnFail;
1118}
1119
1120
1121/**
1122 * Alias for {@link CB_GraphicSprites#getSprites}.
1123 * @function CB_GraphicSprites#getAll
1124 * @see {@link CB_GraphicSprites#getSprites}
1125 */
1126/**
1127 * Alias for {@link CB_GraphicSprites#getSprites}.
1128 * @function CB_GraphicSprites#getSpritesAll
1129 * @see {@link CB_GraphicSprites#getSprites}
1130 */
1131/**
1132 * Gets all the sprites (the "sprites" property of the internal {@link CB_GraphicSprites.SPRITES_OBJECT} object, if any).
1133 * @function
1134 * @param {boolean} [orderedByZIndex=false] - If set to true, it will return the sprites sorted by their z-index (ascending order).
1135 * @param {*} [returnValueOnFail=undefined] - The value we want it to return in the case that no value is found. If not provided, undefined will be returned.
1136 * @returns {array|*} Returns an array with all the {@link CB_GraphicSprites.SPRITE_OBJECT} objects or the value of "returnValueOnFail" otherwise.
1137 */
1138CB_GraphicSprites.prototype.getSprites = CB_GraphicSprites.prototype.getSpritesAll = CB_GraphicSprites.prototype.getAll = function(orderedByZIndex, returnValueOnFail)
1139{
1140 if (this.spritesGroup)
1141 {
1142 if (!orderedByZIndex)
1143 {
1144 return (this.spritesGroup.sprites) ? this.spritesGroup.sprites : returnValueOnFail;
1145 }
1146 else
1147 {
1148 return (this.spritesGroup.spritesByZIndex) ? this.spritesGroup.spritesByZIndex : returnValueOnFail;
1149 }
1150 }
1151 return returnValueOnFail;
1152}
1153
1154
1155/**
1156 * Alias for {@link CB_GraphicSprites#getSprite}.
1157 * @function CB_GraphicSprites#get
1158 * @see {@link CB_GraphicSprites#getSprite}
1159 */
1160/**
1161 * Gets a desired sprite object through its index (its position in the {@link CB_GraphicSprites#spritesGroup.sprites} array). Faster than getting it through its identifier with the {@link CB_GraphicSprites#getSpriteById} method.
1162 * @function
1163 * @param {integer} [index=0] - The index where the desired sprite must be located (its position in the {@link CB_GraphicSprites#spritesGroup.sprites} array).
1164 * @param {*} [returnValueOnFail=undefined] - The value we want it to return in the case that no value is found. If not provided, undefined will be returned.
1165 * @returns {CB_GraphicSprites.SPRITE_OBJECT|*} Returns a {@link CB_GraphicSprites.SPRITE_OBJECT} object if found or the value of "returnValueOnFail" otherwise.
1166 */
1167CB_GraphicSprites.prototype.getSprite = CB_GraphicSprites.prototype.get = function(index, returnValueOnFail)
1168{
1169 index = parseInt(index);
1170 index = isNaN(index) ? 0 : index;
1171 if (index &lt; 0) { index *= -1; } //It must be a positive integer.
1172 return this.spritesGroup &amp;&amp; this.spritesGroup.sprites &amp;&amp; this.spritesGroup.sprites[index] ? this.spritesGroup.sprites[index] : returnValueOnFail;
1173}
1174
1175
1176/**
1177 * Alias for {@link CB_GraphicSprites#getSpriteById}.
1178 * @function CB_GraphicSprites#getById
1179 * @see {@link CB_GraphicSprites#getSpriteById}
1180 */
1181/**
1182 * Gets a desired sprite object through its identifier. Slower than getting it through its index with the {@link CB_GraphicSprites#getSprite} method.
1183 * @function
1184 * @param {string|*} [id=undefined] - The identifier of the sprite that we want to get.
1185 * @param {*} [returnValueOnFail=undefined] - The value we want it to return in the case that no value is found. If not provided, undefined will be returned.
1186 * @returns {CB_GraphicSprites.SPRITE_OBJECT|*} Returns a {@link CB_GraphicSprites.SPRITE_OBJECT} object if found or the value of "returnValueOnFail" otherwise.
1187 */
1188CB_GraphicSprites.prototype.getSpriteById = CB_GraphicSprites.prototype.getById = function(id, returnValueOnFail)
1189{
1190 var index = this.getSpriteIndexById(id);
1191 return index !== -1 ? this.spritesGroup.sprites[index] : returnValueOnFail;
1192}
1193
1194
1195/**
1196 * Alias for {@link CB_GraphicSprites#getSpriteIndexById}.
1197 * @function CB_GraphicSprites#getIndexById
1198 * @see {@link CB_GraphicSprites#getSpriteIndexById}
1199 */
1200/**
1201 * Gets the index (the position in the {@link CB_GraphicSprites#spritesGroup.sprites} array) of a desired sprite by its identifier.
1202 * @function
1203 * @param {string|*} [id=undefined] - The identifier of the sprite whose index we want to get.
1204 * @returns {integer} Returns the index (the position in the {@link CB_GraphicSprites#spritesGroup.sprites} array) of the desired sprite or -1 if not found.
1205 * @todo Optimize it (perhaps using a cache matching the IDs with their position, maybe using the "position" or "positionByZIndex" properties).
1206 */
1207CB_GraphicSprites.prototype.getSpriteIndexById = CB_GraphicSprites.prototype.getIndexById = function(id)
1208{
1209 if (this.spritesGroup &amp;&amp; this.spritesGroup.sprites)
1210 {
1211 var spritesLength = this.spritesGroup.sprites.length;
1212 for (var x = 0; x &lt; spritesLength; x++)
1213 {
1214 if (this.spritesGroup.sprites[x].id === id) { return x; }
1215 }
1216 }
1217 return -1;
1218}
1219
1220
1221/**
1222 * Gets an array with all the {@link CB_GraphicSprites.SUBSPRITE_OBJECT} objects of a given {@link CB_GraphicSprites.SPRITE_OBJECT} object.
1223 * @function
1224 * @param {CB_GraphicSprites.SPRITE_OBJECT} [sprite=CB_GraphicSprites#getCurrent()] - The {@link CB_GraphicSprites.SPRITE_OBJECT} object which contains the sprite and its sub-sprites. If not provided, it will use the {@link CB_GraphicSprites.SPRITE_OBJECT} object which the pointer (set in the {@link CB_GraphicSprites#pointer} property) is currently pointing to (using the returning value of the {@link CB_GraphicSprites#getCurrent} method internally).
1225 * @param {boolean} [orderedByZIndex=false] - If set to true, it will return the sub-sprites sorted by their z-index (ascending order).
1226 * @param {*} [returnValueOnFail=undefined] - The value we want it to return in the case that no value is found. If not provided, undefined will be returned.
1227 * @returns {array|*} Returns an array with all the {@link CB_GraphicSprites.SUBSPRITE_OBJECT} objects of the given {@link CB_GraphicSprites.SPRITE_OBJECT} object or the value of "returnValueOnFail" otherwise.
1228 */
1229CB_GraphicSprites.prototype.getSubSprites = function(sprite, orderedByZIndex, returnValueOnFail)
1230{
1231 sprite = sprite || this.getCurrent();
1232
1233 if (sprite)
1234 {
1235 if (!orderedByZIndex)
1236 {
1237 return sprite.subSprites ? sprite.subSprites : returnValueOnFail;
1238 }
1239 else
1240 {
1241 return sprite.subSpritesByZIndex ? sprite.subSpritesByZIndex : returnValueOnFail;
1242 }
1243 }
1244 return returnValueOnFail;
1245}
1246
1247
1248/**
1249 * Gets a desired sub-sprite object through its index (its position in the array which is in the "subSprites" property of the given {@link CB_GraphicSprites.SPRITE_OBJECT} object). Faster than getting it through its identifier with the {@link CB_GraphicSprites#getSubSpriteById} method.
1250 * @function
1251 * @param {integer} [index=0] - The index where the desired sub-sprite must be located (its position in the array which is in the "subSprites" property of the given {@link CB_GraphicSprites.SPRITE_OBJECT} object).
1252 * @param {CB_GraphicSprites.SPRITE_OBJECT} [sprite=CB_GraphicSprites#getCurrent()] - The {@link CB_GraphicSprites.SPRITE_OBJECT} object which contains the sprite and its sub-sprites. If not provided, it will use the {@link CB_GraphicSprites.SPRITE_OBJECT} object which the pointer (set in the {@link CB_GraphicSprites#pointer} property) is currently pointing to (using the returning value of the {@link CB_GraphicSprites#getCurrent} method internally).
1253 * @param {*} [returnValueOnFail=undefined] - The value we want it to return in the case that no value is found. If not provided, undefined will be returned.
1254 * @returns {CB_GraphicSprites.SUBSPRITE_OBJECT|*} Returns a {@link CB_GraphicSprites.SUBSPRITE_OBJECT} object if found or the value of "returnValueOnFail" otherwise.
1255 */
1256CB_GraphicSprites.prototype.getSubSprite = function(index, sprite, returnValueOnFail)
1257{
1258 index = parseInt(index);
1259 index = isNaN(index) ? 0 : index;
1260 if (index &lt; 0) { index *= -1; } //It must be a positive integer.
1261 sprite = sprite || this.getCurrent();
1262 return sprite &amp;&amp; sprite.subSprites &amp;&amp; sprite.subSprites[index] ? sprite.subSprites[index] : returnValueOnFail;
1263}
1264
1265
1266/**
1267 * Gets a desired sub-sprite object through its identifier from the given {@link CB_GraphicSprites.SPRITE_OBJECT} object. Slower than getting it through its index with the {@link CB_GraphicSprites#getSubSprite} method.
1268 * @function
1269 * @param {string|*} [id=undefined] - The identifier of the sub-sprite that we want to get.
1270 * @param {CB_GraphicSprites.SPRITE_OBJECT} [sprite=CB_GraphicSprites#getCurrent()] - The {@link CB_GraphicSprites.SPRITE_OBJECT} object which contains the sprite and its sub-sprites. If not provided, it will use the {@link CB_GraphicSprites.SPRITE_OBJECT} object which the pointer (set in the {@link CB_GraphicSprites#pointer} property) is currently pointing to (using the returning value of the {@link CB_GraphicSprites#getCurrent} method internally).
1271 * @param {*} [returnValueOnFail=undefined] - The value we want it to return in the case that no value is found. If not provided, undefined will be returned.
1272 * @returns {CB_GraphicSprites.SUBSPRITE_OBJECT|*} Returns a {@link CB_GraphicSprites.SUBSPRITE_OBJECT} object if found or the value of "returnValueOnFail" otherwise.
1273 */
1274CB_GraphicSprites.prototype.getSubSpriteById = function(id, sprite, returnValueOnFail)
1275{
1276 sprite = sprite || this.getCurrent();
1277 var index = this.getSubSpriteIndexById(id, sprite);
1278 return index !== -1 ? sprite.subSprites[index] : returnValueOnFail;
1279}
1280
1281
1282/**
1283 * Gets the index (its position in the array which is in the "subSprites" property of the given {@link CB_GraphicSprites.SPRITE_OBJECT} object) of a desired sub-sprite by its identifier.
1284 * @function
1285 * @param {string|*} [id=undefined] - The identifier of the sub-sprite whose index we want to get.
1286 * @param {CB_GraphicSprites.SPRITE_OBJECT} [sprite=CB_GraphicSprites#getCurrent()] - The {@link CB_GraphicSprites.SPRITE_OBJECT} object which contains the sprite and its sub-sprites. If not provided, it will use the {@link CB_GraphicSprites.SPRITE_OBJECT} object which the pointer (set in the {@link CB_GraphicSprites#pointer} property) is currently pointing to (using the returning value of the {@link CB_GraphicSprites#getCurrent} method internally).
1287 * @returns {integer} Returns the index (its position in the array which is in the "subSprites" property of the given {@link CB_GraphicSprites.SPRITE_OBJECT} object) of the desired sub-sprite or -1 if not found.
1288 * @todo Optimize it (perhaps using a cache matching the IDs with their position, maybe using the "position" or "positionByZIndex" properties).
1289 */
1290CB_GraphicSprites.prototype.getSubSpriteIndexById = function(id, sprite)
1291{
1292 sprite = sprite || this.getCurrent();
1293 if (sprite &amp;&amp; sprite.subSprites)
1294 {
1295 var subSpritesLength = sprite.subSprites.length;
1296 for (var x = 0; x &lt; subSpritesLength; x++)
1297 {
1298 if (sprite.subSprites[x].id === id) { return x; }
1299 }
1300 }
1301 return -1;
1302}
1303
1304
1305/**
1306 * Alias for {@link CB_GraphicSprites#executeFunctionAll}.
1307 * @function CB_GraphicSprites#executeAll
1308 * @see {@link CB_GraphicSprites#executeFunctionAll}
1309 */
1310 /**
1311 * Alias for {@link CB_GraphicSprites#executeFunctionAll}.
1312 * @function CB_GraphicSprites#forEach
1313 * @see {@link CB_GraphicSprites#executeFunctionAll}
1314 */
1315 /**
1316 * Alias for {@link CB_GraphicSprites#executeFunctionAll}.
1317 * @function CB_GraphicSprites#forEachSprite
1318 * @see {@link CB_GraphicSprites#executeFunctionAll}
1319 */
1320 /**
1321 * Performs a desired action, using the provided function, on all the existing sprites ({@link CB_GraphicSprites.SPRITE_OBJECT} objects) or on the desired ones (if provided). Calls the {@link CB_Arrays.executeFunctionAll} function internally and returns its returning value.
1322 * @function
1323 * @param {CB_Arrays.executeFunctionAll_ON_LOOP_CALLBACK} functionEach - Function that will be called for each sprite ({@link CB_GraphicSprites.SPRITE_OBJECT} object). As the first parameter it receives the {@link CB_GraphicSprites.SPRITE_OBJECT} object of the "sprites" being looped, as the second parameter the position of this {@link CB_GraphicSprites.SPRITE_OBJECT} object in the "sprites" array provided (or, if not provided, in the array returned by the {@link CB_GraphicSprites#getSprites} method), the third parameter is the array being looped and the fourth parameter will be the "delayBetweenEach" being used, being "this" the {@link CB_GraphicSprites.SPRITE_OBJECT} object itself.
1324 * @param {boolean} [orderedByZIndex=false] - If set to true, it will loop the sprites sorted by their z-index (ascending order).
1325 * @param {number|CB_Arrays.executeFunctionAll_ON_LOOP_CALLBACK} [delayBetweenEach=0] - If a value greater than zero is used, it will be used as the delay desired between each call to the "functionEach" function (calling them using the [setTimeout]{@link https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/setTimeout} function internally). If not provided or the value is 0 (zero) or lower, each call to the "functionEach" function will be performed immediately one after the other. If a function is provided, it will be called with the same parameters as the "functionEach" function and its returning value will be used as the delay (executed every loop for each {@link CB_GraphicSprites.SPRITE_OBJECT} object).
1326 * @param {array} [sprites={@link CB_GraphicSprites#getSprites}()] - A numeric array containing the sprites ({@link CB_GraphicSprites.SPRITE_OBJECT} objects) that we want to loop. It should contain only {@link CB_GraphicSprites.SPRITE_OBJECT} objects which are already in the current {@link CB_GraphicSprites} object. If not provided, it will use all the {@link CB_GraphicSprites.SPRITE_OBJECT} objects contained in the {@link CB_GraphicSprites} object.
1327 * @param {boolean} [returnSetTimeoutsArray=false] - Defines whether we want the method to return an integer or a numeric array with information of each [setTimeout]{@link https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/setTimeout} call. Returning an array with information of each [setTimeout]{@link https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/setTimeout} call is only useful when the [setTimeout]{@link https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/setTimeout} function is called internally, which happens when the "delayBetweenEach" parameter is greater than 0 (zero).
1328 * @param {boolean} [delayBetweenEachAffectsFirst=false] - If set to true, the desired delay (if any) will also affect the first call to the "functionEach" function.
1329 * @param {CB_Arrays.executeFunctionAll_ON_FINISH_CALLBACK} [functionFinish] - Function that will be called for when it has finished looping all the items. The first parameter will be the array which was looped, the second parameter will be the number of times that the "functionEach" callback was called (the most likely, matches the number of elements unless they are undefined or null), and the third parameter will be the maximum "delay" used, being "this" the array itself.
1330 * @returns {integer|array} If the "returnSetTimeoutsArray" parameter is set to false, it will return the number of calls to the "functionEach" function that were performed (which should be the same number as the {@link CB_GraphicSprites.SPRITE_OBJECT} objects given in the "sprites" parameter). Otherwise, if the "returnSetTimeoutsArray" is set to true, it will return a numeric array with a {@link CB_Arrays.executeFunctionAll_OBJECT} object for each {@link CB_GraphicSprites.SPRITE_OBJECT} given. The length of this array will also be the number of calls to the "functionEach" function that were performed. Note that if a value greater than 0 (zero) for the "delayBetweenEach" parameter has been provided, perhaps not all calls of the "functionEach" function will have been performed yet when exiting this method because of the asynchronous nature of the [setTimeout]{@link https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/setTimeout} function.
1331 * @todo Think about only allowing {@link CB_GraphicSprites.SPRITE_OBJECT} objects (in the "sprites" parameter) which are already in the {@link CB_GraphicSprites} (identify them by their ID), to avoid problems.
1332 */
1333CB_GraphicSprites.prototype.executeFunctionAll = CB_GraphicSprites.prototype.executeAll = CB_GraphicSprites.prototype.forEachSprite = CB_GraphicSprites.prototype.forEach = function(functionEach, orderedByZIndex, delayBetweenEach, sprites, returnSetTimeoutsArray, delayBetweenEachAffectsFirst, functionFinish)
1334{
1335 return CB_Arrays.executeFunctionAll(CB_isArray(sprites) ? sprites : this.getSprites(orderedByZIndex, []), functionEach, delayBetweenEach, returnSetTimeoutsArray, delayBetweenEachAffectsFirst, functionFinish);
1336}
1337
1338
1339/**
1340 * Alias for {@link CB_AudioFileSpritesPool#executeFunctionAllSubSprites}.
1341 * @function CB_AudioFileSpritesPool#executeAllSubSprites
1342 * @see {@link CB_AudioFileSpritesPool#executeFunctionAllSubSprites}
1343 */
1344 /**
1345 * Alias for {@link CB_AudioFileSpritesPool#executeFunctionAllSubSprites}.
1346 * @function CB_AudioFileSpritesPool#forEachSubSprite
1347 * @see {@link CB_AudioFileSpritesPool#executeFunctionAllSubSprites}
1348 */
1349 /**
1350 * Performs a desired action, using the provided function, on all the existing sub-sprites ({@link CB_GraphicSprites.SUBSPRITE_OBJECT} objects) from a given sprite ({@link CB_GraphicSprites.SPRITE_OBJECT} object). Calls the {@link CB_Arrays.executeFunctionAll} function internally and returns its returning value.
1351 * @function
1352 * @param {CB_Arrays.executeFunctionAll_ON_LOOP_CALLBACK} functionEach - Function that will be called for each sub-sprite ({@link CB_GraphicSprites.SUBSPRITE_OBJECT} object) from the given sprite ({@link CB_GraphicSprites.SPRITE_OBJECT} object). As the first parameter it receives the {@link CB_GraphicSprites.SUBSPRITE_OBJECT} object of the sub-sprites being looped, as the second parameter the position of this {@link CB_GraphicSprites.SUBSPRITE_OBJECT} object in the "subSprites" property of the sprite ({@link CB_GraphicSprites.SPRITE_OBJECT} object) provided (which is an array), the third parameter is the array being looped and the fourth parameter will be the "delayBetweenEach" being used, being "this" the {@link CB_GraphicSprites.SUBSPRITE_OBJECT} object itself.
1353 * @param {boolean} [orderedByZIndex=false] - If set to true, it will loop the sub-sprites sorted by their z-index (ascending order).
1354 * @param {number|CB_Arrays.executeFunctionAll_ON_LOOP_CALLBACK} [delayBetweenEach=0] - If a value greater than zero is used, it will be used as the delay desired between each call to the "functionEach" function (calling them using the [setTimeout]{@link https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/setTimeout} function internally). If not provided or the value is 0 (zero) or lower, each call to the "functionEach" function will be performed immediately one after the other. If a function is provided, it will be called with the same parameters as the "functionEach" function and its returning value will be used as the delay (executed every loop for each {@link CB_GraphicSprites.SUBSPRITE_OBJECT} object).
1355 * @param {CB_GraphicSprites.SPRITE_OBJECT} [sprite=CB_GraphicSprites#getCurrent()] - The {@link CB_GraphicSprites.SPRITE_OBJECT} object which contains the sprite and its sub-sprites. If not provided, it will use the {@link CB_GraphicSprites.SPRITE_OBJECT} object which the pointer (set in the {@link CB_GraphicSprites#pointer} property) is currently pointing to (using the returning value of the {@link CB_GraphicSprites#getCurrent} method internally).
1356 * @param {boolean} [returnSetTimeoutsArray=false] - Defines whether we want the method to return an integer or a numeric array with information of each [setTimeout]{@link https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/setTimeout} call. Returning an array with information of each [setTimeout]{@link https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/setTimeout} call is only useful when the [setTimeout]{@link https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/setTimeout} function is called internally, which happens when the "delayBetweenEach" parameter is greater than 0 (zero).
1357 * @param {boolean} [delayBetweenEachAffectsFirst=false] - If set to true, the desired delay (if any) will also affect the first call to the "functionEach" function.
1358 * @param {CB_Arrays.executeFunctionAll_ON_FINISH_CALLBACK} [functionFinish] - Function that will be called for when it has finished looping all the items. The first parameter will be the array which was looped, the second parameter will be the number of times that the "functionEach" callback was called (the most likely, matches the number of elements unless they are undefined or null), and the third parameter will be the maximum "delay" used, being "this" the array itself.
1359 * @returns {integer|array} If the "returnSetTimeoutsArray" parameter is set to false, it will return the number of calls to the "functionEach" function that were performed (which should be the same number as the existing {@link CB_GraphicSprites.SUBSPRITE_OBJECT} objects in the given {@link CB_GraphicSprites.SPRITE_OBJECT} object). Otherwise, if the "returnSetTimeoutsArray" is set to true, it will return a numeric array with a {@link CB_Arrays.executeFunctionAll_OBJECT} object for each {@link CB_GraphicSprites.SUBSPRITE_OBJECT}. The length of this array will also be the number of calls to the "functionEach" function that were performed. Note that if a value greater than 0 (zero) for the "delayBetweenEach" parameter has been provided, perhaps not all calls of the "functionEach" function will have been performed yet when exiting this method because of the asynchronous nature of the [setTimeout]{@link https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/setTimeout} function.
1360 * @todo Think about only allowing {@link CB_GraphicSprites.SPRITE_OBJECT} objects (in the "sprite" parameter) which are already in the {@link CB_GraphicSprites.SPRITE_OBJECT} (identify them by their ID), to avoid problems.
1361 */
1362CB_GraphicSprites.prototype.executeFunctionAllSubSprites = CB_GraphicSprites.prototype.executeAllSubSprites = CB_GraphicSprites.prototype.forEachSubSprite = function(functionEach, orderedByZIndex, delayBetweenEach, sprite, returnSetTimeoutsArray, delayBetweenEachAffectsFirst, functionFinish)
1363{
1364 return CB_Arrays.executeFunctionAll(this.getSubSprites(sprite, orderedByZIndex, []), functionEach, delayBetweenEach, returnSetTimeoutsArray, delayBetweenEachAffectsFirst, functionFinish);
1365}
1366
1367
1368/**
1369 * Alias for {@link CB_GraphicSprites#getPointerPrevious}.
1370 * @function CB_GraphicSprites#getPreviousPosition
1371 * @see {@link CB_GraphicSprites#getPointerPrevious}
1372 */
1373/**
1374 * Gets the previous position of the pointer. It belongs to an index of the {@link CB_GraphicSprites#spritesGroup.sprites} array where a {@link CB_GraphicSprites.SPRITE_OBJECT} object is placed (containing a sprite). Internally, it uses the {@link CB_GraphicSprites#pointerPrevious} property.
1375 * @function
1376 * @returns {integer} Returns the position where the pointer was previously pointing to. It belongs to an index of the {@link CB_GraphicSprites#spritesGroup.sprites} array where a {@link CB_GraphicSprites.SPRITE_OBJECT} object is placed (containing a sprite). If not found, returns -1 by default.
1377 */
1378CB_GraphicSprites.prototype.getPointerPrevious = CB_GraphicSprites.prototype.getPreviousPosition = function()
1379{
1380 return this.pointerPrevious === 0 || parseInt(this.pointerPrevious) &amp;&amp; this.pointerPrevious > 0 ? this.pointerPrevious : -1;
1381}
1382
1383
1384/**
1385 * Alias for {@link CB_GraphicSprites#getPointer}.
1386 * @function CB_GraphicSprites#getCurrentPosition
1387 * @see {@link CB_GraphicSprites#getPointer}
1388 */
1389/**
1390 * Gets the current position of the pointer. It belongs to an index of the {@link CB_GraphicSprites#spritesGroup.sprites} array where a {@link CB_GraphicSprites.SPRITE_OBJECT} object is placed (containing a sprite). Internally, it uses the {@link CB_GraphicSprites#pointer} property.
1391 * @function
1392 * @returns {integer} Returns the position where the pointer is currently pointing to. It belongs to an index of the {@link CB_GraphicSprites#spritesGroup.sprites} array where a {@link CB_GraphicSprites.SPRITE_OBJECT} object is placed (containing a sprite). If not found, returns zero (0) by default.
1393 */
1394CB_GraphicSprites.prototype.getPointer = CB_GraphicSprites.prototype.getCurrentPosition = function()
1395{
1396 return parseInt(this.pointer) &amp;&amp; this.pointer > 0 ? this.pointer : 0;
1397}
1398
1399
1400/**
1401 * Alias for {@link CB_GraphicSprites#setPointer}.
1402 * @function CB_GraphicSprites#setCurrentPosition
1403 * @see {@link CB_GraphicSprites#setPointer}
1404 */
1405/**
1406 * Sets the pointer to the desired position (if possible). The position should belong to an index of the {@link CB_GraphicSprites#spritesGroup.sprites} array where a {@link CB_GraphicSprites.SPRITE_OBJECT} object is placed (containing a sprite). Internally, it modifies the {@link CB_GraphicSprites#pointer} property (if possible). If the position was updated, it will also reset the {@link CB_GraphicSprites#time} property (setting the current time in milliseconds).
1407 * @function
1408 * @param {integer} [position=0|CB_GraphicSprites#spritesGroup.sprites.length-1|position%CB_GraphicSprites#spritesGroup.sprites.length] - The position that we want the pointer to use. The position should belong to an index of the {@link CB_GraphicSprites#spritesGroup.sprites} array where a {@link CB_GraphicSprites.SPRITE_OBJECT} object is placed (containing a sprite).
1409 * @param {boolean} [loop=false] - If set to false and the "position" given is greater than the current number of sprites, the "position" used will be the one which belongs to the last sprite. If set to false and the "position" given is lower than zero, the "position" used will be zero (the first position). Otherwise, if set to true and the "position" given is greater than the current number of sprites or lower than zero, it will modify the given "position" making it cycle (from the end to the beginning) treating always the "position" as a positive number. This parameter is ignored when the given "position" has not reached the limit.
1410 * @returns {integer} Returns the position where the pointer is currently pointing to. It belongs to an index of the {@link CB_GraphicSprites#spritesGroup.sprites} array where a {@link CB_GraphicSprites.SPRITE_OBJECT} object is placed (containing a sprite).
1411 */
1412CB_GraphicSprites.prototype.setPointer = CB_GraphicSprites.prototype.setCurrentPosition = function(position, loop)
1413{
1414 if (this.spritesGroup &amp;&amp; this.spritesGroup.sprites &amp;&amp; this.spritesGroup.sprites.length)
1415 {
1416 position = position || 0;
1417 if (loop)
1418 {
1419 if (position &lt; 0) { position = position * -1; } //Converts it to a positive number.
1420 position %= this.spritesGroup.sprites.length;
1421 }
1422 else if (position &lt; 0) { position = 0; }
1423 else if (position >= this.spritesGroup.sprites.length) { position = this.spritesGroup.sprites.length - 1; }
1424 if (this.pointer !== position) { this.pointerPrevious = this.pointer; this.pointer = position; this.setTime(undefined, true, true); } //Updates the pointer and "resets" the time.
1425 }
1426 return this.pointer || 0;
1427}
1428
1429
1430/**
1431 * Gets the sprite (a {@link CB_GraphicSprites.SPRITE_OBJECT} object) which was previously pointed (by the previous value of the pointer set in the {@link CB_GraphicSprites#pointer} property, whose value is now in the {@link CB_GraphicSprites#pointerPrevious} property).
1432 * @function
1433 * @returns {CB_GraphicSprites.SPRITE_OBJECT|null} Returns the {@link CB_GraphicSprites.SPRITE_OBJECT} object which was previously pointed by the pointer (by the previous value of the pointer set in the {@link CB_GraphicSprites#pointer} property, whose value is now in the {@link CB_GraphicSprites#pointerPrevious} property). Returns null if not found.
1434 */
1435CB_GraphicSprites.prototype.getPrevious = function()
1436{
1437 if (this.pointerPrevious === 0 || parseInt(this.pointerPrevious) &amp;&amp; this.pointerPrevious > 0) { return this.getSprite(this.pointerPrevious, null); }
1438 else { return null; }
1439}
1440
1441
1442/**
1443 * Alias for {@link CB_GraphicSprites#getCurrent}.
1444 * @function CB_GraphicSprites#now
1445 * @see {@link CB_GraphicSprites#getCurrent}
1446 */
1447/**
1448 * Alias for {@link CB_GraphicSprites#getCurrent}.
1449 * @function CB_GraphicSprites#current
1450 * @see {@link CB_GraphicSprites#getCurrent}
1451 */
1452/**
1453 * Gets the sprite (a {@link CB_GraphicSprites.SPRITE_OBJECT} object) which is being currently pointed (by the pointer set in the {@link CB_GraphicSprites#pointer} property).
1454 * @function
1455 * @returns {CB_GraphicSprites.SPRITE_OBJECT|null} Returns the {@link CB_GraphicSprites.SPRITE_OBJECT} object which is currently pointed by the pointer (set in the {@link CB_GraphicSprites#pointer} property). Returns null if not found.
1456 */
1457CB_GraphicSprites.prototype.getCurrent = CB_GraphicSprites.prototype.current = CB_GraphicSprites.prototype.now = function()
1458{
1459 return this.getSprite(this.getPointer(), null);
1460}
1461
1462
1463/**
1464 * Alias for {@link CB_GraphicSprites#setPrevious}.
1465 * @function CB_GraphicSprites#previous
1466 * @see {@link CB_GraphicSprites#setPrevious}
1467 */
1468/**
1469 * Makes the pointer to go back to the previous position (if possible) and returns the sprite located there (if any). The position should belong to an index of the {@link CB_GraphicSprites#spritesGroup.sprites} array where a {@link CB_GraphicSprites.SPRITE_OBJECT} object is placed (containing a sprite) and it will be returned if found. Internally, it modifies the {@link CB_GraphicSprites#pointer} property (if possible). If the position was updated, it will update also the {@link CB_GraphicSprites#time} property (setting the current time in milliseconds).
1470 * @function
1471 * @param {boolean} [loop=false] - If set to false and the previous position is lower than zero, it will return null. Otherwise, if set to true and the position is lower than zero, it will modify the position making it cycle (from the beginning to the end). This parameter is ignored when the position has not reached the limit.
1472 * @returns {CB_GraphicSprites.SPRITE_OBJECT|null} Makes it to point to the previous {@link CB_GraphicSprites.SPRITE_OBJECT} object (making it the current one) and returns it. Returns null if it cannot be found.
1473 */
1474CB_GraphicSprites.prototype.setPrevious = CB_GraphicSprites.prototype.previous = function(loop)
1475{
1476 var pointer = this.getPointer() - 1;
1477 if (pointer &lt; 0)
1478 {
1479 if (loop &amp;&amp; this.spritesGroup &amp;&amp; this.spritesGroup.sprites &amp;&amp; this.spritesGroup.sprites.length) { pointer = this.spritesGroup.sprites.length + pointer; }
1480 else { return null; }
1481 }
1482 var sprite = this.getSprite(pointer, null);
1483 if (sprite !== null &amp;&amp; this.pointer !== pointer) { this.pointerPrevious = this.pointer; this.pointer = pointer; this.setTime(undefined, true, true); } //Updates the pointer and "resets" the time.
1484 return sprite;
1485}
1486
1487
1488/**
1489 * Alias for {@link CB_GraphicSprites#setNext}.
1490 * @function CB_GraphicSprites#next
1491 * @see {@link CB_GraphicSprites#setNext}
1492 */
1493/**
1494 * Makes the pointer to advance to the next position (if possible) and returns the sprite located there (if any). The position should belong to an index of the {@link CB_GraphicSprites#spritesGroup.sprites} array where a {@link CB_GraphicSprites.SPRITE_OBJECT} object is placed (containing a sprite) and it will be returned if found. Internally, it modifies the {@link CB_GraphicSprites#pointer} property (if possible). If the position was updated, it will also update the {@link CB_GraphicSprites#time} property (setting the current time in milliseconds).
1495 * @function
1496 * @param {boolean} [loop=false] - If set to false and the next position is greater than the current number of sprites, it will return null. Otherwise, if set to true and the position is greater than the current number of sprites, it will modify the position making it cycle (from the end to the beginning). This parameter is ignored when the position has not reached the limit.
1497 * @returns {CB_GraphicSprites.SPRITE_OBJECT|null} Makes it to point to the next {@link CB_GraphicSprites.SPRITE_OBJECT} object (making it the current one) and returns it. Returns null if it cannot be found.
1498 */
1499CB_GraphicSprites.prototype.setNext = CB_GraphicSprites.prototype.next = function(loop)
1500{
1501 var pointer = this.getPointer() + 1;
1502 if (loop &amp;&amp; this.spritesGroup &amp;&amp; this.spritesGroup.sprites &amp;&amp; this.spritesGroup.sprites.length) { pointer %= this.spritesGroup.sprites.length; }
1503 var sprite = this.getSprite(pointer, null);
1504 if (sprite !== null &amp;&amp; this.pointer !== pointer) { this.pointerPrevious = this.pointer; this.pointer = pointer; this.setTime(undefined, true, true); } //Updates the pointer and "resets" the time.
1505 return sprite;
1506}
1507
1508
1509/**
1510 * Gets the z-index ("zIndex" property) of the sprites group object (and the {@CB_GraphicSprites} object itself).
1511 * @function
1512 * @param {*} [returnValueOnFail=undefined] - The value we want it to return in the case that no value is found. If not provided, undefined will be returned.
1513 * @returns {number} Returns the z-index ("zIndex") of the sprites group object (and the {@CB_GraphicSprites} object itself). If not found, returns the value of the {@link CB_GraphicSprites.ZINDEX_DEFAULT} property of evaluates to true or "returnValueOnFail" otherwise.
1514 */
1515CB_GraphicSprites.prototype.getZIndex = function(returnValueOnFail)
1516{
1517 return parseFloat(this.zIndex) || CB_GraphicSprites.ZINDEX_DEFAULT || returnValueOnFail;
1518}
1519
1520
1521/**
1522 * Sets the desired z-index ("zIndex" property) of the sprites group object (and the {@CB_GraphicSprites} object itself). If there is a {@link CB_GraphicSpritesScene} parent object (set in the {@link CB_GraphicSprites.parent} property), it will also call its {@link CB_GraphicSpritesScene#updateGraphicSpritesByZIndex} method internally.
1523 * @function
1524 * @param {number} [zIndex=parseFloat(zIndex)||CB_GraphicSprites.ZINDEX_DEFAULT||1] - The z-index value we want. It must be a number but never zero (0). If no valid number is given, it will use the value of the {@link CB_GraphicSprites.ZINDEX_DEFAULT} property of evaluates to true or 1 otherwise.
1525 * @returns {number} Returns the z-index ("zIndex") of the sprites group object (and the {@CB_GraphicSprites} object itself) after setting it (it could have been sanitized).
1526 */
1527CB_GraphicSprites.prototype.setZIndex = function(zIndex)
1528{
1529 this.zIndex = parseFloat(zIndex) || CB_GraphicSprites.ZINDEX_DEFAULT || 1;
1530 if (this.spritesGroup) { this.spritesGroup.zIndex = this.zIndex; }
1531
1532 //If there is a parent (CB_GraphicSpritesScene object), updates the array with its CB_GraphicSprites ordered by z-index:
1533 if (this.parent &amp;&amp; typeof(this.parent.updateGraphicSpritesByZIndex) === "function") { this.parent.updateGraphicSpritesByZIndex.call(this.parent); }
1534
1535 return this.zIndex;
1536}
1537
1538
1539/**
1540 * Gets the z-index ("zIndex" property) of a given sprite object.
1541 * @function
1542 * @param {CB_GraphicSprites.SPRITE_OBJECT} [sprite=CB_GraphicSprites#getCurrent()] - The {@link CB_GraphicSprites.SPRITE_OBJECT} object which contains the sprite. If not provided, it will use the {@link CB_GraphicSprites.SPRITE_OBJECT} object which the pointer (set in the {@link CB_GraphicSprites#pointer} property) is currently pointing to (using the returning value of the {@link CB_GraphicSprites#getCurrent} method internally).
1543 * @param {*} [returnValueOnFail=undefined] - The value we want it to return in the case that no value is found. If not provided, undefined will be returned.
1544 * @returns {number} Returns the z-index ("zIndex") of the given sprite. If not found, returns the value of the {@link CB_GraphicSprites.ZINDEX_DEFAULT} property of evaluates to true or "returnValueOnFail" otherwise.
1545 */
1546CB_GraphicSprites.prototype.getZIndexSprite = function(sprite, returnValueOnFail)
1547{
1548 sprite = sprite || this.getCurrent();
1549 return sprite &amp;&amp; parseFloat(sprite.zIndex) ? sprite.zIndex : CB_GraphicSprites.ZINDEX_DEFAULT || returnValueOnFail;
1550}
1551
1552
1553/**
1554 * Sets the desired z-index ("zIndex") of the given sprite object. Calls the {@link CB_GraphicSprites#updateSpritesByZIndex} method internally.
1555 * @function
1556 * @param {CB_GraphicSprites.SPRITE_OBJECT} [sprite=CB_GraphicSprites#getCurrent()] - The {@link CB_GraphicSprites.SPRITE_OBJECT} object which contains the sprite. If not provided, it will use the {@link CB_GraphicSprites.SPRITE_OBJECT} object which the pointer (set in the {@link CB_GraphicSprites#pointer} property) is currently pointing to (using the returning value of the {@link CB_GraphicSprites#getCurrent} method internally).
1557 * @param {number} [zIndex=parseFloat(zIndex)||CB_GraphicSprites.ZINDEX_DEFAULT||1] - The z-index value we want. It must be a number but never zero (0). If no valid number is given, it will use the value of the {@link CB_GraphicSprites.ZINDEX_DEFAULT} property of evaluates to true or 1 otherwise.
1558 * @returns {number} Returns the z-index ("zIndex") of the given sprite after setting it (it could have been sanitized).
1559 */
1560CB_GraphicSprites.prototype.setZIndexSprite = function(sprite, zIndex)
1561{
1562 sprite = sprite || this.getCurrent();
1563 if (sprite &amp;&amp; sprite.parent)
1564 {
1565 sprite.zIndex = parseFloat(zIndex) || CB_GraphicSprites.ZINDEX_DEFAULT || 1;
1566
1567 //Updates the array with the sprites ordered by z-index:
1568 this.updateSpritesByZIndex();
1569 }
1570 return sprite.zIndex;
1571}
1572
1573
1574/**
1575 * Gets the z-index ("zIndex" property) of a given sub-sprite object.
1576 * @function
1577 * @param {CB_GraphicSprites.SUBSPRITE_OBJECT} subSprite - The {@link CB_GraphicSprites.SUBSPRITE_OBJECT} object which contains the sub-sprite.
1578 * @param {*} [returnValueOnFail=undefined] - The value we want it to return in the case that no value is found. If not provided, undefined will be returned.
1579 * @returns {number} Returns the z-index ("zIndex") of the given sub-sprite. If not found, returns the value of the {@link CB_GraphicSprites.ZINDEX_DEFAULT} property of evaluates to true or "returnValueOnFail" otherwise.
1580 */
1581CB_GraphicSprites.prototype.getZIndexSubSprite = function(subSprite, returnValueOnFail)
1582{
1583 return subSprite &amp;&amp; parseFloat(subSprite.zIndex) ? subSprite.zIndex : CB_GraphicSprites.ZINDEX_DEFAULT || returnValueOnFail;
1584}
1585
1586
1587/**
1588 * Sets the desired z-index ("zIndex") of the given sub-sprite object. Calls the {@link CB_GraphicSprites#updateSubSpritesByZIndex} method internally.
1589 * @function
1590 * @param {CB_GraphicSprites.SUBSPRITE_OBJECT} sprite - The {@link CB_GraphicSprites.SUBSPRITE_OBJECT} object which contains the sub-sprite.
1591 * @param {number} [zIndex=parseFloat(zIndex)||CB_GraphicSprites.ZINDEX_DEFAULT||0] - The z-index value we want. It must be a number but never zero (0). If no valid number is given, it will use the value of the {@link CB_GraphicSprites.ZINDEX_DEFAULT} property of evaluates to true or 1 otherwise.
1592 * @returns {number} Returns the z-index ("zIndex") of the given sub-sprite after setting it (it could have been sanitized).
1593 */
1594CB_GraphicSprites.prototype.setZIndexSubSprite = function(subSprite, zIndex)
1595{
1596 if (subSprite &amp;&amp; subSprite.parent)
1597 {
1598 subSprite.zIndex = parseFloat(zIndex) || CB_GraphicSprites.ZINDEX_DEFAULT || 1;
1599
1600 //Updates the array with the sub-sprites ordered by z-index:
1601 this.updateSubSpritesByZIndex(subSprite.parent);
1602 }
1603 return subSprite.zIndex;
1604}
1605
1606
1607/**
1608 * Tells whether the sprites group object (and the {@CB_GraphicSprites} object itself) is disabled or not. Internally, it checks the "{@link CB_GraphicSprites.spritesGroup}.disabled" property.
1609 * @function
1610 * @returns {boolean} Returns whether the sprites group object (and the {@link CB_GraphicSprites} object itself) is disabled or not.
1611 */
1612CB_GraphicSprites.prototype.isDisabled = function()
1613{
1614 return !!this.getSpritesGroup({}).disabled;
1615}
1616
1617
1618/**
1619 * Sets whether the sprites group object (and the {@CB_GraphicSprites} object itself) is disabled or enabled. Internally, it edits the "{@link CB_GraphicSprites.spritesGroup}.disabled" property.
1620 * @function
1621 * @param {boolean} [disabled=false] - Set to true to disable it or false to enable it.
1622 * @param {boolean} [affectChildren=disabled] - If this parameter is set to true, it will also modify the "disabled" property of all the sprites and their sub-sprites. By default, it is false if the "disabled" parameter is set to false or it is true otherwise.
1623 */
1624CB_GraphicSprites.prototype.setDisabled = function(disabled, affectChildren)
1625{
1626 disabled = !!disabled;
1627 if (typeof(affectChildren) === "undefined" || affectChildren === null) { affectChildren = disabled; }
1628 this.spritesGroup = this.spritesGroup || {};
1629 this.spritesGroup.disabled = disabled;
1630 if (affectChildren)
1631 {
1632 this.executeFunctionAll(function() { if (this.setDisabled &amp;&amp; typeof(this.setDisabled) === "function") { this.setDisabled(disabled, true, false, false); } });
1633 }
1634}
1635
1636
1637
1638/**
1639 * Tells whether the given sprite is disabled or not. Internally, it checks its "disabled" property and also the "{@link CB_GraphicSprites.spritesGroup}.disabled" property (calling the {@link CB_GraphicSprites#isDisabled} method internally). A sprite is considered disabled if its sprites group parent is also disabled.
1640 * @function
1641 * @param {CB_GraphicSprites.SPRITE_OBJECT} [sprite=CB_GraphicSprites#getCurrent()] - The {@link CB_GraphicSprites.SPRITE_OBJECT} object which contains the sprite. If not provided, it will use the {@link CB_GraphicSprites.SPRITE_OBJECT} object which the pointer (set in the {@link CB_GraphicSprites#pointer} property) is currently pointing to (using the returning value of the {@link CB_GraphicSprites#getCurrent} method internally).
1642 * @returns {boolean} Returns whether the sprite is disabled or not. A sprite is considered disabled if its sprites group parent is also disabled.
1643 */
1644CB_GraphicSprites.prototype.isDisabledSprite = function(sprite)
1645{
1646 sprite = sprite || this.getCurrent() || {};
1647 return !!sprite.disabled || this.isDisabled();
1648}
1649
1650
1651/**
1652 * Sets a given sprite disabled or enabled. Internally, it edits its "disabled" property.
1653 * @function
1654 * @param {CB_GraphicSprites.SPRITE_OBJECT} [sprite=CB_GraphicSprites#getCurrent()] - The {@link CB_GraphicSprites.SPRITE_OBJECT} object which contains the sprite. If not provided, it will use the {@link CB_GraphicSprites.SPRITE_OBJECT} object which the pointer (set in the {@link CB_GraphicSprites#pointer} property) is currently pointing to (using the returning value of the {@link CB_GraphicSprites#getCurrent} method internally).
1655 * @param {boolean} [disabled=false] - Set to true to disable it or false to enable it.
1656 * @param {boolean} [affectSubSprites=disabled] - If this parameter is set to true, it will also modify the "disabled" property of all the sub-sprites of the given sprite. This parameter will be ignored if the "affectParent" parameter is set to true (as all existing sprites and sub-sprites in the {@link CB_GraphicSprites} object will be affected anyway). By default, it is false if the "disabled" parameter is set to false or it is true otherwise.
1657 * @param {boolean} [affectParent=affectParentChildren|!disabled] - If this parameter is set to true, it will also modify the "disabled" property of the sprites group object (which is considered the status of the whole {@CB_GraphicSprites} object). By default, it is true if either the "affectParentChildren" parameter is set to true or the "disabled" parameter is set to false and it is false otherwise.
1658 * @param {boolean} [affectParentChildren=!disabled] - Defines whether to also affect the sprites and sub-sprites of the sprites group object (which is considered the status of the whole {@CB_GraphicSprites} object) or not. If it is set to true and the "affectParent" is also set to true, it will also modify the "disabled" property of all the existing sprites and sub-sprites in the {@link CB_GraphicSprites} object. This parameter is ignored if the "affectParent" parameter is set to false. By default, it is false if the "disabled" parameter is set to true or it is false otherwise.
1659 */
1660CB_GraphicSprites.prototype.setDisabledSprite = function(sprite, disabled, affectSubSprites, affectParent, affectParentChildren)
1661{
1662 disabled = !!disabled;
1663 if (typeof(affectParentChildren) === "undefined" || affectParentChildren === null) { affectParentChildren = !disabled; }
1664 if (typeof(affectParent) === "undefined" || affectParent === null) { affectParent = affectParentChildren || !disabled; }
1665 sprite = sprite || this.getCurrent();
1666
1667 if (sprite)
1668 {
1669 sprite.disabled = disabled;
1670 if (typeof(affectSubSprites) === "undefined" || affectSubSprites === null) { affectSubSprites = disabled; }
1671 if (affectSubSprites)
1672 {
1673 if (typeof(sprite.executeFunctionAll) === "function")
1674 {
1675 sprite.executeFunctionAll(function() { if (this.setDisabled &amp;&amp; typeof(this.setDisabled) === "function") { this.setDisabled(disabled, false, false); } });
1676 }
1677 }
1678
1679 if (affectParent &amp;&amp; sprite &amp;&amp; sprite.parent)
1680 {
1681 return this.setDisabled(disabled, affectParentChildren); //Disables/enables the sprites group parent (and also its children).
1682 }
1683 }
1684}
1685
1686
1687/**
1688 * Tells whether the given sub-sprite is disabled or not. Internally, it checks its "disabled" property and also whether its sprite parent is disabled (calling the {@link CB_GraphicSprites#isDisabledSprite} method internally, for its sprite parent). A sub-sprite is considered disabled if its sprite parent is disabled (a sprite is considered disabled if its sprites group parent is also disabled).
1689 * @function
1690 * @param {CB_GraphicSprites.SUBSPRITE_OBJECT} subSprite - The {@link CB_GraphicSprites.SUBSPRITE_OBJECT} object which contains the sub-sprite.
1691 * @returns {boolean} Returns whether the sub-sprite is disabled or not. A sub-sprite is considered disabled if its sprite parent is disabled (a sprite is considered disabled if its sprites group parent is also disabled).
1692 */
1693CB_GraphicSprites.prototype.isDisabledSubSprite = function(subSprite)
1694{
1695 subSprite = subSprite || {};
1696 return !!subSprite.disabled || this.isDisabledSprite(subSprite.parent || {});
1697}
1698
1699
1700/**
1701 * Sets a given sub-sprite disabled or enabled. Internally, it edits its "disabled" property.
1702 * @function
1703 * @param {CB_GraphicSprites.SUBSPRITE_OBJECT} subSprite - The {@link CB_GraphicSprites.SUBSPRITE_OBJECT} object which contains the sub-sprite.
1704 * @param {boolean} [disabled=false] - Set to true to disable it or false to enable it.
1705 * @param {boolean} [affectParents=affectParentsChildren|!disabled] - If this parameter is set to true, it will also modify the "disabled" property of the sprite parent and of the sprites group object (which is considered the status of the whole {@CB_GraphicSprites} object). By default, it is true if either the "affectParentChildren" parameter is set to true or the "disabled" parameter is set to false and it is false otherwise.
1706 * @param {boolean} [affectParentsChildren=!disabled] - Defines whether to also affect the sprites and sub-sprites of the sprite parent and its sprites group object (which is considered the status of the whole {@CB_GraphicSprites} object) or not. If it is set to true and the "affectParents" is also set to true, it will also modify the "disabled" property of all the existing sprites and sub-sprites in the {@link CB_GraphicSprites} object. This parameter is ignored if the "affectParents" parameter is set to false. By default, it is false if the "disabled" parameter is set to true or it is false otherwise.
1707 */
1708CB_GraphicSprites.prototype.setDisabledSubSprite = function(subSprite, disabled, affectParents, affectParentsChildren)
1709{
1710 disabled = !!disabled;
1711 if (typeof(affectParentsChildren) === "undefined" || affectParentsChildren === null) { affectParentsChildren = !disabled; }
1712 if (typeof(affectParents) === "undefined" || affectParents === null) { affectParents = affectParentsChildren || !disabled; }
1713 if (subSprite)
1714 {
1715 subSprite.disabled = disabled;
1716 if (affectParents &amp;&amp; subSprite.parent)
1717 {
1718 return this.setDisabledSprite(subSprite.parent, disabled, affectParentsChildren, true, affectParentsChildren);
1719 }
1720 }
1721}
1722
1723
1724/**
1725 * Sets (updates) the time in milliseconds when the current sprite or a sub-sprite started being pointed.
1726 * @function
1727 * @param {number} [time=CB_Device.getTiming()] - The time that we want to set, in milliseconds (time elapsed since the [time origin]{@link https://developer.mozilla.org/en-US/docs/Web/API/DOMHighResTimeStamp#The_time_origin} which can be obtained calling the {@link CB_Device.getTiming} function). It must be a positive number (or zero). If not provided, it will use the current time (by calling the {@link CB_Device.getTiming} function internally).
1728 * @param {boolean} [updateTimeCurrentSprite=false] - If set to true, it will also update the "time" property of the {@link CB_GraphicSprites.SPRITE_OBJECT} object which is currently pointed by the pointer (set in the {@link CB_GraphicSprites#pointer} property).
1729 * @param {boolean} [updateTimeCurrentSpriteSubSprites=false] - If set to true and the "updateTimeCurrentSprite" is set to true, it will also update the "time" property of the {@link CB_GraphicSprites.SUBSPRITE_OBJECT} objects that belong to the sprite which is currently pointed by the pointer (set in the {@link CB_GraphicSprites#pointer} property). This parameter is ignored if the "updateTimeCurrentSprite" parameter is set to false.
1730 * @returns {number} Returns the time in milliseconds when the current sprite or a sub-sprite started being pointed (time elapsed since the [time origin]{@link https://developer.mozilla.org/en-US/docs/Web/API/DOMHighResTimeStamp#The_time_origin} which can be obtained calling the {@link CB_Device.getTiming} function).
1731 */
1732CB_GraphicSprites.prototype.setTime = function(time, updateTimeCurrentSprite, updateTimeCurrentSpriteSubSprites)
1733{
1734 time = parseFloat(time);
1735 time = !isNaN(time) &amp;&amp; time >= 0 ? time : CB_Device.getTiming();
1736 this.time = time;
1737 if (updateTimeCurrentSprite)
1738 {
1739 var sprite = this.getSprite(this.getPointer(), null);
1740 if (sprite !== null)
1741 {
1742 sprite.time = time;
1743 if (updateTimeCurrentSpriteSubSprites)
1744 {
1745 sprite.forEach(function() { this.time = time; });
1746 }
1747 }
1748 }
1749 return this.time;
1750}
1751
1752
1753/**
1754 * Gets the time in milliseconds when the current sprite or a sub-sprite started being pointed (time elapsed since the [time origin]{@link https://developer.mozilla.org/en-US/docs/Web/API/DOMHighResTimeStamp#The_time_origin} which was obtained calling the {@link CB_Device.getTiming} function internally).
1755 * @function
1756 * @param {*} [returnValueOnFail=undefined] - The value we want it to return in the case that no value is found. If not provided, undefined will be returned.
1757 * @param {boolean} [parentTimeFallback=false] - If the "time" property of "this" is not found, it will try to get the "time" property of "this.time" before returning "returnValueOnFail".
1758 * @returns {number} Returns the time in milliseconds when the current sprite or a sub-sprite started being pointed (time elapsed since the [time origin]{@link https://developer.mozilla.org/en-US/docs/Web/API/DOMHighResTimeStamp#The_time_origin} which was obtained calling the {@link CB_Device.getTiming} function internally). If it could not be found, it will return "returnValueOnFail".
1759 */
1760CB_GraphicSprites.prototype.getTime = function(returnValueOnFail, parentTimeFallback)
1761{
1762 if (parentTimeFallback) { returnValueOnFail = this.parent.time || returnValueOnFail; }
1763 return this.time || returnValueOnFail;
1764}
1765
1766
1767/**
1768 * Tells how many milliseconds elapsed since the current sprite or a sub-sprite was or will be pointed (checking the {@link CB_GraphicSprites#time} property), comparing with the time given in milliseconds (time elapsed since the [time origin]{@link https://developer.mozilla.org/en-US/docs/Web/API/DOMHighResTimeStamp#The_time_origin} which can be obtained calling the {@link CB_Device.getTiming} function) or with the current one if none is given.
1769 * @function
1770 * @param {number} [timeToCompare=CB_Device.getTiming()] - The time (time elapsed since the [time origin]{@link https://developer.mozilla.org/en-US/docs/Web/API/DOMHighResTimeStamp#The_time_origin} which can obtained calling the {@link CB_Device.getTiming} function) that we want to compare to (normally, it will be a newer time than the one stored in the {@link CB_GraphicSprites#time} property). It must be a positive number (or zero). If not provided, it will use the current time (by calling the {@link CB_Device.getTiming} function internally).
1771 * @param {boolean} [parentTimeFallback=false] - If the "time" property of "this" is not found, it will try to get the "time" property of "this.time" before using "returnValueOnFail".
1772 * @returns {number} Returns how many milliseconds elapsed since the current sprite or a sub-sprite was or will be pointed, comparing with the time given (in milliseconds) or with the current one if none was given. This is just the given "timeToCompare" minus the returning value of calling the {@link CB_GraphicSprites#getTime} method.
1773 */
1774CB_GraphicSprites.prototype.getTimeElapsed = function(timeToCompare, parentTimeFallback)
1775{
1776 timeToCompare = parseFloat(timeToCompare);
1777 timeToCompare = !isNaN(timeToCompare) &amp;&amp; timeToCompare >= 0 ? timeToCompare : CB_Device.getTiming();
1778 return timeToCompare - this.getTime(timeToCompare, parentTimeFallback);
1779}
1780
1781
1782/**
1783 * Sets the desired value of a given property name to the {@link CB_GraphicSprites.SPRITES_OBJECT} object as well to its children elements ({@link CB_GraphicSprites.SPRITE_OBJECT} and {@link CB_GraphicSprites.SUBSPRITE_OBJECT} objects).
1784 * @function
1785 * @param {number} propertyName - The name of the property we want to affect.
1786 * @param {*} [value=undefined] - The value desired for the given property.
1787 * @param {boolean} [onlyCurrent=false] - If set to true, it will only affect the current sprite and its sub-sprites (and also the {@link CB_GraphicSprites.SPRITES_OBJECT} object).
1788 * @returns {integer} Returns the number of elements affected (counting the {@link CB_GraphicSprites.SPRITES_OBJECT} object).
1789 */
1790CB_GraphicSprites.prototype.setPropertyCascade = function(propertyName, value, onlyCurrent)
1791{
1792 if (!propertyName) { return; }
1793
1794 if (this.spritesGroup)
1795 {
1796 this.spritesGroup[propertyName] = value;
1797 }
1798 else
1799 {
1800 this[propertyName] = value;
1801 }
1802
1803 var affected = 1;
1804
1805 if (onlyCurrent)
1806 {
1807 var currentSprite = this.getCurrent();
1808 if (currentSprite !== null)
1809 {
1810 currentSprite[propertyName] = value;
1811 affected++;
1812 currentSprite.forEach(function(subSprite) { subSprite[propertyName] = value; affected++; });
1813 }
1814 }
1815 else
1816 {
1817 this.forEach
1818 (
1819 function(element)
1820 {
1821 element[propertyName] = value;
1822 affected++;
1823 if (typeof(element.forEach) === "function")
1824 {
1825 element.forEach(function(subElement) { subElement[propertyName] = value; affected++; });
1826 }
1827 }
1828
1829 );
1830 }
1831
1832 return affected;
1833}
1834
1835
1836/**
1837 * Gets a new copy of this object with the same attributes (all sub-objects will be a copy, they will not the same reference).
1838 * @function
1839 * @param {boolean} [avoidCopyingPointer=false] - If set to true, it will not copy the {@link CB_GraphicSprites#pointer} property of the object.
1840 * @param {boolean} [avoidCopyingTimes=false] - If set to true, it will not copy neither the {@link CB_GraphicSprites#time} property property of the object nor the "time" property of each of its sprites ({@link CB_GraphicSprites.SPRITE_OBJECT} objects).
1841 * @param {boolean} [clearReferences=false] - If set to true, it will not copy neither the "container" nor the "parent" nor the "data.that" nor the "data.getThis" properties of any element. Useful to be able to stringify the object preventing the "TypeError: cyclic object value" error. When set to true, calls the {@link CB_GraphicSprites.clearReferences} function internally. If set to true and the "filterProperties" parameter is also set to true, the {@link CB_GraphicSprites.filterProperties} will always be called before calling the {@link CB_GraphicSprites.clearReferences} function.
1842 * @param {boolean} [filterProperties=false] - If set to true, it will call the {@link CB_GraphicSprites.filterProperties} function internally to filter the properties that we do not want to keep (using the given "propertiesToKeepObject" as the parameter to call it). When set to true, calls the {@link CB_GraphicSprites.filterProperties} function internally. If set to true and the "clearReferences" parameter is also set to true, the {@link CB_GraphicSprites.filterProperties} will always be called before calling the {@link CB_GraphicSprites.clearReferences} function.
1843 * @param {CB_GraphicSprites.filterProperties_propertiesToKeepObject_TYPE} [propertiesToKeepObject=CB_GraphicSprites.filterProperties_DEFAULT_PROPERTIES] - The object with the properties that we want to keep. Only used when the "filterProperties" parameter is set to true, as the "propertiesToKeepObject" when calling the {@link CB_GraphicSprites.filterProperties} function internally.
1844 * @returns {CB_GraphicSprites} Returns a copy of this object with the same attributes (all sub-objects will be a copy, not the same reference).
1845 */
1846CB_GraphicSprites.prototype.getCopy = function(avoidCopyingPointer, avoidCopyingTimes, clearReferences, filterProperties, propertiesToKeepObject)
1847{
1848 var spritesGroupCopy = CB_copyObject(this.spritesGroup);
1849 var newCopy = new CB_GraphicSprites(spritesGroupCopy, false);
1850
1851 //If desired, sets the same pointer:
1852 if (!avoidCopyingPointer) { newCopy.pointer = this.pointer; newCopy.pointerPrevious = this.pointerPrevious; }
1853
1854 //If desired, sets the same times:
1855 if (!avoidCopyingTimes)
1856 {
1857 newCopy.time = this.time;
1858 }
1859
1860 CB_GraphicSprites._copyNeededProperties(newCopy, this) //Copies the needed properties from the original element.
1861 CB_GraphicSprites._copyNeededProperties(newCopy.spritesGroup, this.spritesGroup) //Copies the needed properties from the original element.
1862
1863 this.forEach
1864 (
1865 function(sprite, index)
1866 {
1867 //If desired, sets the same times:
1868 if (!avoidCopyingTimes) { newCopy.get(index).time = this.time; }
1869
1870 CB_GraphicSprites._copyNeededProperties(newCopy.get(index), sprite) //Copies the needed properties from the original element.
1871
1872 sprite.forEach
1873 (
1874 function(subSprite, subSpriteIndex)
1875 {
1876 CB_GraphicSprites._copyNeededProperties(sprite.get(index).get(subSpriteIndex), subSprite) //Copies the needed properties from the original element.
1877
1878 //If desired, sets the same times:
1879 if (!avoidCopyingTimes) { sprite.get(subSpriteIndex).time = this.time; }
1880 }
1881 );
1882 }
1883 );
1884
1885 //Sets the same parent and positions:
1886 newCopy.parent = this.parent;
1887 newCopy.position = this.position;
1888 newCopy.positionByZIndex = this.positionByZIndex;
1889
1890 //If we want to, filters the properties keeping just the desired ones:
1891 if (filterProperties) { newCopy = CB_GraphicSprites.filterProperties(newCopy, propertiesToKeepObject); }
1892
1893 //If we want to, clears the references:
1894 if (clearReferences) { CB_GraphicSprites.clearReferences(newCopy); }
1895
1896 return newCopy;
1897}
1898
1899
1900CB_GraphicSprites._copyNeededPropertiesData =
1901{
1902 spritesScene: ["id"],
1903 spritesGroups: ["id", "byReference_DEFAULT", "src", "srcType", "srcLeft", "left", "srcTop", "top", "srcWidth", "width", "srcHeight", "height", "zIndex"],
1904 sprites: ["id", "byReference_DEFAULT", "zIndex", "pointer", "pointerPrevious", "pointer", "pointerPrevious", "position", "positionByZIndex", "_attributes"],
1905 spritesGroup: ["id", "byReference_DEFAULT", "src", "srcType", "srcLeft", "left", "srcTop", "top", "srcWidth", "width", "srcHeight", "height", "zIndex", "disabled"],
1906 sprite: ["id", "byReference", "src", "srcType", "srcLeft", "left", "srcTop", "top", "srcWidth", "width", "srcHeight", "height", "zIndex", "disabled", "position", "positionByZIndex", "_timeDisappeared", "_usingRelativePosition", "_clearPreviousFirstPerformed", "_widthOriginal", "_heightOriginal", "_leftOriginal", "_topOriginal", "_attributes"],
1907 subSprite: ["id", "byReference", "time", "src", "srcType", "srcLeft", "left", "srcTop", "top", "srcWidth", "width", "srcHeight", "height", "zIndex", "disabled", "position", "positionByZIndex", "_timeDisappeared", "_usingRelativePosition", "_attributes"]
1908};
1909CB_GraphicSprites._copyNeededProperties = function(element, elementOriginal)
1910{
1911 if (!element.type || element.type !== elementOriginal.type) { return; }
1912 if (!CB_isArray(CB_GraphicSprites._copyNeededPropertiesData[element.type])) { return; }
1913
1914 for (var x = CB_GraphicSprites._copyNeededPropertiesData[element.type].length; x >= 0; x--)
1915 {
1916 propertyName = CB_GraphicSprites._copyNeededPropertiesData[element.type][x];
1917 element[propertyName] = elementOriginal[propertyName];
1918 }
1919
1920 return element;
1921}
1922
1923
1924/**
1925 * Clears the "container", the "parent" and the "data.that" properties (sets to null) of the given object and its sub-objects (works recursively, internally).
1926 * @function
1927 * @param {*} element - The object whose properties we want to clear. It can be different kinds ({@link CB_GraphicSpritesScene}, {@link CB_GraphicSpritesScene.SPRITES_GROUPS_OBJECT}, {@link CB_GraphicSprites}, {@link CB_GraphicSprites.SPRITES_OBJECT}, {@link CB_GraphicSprites.SPRITE_OBJECT}, {@link CB_GraphicSprites.SUBSPRITE_OBJECT}, etc.).
1928 * @returns {*} Returns the same object with the the "container", the "parent", "data.that" and the "data.getThis" properties cleared (set to null), if possible.
1929 */
1930CB_GraphicSprites.clearReferences = function(element)
1931{
1932 if (typeof(element) !== "object" || element === null) { return element; }
1933 if (typeof(element.forEach) === "function")
1934 {
1935 element.forEach.call
1936 (
1937 element,
1938 function(subElement)
1939 {
1940 CB_GraphicSprites.clearReferences(subElement);
1941 }
1942 );
1943 }
1944 if (element.container) { element.container = null; }
1945 if (element.parent) { element.container = null; }
1946 if (element.data)
1947 {
1948 if (element.data.that) { element.data.that = null; }
1949 if (element.data.getThis) { element.data.getThis = null; }
1950 }
1951 return element;
1952}
1953
1954
1955/**
1956 * Object used to know what properties keep when calling the {@link CB_GraphicSprites.filterProperties} function (type used for its "propertiesToKeepObject" parameter). Its properties must have the name that matches the value returned by the "type" property of each element, being their value an array of strings with the name of the properties we want to keep. The property names which start with a "_" symbol will not considered inherited from the element's parent and will always be copied. The other properties (which do not start with the "_" symbol) will only be copied when the element contains a value which is different from the same property of its parent.
1957 * @memberof CB_GraphicSprites
1958 * @typedef {Object} CB_GraphicSprites.filterProperties_propertiesToKeepObject_TYPE
1959 * @property {array} [spritesScene] Array of strings with the name of the properties to keep for the {@link CB_GraphicSpritesScene} objects. If no provided, no properties will be kept for this kind of element.
1960 * @property {array} [spritesGroups] Array of strings with the name of the properties to keep for the {@link CB_GraphicSpritesScene.SPRITES_GROUPS_OBJECT} objects. If no provided, no properties will be kept for this kind of element.
1961 * @property {array} [sprites] Array of strings with the name of the properties to keep for the {@link CB_GraphicSprites} objects. If no provided, no properties will be kept for this kind of element.
1962 * @property {array} [spritesGroup] Array of strings with the name of the properties to keep for the {@link CB_GraphicSprites.SPRITES_OBJECT} objects. If no provided, no properties will be kept for this kind of element.
1963 * @property {array} [sprite] Array of strings with the name of the properties to keep for the {@link CB_GraphicSprites.SPRITE_OBJECT} objects. If no provided, no properties will be kept for this kind of element.
1964 * @property {array} [subSprite] Array of strings with the name of the properties to keep for the {@link CB_GraphicSprites.SUBSPRITE_OBJECT} objects. If no provided, no properties will be kept for this kind of element.
1965 */
1966
1967 /**
1968 * Object used as the default value for the "propertiesToKeepObject" parameter if not provided when calling the {@link CB_GraphicSprites.filterProperties} function.
1969 * @constant
1970 * @type {CB_GraphicSprites.filterProperties_propertiesToKeepObject_TYPE}
1971 * @default
1972 */
1973CB_GraphicSprites.filterProperties_DEFAULT_PROPERTIES =
1974{
1975 spritesScene: ["id", "spritesGroups"],
1976 spritesGroups: ["id", "byReference_DEFAULT", "src", "srcType", "srcLeft", "left", "srcTop", "top", "srcWidth", "width", "srcHeight", "height", "zIndex", "data", "spritesGroups", "items"],
1977 sprites: ["id", "byReference_DEFAULT", "spritesGroup", "zIndex", "pointer", "pointerPrevious", "time", "pointer", "pointerPrevious", "position", "positionByZIndex", "_attributes"],
1978 spritesGroup: ["id", "byReference_DEFAULT", "src", "srcType", "srcLeft", "left", "srcTop", "top", "srcWidth", "width", "srcHeight", "height", "zIndex", "data", "disabled", "sprites"],
1979 sprite: ["id", "byReference", "time", "src", "srcType", "srcLeft", "left", "srcTop", "top", "srcWidth", "width", "srcHeight", "height", "zIndex", "data", "disabled", "position", "positionByZIndex", "subSprites", "_timeDisappeared", "_usingRelativePosition", "_clearPreviousFirstPerformed", "_widthOriginal", "_heightOriginal", "_leftOriginal", "_topOriginal", "_attributes"],
1980 subSprite: ["id", "byReference", "time", "src", "srcType", "srcLeft", "left", "srcTop", "top", "srcWidth", "width", "srcHeight", "height", "zIndex", "data", "disabled", "position", "positionByZIndex", "_timeDisappeared", "_usingRelativePosition", "_attributes"]
1981};
1982
1983//Object to detect type of elements in an array according to the property name they belong to (which contains the array):
1984CB_GraphicSprites.filterProperties_types =
1985{
1986 "spritesGroups": "spritesGroup",
1987 "items": "sprites",
1988 "sprites": "sprite",
1989 "subSprites": "subSprite"
1990};
1991
1992/**
1993 * Gets a new object with the properties filtered of a given element and its sub-elements, keeping only the ones that are in the given "propertiesToKeepObject" (works recursively, internally).
1994 * @function
1995 * @param {*} element - The object whose properties we want to clear. It can be different kinds ({@link CB_GraphicSpritesScene}, {@link CB_GraphicSpritesScene.SPRITES_GROUPS_OBJECT}, {@link CB_GraphicSprites}, {@link CB_GraphicSprites.SPRITES_OBJECT}, {@link CB_GraphicSprites.SPRITE_OBJECT}, {@link CB_GraphicSprites.SUBSPRITE_OBJECT}, etc.).
1996 * @param {CB_GraphicSprites.filterProperties_propertiesToKeepObject_TYPE} [propertiesToKeepObject=CB_GraphicSprites.filterProperties_DEFAULT_PROPERTIES] - The object with the properties that we want to keep.
1997 * @returns {*} Returns a new object with the properties filtered of a given element and its sub-elements, keeping only the ones that are in the given "propertiesToKeepObject". If no valid "element" is provided, returns null.
1998 * @todo Implement a boolean property and when it is true it will not keep the properties whose values are the default ones (for example, if "byReference" property is false it will not be kept as it is its default value). So the output can be reduced this way.
1999 */
2000CB_GraphicSprites.filterProperties = function(element, propertiesToKeepObject)
2001{
2002 if (typeof(element) !== "object" || element === null) { return null; }
2003
2004 propertiesToKeepObject = (typeof(propertiesToKeepObject) === "object" &amp;&amp; propertiesToKeepObject !== null) ? propertiesToKeepObject : CB_GraphicSprites.filterProperties_DEFAULT_PROPERTIES;
2005
2006 if (element.type === "spritesGroup") { element.isSpritesGroup = true; }
2007 else if (element.type === "sprites") { element.isSprites = true; }
2008 else if (element.type === "sprite") { element.isSprite = true; }
2009 else if (element.type === "subSprite") { element.isSubSprite = true; }
2010
2011 var newObject = {};
2012
2013 for (var propertyName in element)
2014 {
2015 if (propertiesToKeepObject[element.type] &amp;&amp; CB_Arrays.indexOf(propertiesToKeepObject[element.type], propertyName) !== -1)
2016 {
2017 //If the property starts with "_", or there is no parent or the value of the property of the parent is different from the value of the current element, copies the value:
2018 if (propertyName.charAt(0) === "_" || !element.parent || element._avoidParent || element.parent &amp;&amp; element.parent[propertyName] !== element[propertyName]) //The hidden properties (which start with "_") are not inherited.
2019 {
2020 if (element.isSpritesScene &amp;&amp; propertyName === "spritesGroups")
2021 {
2022 element.spritesGroups.type = "spritesGroups";
2023 element._avoidParent = true; //It will not let it inherit from its parent.
2024 newObject.spritesGroups = CB_GraphicSprites.filterProperties(element.spritesGroups, propertiesToKeepObject);
2025 element._avoidParent = undefined;
2026 }
2027 else if (element.isSpritesGroups &amp;&amp; (propertyName === "spritesGroups" || propertyName === "items") || element.isSpritesGroup &amp;&amp; propertyName === "sprites" || element.isSprite &amp;&amp; propertyName === "subSprites")
2028 {
2029 var type = CB_GraphicSprites.filterProperties_types[propertyName];
2030 var currentElement = null;
2031 newObject[propertyName] = [];
2032 if (CB_isArray(element[propertyName]))
2033 {
2034 for (var x = 0; x &lt; element[propertyName].length; x++)
2035 {
2036 element[propertyName][x].type = type;
2037 element[propertyName][x]._avoidParent = true; //It will not let it inherit from its parent.
2038 newObject[propertyName][x] = CB_GraphicSprites.filterProperties(element[propertyName][x], propertiesToKeepObject);
2039 element[propertyName][x]._avoidParent = undefined;
2040 }
2041 }
2042 }
2043 else if (element.isSprites &amp;&amp; propertyName === "spritesGroup")
2044 {
2045 element.spritesGroup.type = "spritesGroup";
2046 element._avoidParent = true; //It will not let it inherit from its parent.
2047 newObject.spritesGroup = CB_GraphicSprites.filterProperties(element.spritesGroup, propertiesToKeepObject);
2048 element._avoidParent = undefined;
2049 }
2050 else if (propertyName === "data" &amp;&amp; element.data)
2051 {
2052 newObject.data = {};
2053 for (var dataPropertyName in element.data)
2054 {
2055 if (dataPropertyName === "that" || dataPropertyName === "getThis") { continue; }
2056 newObject.data[dataPropertyName] = element.data[dataPropertyName];
2057 }
2058 }
2059 else
2060 {
2061 newObject[propertyName] = element[propertyName];
2062 }
2063 }
2064 }
2065 }
2066
2067 propertyName = element.isSprites ? "sprites" : element.isSprite ? "subSprites" : "";
2068 if (propertyName !== "" &amp;&amp; CB_Arrays.indexOf(propertiesToKeepObject[element.type], propertyName) !== -1 &amp;&amp; typeof(element.forEach) === "function")
2069 {
2070 newObject[propertyName] = [];
2071 element.forEach.call
2072 (
2073 element,
2074 function(subElement)
2075 {
2076 //subElement._avoidParent = true; //It will not let it inherit from its parent.
2077 newObject[propertyName][newObject[propertyName].length] = CB_GraphicSprites.filterProperties(subElement, propertiesToKeepObject);
2078 //subElement._avoidParent = undefined;
2079 }
2080 );
2081 }
2082
2083 return newObject;
2084}</pre>
2085 </article>
2086</section>
2087
2088
2089
2090
2091
2092 </div>
2093 </div>
2094
2095 <div class="clearfix"></div>
2096
2097
2098
2099</div>
2100</div>
2101
2102
2103 <div class="modal fade" id="searchResults">
2104 <div class="modal-dialog">
2105 <div class="modal-content">
2106 <div class="modal-header">
2107 <button type="button" class="close" data-dismiss="modal" aria-label="Close"><span aria-hidden="true">&times;</span></button>
2108 <h4 class="modal-title">Search results</h4>
2109 </div>
2110 <div class="modal-body"></div>
2111 <div class="modal-footer">
2112 <button type="button" class="btn btn-default" data-dismiss="modal">Close</button>
2113 </div>
2114 </div><!-- /.modal-content -->
2115 </div><!-- /.modal-dialog -->
2116 </div>
2117
2118
2119<footer>
2120
2121
2122 <span class="copyright">
2123 <a href="printable/" target="_blank">See a more printer-friendly version</a><hr /><span style="color:#000000">© <address style="display:inline; font-style:normal;"><a href="https://crossbrowdy.com/" target="_blank">CrossBrowdy</a> API documentation</address> by <a href="https://joanalbamaldonado.com/" target="_blank">Joan Alba Maldonado</a> - <a href="https://creativecommons.org/licenses/by/4.0/" target="_blank">Creative Commons Attribution 4.0 International</a><br />DocStrap Copyright © 2012-2015 The contributors to the JSDoc3 and DocStrap projects.</span>
2124 </span>
2125
2126<span class="jsdoc-message">
2127 Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.2</a>
2128
2129 on Wed Mar 22nd 2023
2130
2131 using the <a href="https://github.com/docstrap/docstrap">DocStrap template</a>.
2132</span>
2133</footer>
2134
2135<script src="scripts/docstrap.lib.js"></script>
2136<script src="scripts/toc.js"></script>
2137
2138 <script type="text/javascript" src="scripts/fulltext-search-ui.js"></script>
2139
2140
2141<script>
2142$( function () {
2143 $( "[id*='$']" ).each( function () {
2144 var $this = $( this );
2145
2146 $this.attr( "id", $this.attr( "id" ).replace( "$", "__" ) );
2147 } );
2148
2149 $( ".tutorial-section pre, .readme-section pre, pre.prettyprint.source" ).each( function () {
2150 var $this = $( this );
2151
2152 var example = $this.find( "code" );
2153 exampleText = example.html();
2154 var lang = /{@lang (.*?)}/.exec( exampleText );
2155 if ( lang && lang[1] ) {
2156 exampleText = exampleText.replace( lang[0], "" );
2157 example.html( exampleText );
2158 lang = lang[1];
2159 } else {
2160 var langClassMatch = example.parent()[0].className.match(/lang\-(\S+)/);
2161 lang = langClassMatch ? langClassMatch[1] : "javascript";
2162 }
2163
2164 if ( lang ) {
2165
2166 $this
2167 .addClass( "sunlight-highlight-" + lang )
2168 .addClass( "linenums" )
2169 .html( example.html() );
2170
2171 }
2172 } );
2173
2174 Sunlight.highlightAll( {
2175 lineNumbers : true,
2176 showMenu : true,
2177 enableDoclinks : true
2178 } );
2179
2180 $.catchAnchorLinks( {
2181 navbarOffset: 10
2182 } );
2183 $( "#toc" ).toc( {
2184 anchorName : function ( i, heading, prefix ) {
2185 return $( heading ).attr( "id" ) || ( prefix + i );
2186 },
2187 selectors : "#toc-content h1,#toc-content h2,#toc-content h3,#toc-content h4",
2188 showAndHide : false,
2189 smoothScrolling: true
2190 } );
2191
2192 $( "#main span[id^='toc']" ).addClass( "toc-shim" );
2193 $( '.dropdown-toggle' ).dropdown();
2194
2195 $( "table" ).each( function () {
2196 var $this = $( this );
2197 $this.addClass('table');
2198 } );
2199
2200} );
2201</script>
2202
2203
2204
2205<!--Navigation and Symbol Display-->
2206
2207<script>
2208 $( function () {
2209 $( '#main' ).localScroll( {
2210 offset : { top : 60 } //offset by the height of your header (give or take a few px, see what works for you)
2211 } );
2212 $( "dt.name" ).each( function () {
2213 var $this = $( this ).find("h4");
2214 var icon = $( "<i/>" ).addClass( "icon-plus-sign" ).addClass( "pull-right" ).addClass( "icon-white" );
2215 var dt = $(this);
2216 var children = dt.next( "dd" );
2217
2218 dt.prepend( icon ).css( {cursor : "pointer"} );
2219 dt.addClass( "member-collapsed" ).addClass( "member" );
2220
2221
2222 children.hide();
2223
2224 dt.children().on( "click", function () {
2225 children = dt.next( "dd" );
2226 children.slideToggle( "fast", function () {
2227
2228 if ( children.is( ":visible" ) ) {
2229 icon.addClass( "icon-minus-sign" ).removeClass( "icon-plus-sign" ).removeClass( "icon-white" );
2230 dt.addClass( "member-open" ).animate( "member-collapsed" );
2231 } else {
2232 icon.addClass( "icon-plus-sign" ).removeClass( "icon-minus-sign" ).addClass( "icon-white" );
2233 dt.addClass( "member-collapsed" ).removeClass( "member-open" );
2234 }
2235 } );
2236 } );
2237
2238 } );
2239 } );
2240</script>
2241
2242
2243<!--Google Analytics-->
2244
2245
2246
2247 <script type="text/javascript">
2248 $(document).ready(function() {
2249 SearcherDisplay.init();
2250 });
2251 </script>
2252
2253
2254</body>
2255</html>