/** * @file Group of graphic sprites management (2D or 3D). Contains the {@link CB_GraphicSprites} class. * @author Joan Alba Maldonado <workindalian@gmail.com> */ /** * An object with the information that belongs to a sub-sprite (data which belongs to a certain source) used by a graphic sprite. * @example { id: "my_subsprite_1", src: "path/to/image.gif", srcType: "image", srcLeft: 10, srcTop: 20, srcWidth: 64, srcHeight: 32, left: 10, top: 20, width: 64, height: 32, zIndex: 1, disabled: false, data: { datum_1: "value_1", datum_2: 2, datum_3: [ "a", "b", "c" ] } } * @memberof CB_GraphicSprites * @typedef {Object} CB_GraphicSprites.SUBSPRITE_OBJECT * @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). * @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. * @property {string} [srcType=this.parent.srcType|{@link CB_GraphicSprites.SRC_TYPE_DEFAULT}] - Type of the source of origin. If not provided, as default it will use the value from the sprite that it belongs to. * @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. * @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. * @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. * @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. * @property {number} [left=this.parent.left|{@link CB_GraphicSprites.LEFT_DEFAULT}] - Left (horizontal) position in 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. * @property {number} [top=this.parent.top|{@link CB_GraphicSprites.TOP_DEFAULT}] - Top (vertical) position in 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. * @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. * @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. * @property {number} [zIndex=this.parent.zIndex|{@link CB_GraphicSprites.ZINDEX_DEFAULT}] - The z-index for the destiny (inside the sprite). Only numeric values are allowed. If not provided, as default it will use the value from the sprite that it belongs to. * @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. * @property {object} [data=this.parent.data||{ 'this' : CB_GraphicSprites.SPRITES_OBJECT, 'getThis' = function() { return this.this; } }] - Object with any additional data desired which can be any kind. If not provided, as default it will use the value from the sprite that it belongs to. It will always have a "this" 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 ("this" and "getThis") cannot be overridden. * @property {CB_GraphicSprites.SPRITE_OBJECT} parent - Read-only property pointing to its parent ({@link CB_GraphicSprites.SPRITE_OBJECT} object). * @property {CB_GraphicSprites} container - Read-only property pointing to the {@link CB_GraphicSprites} object which contains it. * @property {'subSprite'} type - Read-only property indicating the type of object (always "subSprite"). * @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). * @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. */ /** * 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). * @example { //'my_sprite_1': id: "my_sprite_1", src: "path/to/image.gif", srcType: "image", srcLeft: 10, srcTop: 20, srcWidth: 64, srcHeight: 32, left: 10, top: 20, width: 64, height: 32, disabled: false, data: { datum_1 : "value_1", datum_2 : 2, datum_3: [ "a", "b", "c" ] }, subSprites: [ //'my_subsprite_1': { id: "my_subsprite_1", srcLeft: 10, srcTop: 20, zIndex: 1 }, //'my_subsprite_2': { id: "my_subsprite_2", srcLeft: 20, srcTop: 40, zIndex: 2 } ] } * @memberof CB_GraphicSprites * @typedef {Object} CB_GraphicSprites.SPRITE_OBJECT * @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). * @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. * @property {string} [srcType=this.parent.srcType|{@link CB_GraphicSprites.SRC_TYPE_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. * @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. * @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. * @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. * @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. * @property {number} [left=this.parent.left|{@link CB_GraphicSprites.LEFT_DEFAULT}] - Left (horizontal) position in 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. * @property {number} [top=this.parent.top|{@link CB_GraphicSprites.TOP_DEFAULT}] - Top (vertical) position in 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. * @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. * @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. * @property {number} [zIndex=this.parent.zIndex|{@link CB_GraphicSprites.ZINDEX_DEFAULT}] - The z-index for the destiny (inside the sprites group). Only numeric values are allowed. If not provided, as default it will use the value from the sprites group that it belongs to. * @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. * @property {object} [data=this.parent.data||{ 'this' : CB_GraphicSprites.SPRITES_OBJECT, 'getThis' = function() { return this.this; } }] - Object with any additional data desired which can be any kind. If not provided, as default it will use the value from the sprites group that it belongs to. It will always have a "this" 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 ("this" and "getThis") cannot be overridden. * @property {array} [subSprites=[]] - Numeric array containing {@link CB_GraphicSprites.SUBSPRITE_OBJECT} objects with the sub-sprites that this sprite uses. * @property {CB_GraphicSprites.SPRITES_OBJECT} parent - Read-only property pointing to its parent ({@link CB_GraphicSprites.SPRITES_OBJECT} object). * @property {CB_GraphicSprites} container - Read-only property pointing to the {@link CB_GraphicSprites} object which contains it. * @property {'sprite'} type - Read-only property indicating the type of object (always "sprite"). * @property {integer} time - Read-only 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. * @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. * @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. * @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. * @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. * @property {function} removeSubSprites - Alias for the "removeAll" method. * @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. * @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. * @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. * @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. * @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 only one parameter which belongs to the "returnValueOnFail" parameter of the {@link CB_GraphicSprites#getAll} method. * @property {function} getSubSprites - Alias for the "getAll" method. * @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. * @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. * @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. * @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", "delayBetweenEach", "returnSetTimeoutsArray", "delayBetweenEachAffectsFirst" and "functionFinish") which belong to the parameters with the same name of the {@link CB_GraphicSprites#executeFunctionAllSubSprites} method. * @property {function} executeAll - Alias for the "executeFunctionAll" method. * @property {function} forEach - Alias for the "executeFunctionAll" method. * @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. * @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. * @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. * @property {function} getCurrentPosition - Alias for the "getPointer" method. * @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. * @property {function} setCurrentPosition - Alias for the "setPointer" method. * @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. * @property {function} current - Alias for the "getCurrent" method. * @property {function} now - Alias for the "getCurrent" method. * @property {function} getNext - 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#getNext} internally and returns its returning value. With only one parameter which belongs to the "loop" parameter of the {@link CB_GraphicSprites#getNext} method. * @property {function} setNext - Alias for the "getNext" method. * @property {function} next - Alias for the "getNext" method. * @property {function} getPrevious - 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#getPrevious} internally and returns its returning value. With only one parameter which belongs to the "loop" parameter of the {@link CB_GraphicSprites#getPrevious} method. * @property {function} setPrevious - Alias for the "getPrevious" method. * @property {function} previous - Alias for the "getPrevious" method. */ /** * An object with the information that belongs to a group of graphic sprites. * @example { //'my_sprites_1': id: "my_sprites_1", src: "path/to/image.gif", srcType: "image", srcLeft: 10, srcTop: 20, srcWidth: 64, srcHeight: 32, left: 10, top: 20, width: 64, height: 32, data: { datum_1: "value_1", datum_2: 2, datum_3: [ "a", "b", "c" ] }, sprites: [ //'my_sprite_1': { id: "my_sprite_1", subSprites: [ //'my_subsprite_1': { id: "my_subsprite_1", srcLeft: 10, srcTop: 20, zIndex: 1 }, //'my_subsprite_2': { id: "my_subsprite_2", srcLeft: 20, srcTop: 40, zIndex: 2 } ] }, //'my_sprite_2': { id: "my_sprite_2", subSprites: [ //'my_subsprite_3': { id: "my_subsprite_3", srcLeft: 30, srcTop: 60, zIndex: 1 }, //'my_subsprite_4': { id: "my_subsprite_4", srcLeft: 40, srcTop: 80, zIndex: 2 } ] } ] } * @memberof CB_GraphicSprites * @typedef {Object} CB_GraphicSprites.SPRITES_OBJECT * @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). * @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. * @property {string} [srcType={@link CB_GraphicSprites.SRC_TYPE_DEFAULT}] - Type of the source of origin. * @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}. * @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}. * @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}. * @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}. * @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}. * @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}. * @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}. * @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}. * @property {number} [zIndex={@link CB_GraphicSprites.ZINDEX_DEFAULT}] - The z-index for the destiny (only numeric values are allowed). If not provided, as default it will use the value from {@link CB_GraphicSprites.ZINDEX_DEFAULT}. * @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). * @property {object} [data={ 'this' : CB_GraphicSprites.SPRITES_OBJECT, 'getThis' = function() { return this.this; } }] - Object with any additional data desired which can be any kind. It will always have a "this" 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 ("this" and "getThis") cannot be overridden. * @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. * @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. * @property {CB_GraphicSprites} container - Read-only property pointing to the {@link CB_GraphicSprites} object which contains it. * @property {'spritesGroup'} type - Read-only property indicating the type of object (always "spritesGroup"). */ /** * Class to manage a group of graphic sprites (2D or 3D). * @class * @classdesc Class to manage a group of graphic sprites (2D or 3D). * @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. * @returns {CB_GraphicSprites} Returns a new {@link CB_GraphicSprites} object. * @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). * @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. */ var CB_GraphicSprites = function(spritesGroup) { //Creates an instance of this object and returns it in the case that it is being called from an unexpected context: if (this === window || !(this instanceof CB_GraphicSprites)) { return new CB_GraphicSprites(spritesGroup); } //Properties and variables: /** * 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). * @var * @readonly * @type {string|*} * @default 'CB_GraphicSprites_' + CB_GraphicSprites._idUnique++ */ this.id = ""; /** * 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. * @var * @readonly * @type {*} * @default */ this.parent = undefined; /** * Object with information about the sprites. * @var * @readonly * @type {CB_GraphicSprites.SPRITES_OBJECT} * @default */ this.spritesGroup = {}; /** * Pointer with the position of the current sprite (belongs to an index of the {@link CB_GraphicSprites#spritesGroup.sprites} array). * @var * @readonly * @type {integer} * @default */ this.pointer = -1; /** * 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). * @var * @readonly * @type {integer} * @default */ this.time = 0; //Calls the constructor of the object when creates an instance: return this._init(spritesGroup); } //Constants: /** * Indicates the type of object (always "sprites"). * @constant * @type {string} * @default */ CB_GraphicSprites.prototype.type = "sprites"; /** * Default "srcType", the type of the original source. * @constant * @type {string} * @default */ CB_GraphicSprites.SRC_TYPE_DEFAULT = "image"; /** * Default width ("srcWidth") of the original source. Unit agnostic. * @constant * @type {number} * @default */ CB_GraphicSprites.WIDTH_SOURCE_DEFAULT = 32; /** * Default height ("srcHeight") of the original source. Unit agnostic. * @constant * @type {number} * @default */ CB_GraphicSprites.HEIGHT_SOURCE_DEFAULT = 32; /** * Default left ("srcLeft", horizontal position) in the original source. Unit agnostic. * @constant * @type {number} * @default */ CB_GraphicSprites.LEFT_SOURCE_DEFAULT = 0; /** * Default top ("srcTop", vertical position) in the original source. Unit agnostic. * @constant * @type {number} * @default */ CB_GraphicSprites.TOP_SOURCE_DEFAULT = 0; /** * Default "width" of the destiny. Unit agnostic. * @constant * @type {number} * @default */ CB_GraphicSprites.WIDTH_DEFAULT = CB_GraphicSprites.WIDTH_SOURCE_DEFAULT; /** * Default "height" of the destiny. Unit agnostic. * @constant * @type {number} * @default */ CB_GraphicSprites.HEIGHT_DEFAULT = CB_GraphicSprites.HEIGHT_SOURCE_DEFAULT; /** * Default "left" (horizontal position) in the destiny. Unit agnostic. * @constant * @type {number} * @default */ CB_GraphicSprites.LEFT_DEFAULT = 0; /** * Default "top" (vertical position) in the destiny. Unit agnostic. * @constant * @type {number} * @default */ CB_GraphicSprites.TOP_DEFAULT = 0; /** * Default "zIndex" in the destiny. * @constant * @type {number} * @default */ CB_GraphicSprites.ZINDEX_DEFAULT = 1; //Variables: CB_GraphicSprites._idUnique = 0; //Counter to make the sprites group id unique. CB_GraphicSprites._idSpriteUnique = 0; //Counter to make the sprite id unique. CB_GraphicSprites._idSubSpriteUnique = 0; //Counter to make the sub-sprite id unique. //Constructor: CB_GraphicSprites.prototype._init = function(spritesGroup) { this.insertSprites(spritesGroup); //Inserts the given sprites group. return this; } /** * Destroys the graphic sprites object (removing all the sprites and their sub-sprites, etc.) and frees memory. * @function */ CB_GraphicSprites.prototype.destructor = function() { //Resets properties to their default value: this.removeSprites(); } /** * Alias for {@link CB_GraphicSprites#removeSprites}. * @function CB_GraphicSprites#removeAll * @see {@link CB_GraphicSprites#removeSprites} */ /** * Alias for {@link CB_GraphicSprites#removeSprites}. * @function CB_GraphicSprites#removeSpritesGroup * @see {@link CB_GraphicSprites#removeSprites} */ /** * Alias for {@link CB_GraphicSprites#removeSprites}. * @function CB_GraphicSprites#removeSpritesAll * @see {@link CB_GraphicSprites#removeSprites} */ /** * Removes all the sprites by clearing the {@link CB_GraphicSprites#spritesGroup} property. * @function */ CB_GraphicSprites.prototype.removeSprites = CB_GraphicSprites.prototype.removeSpritesAll = CB_GraphicSprites.prototype.removeSpritesGroup = CB_GraphicSprites.prototype.removeAll = function() { this.spritesGroup = {}; this.pointer = -1; } /** * Alias for {@link CB_GraphicSprites#insertSprites}. * @function CB_GraphicSprites#insertSpritesGroup * @see {@link CB_GraphicSprites#insertSprites} */ /** * Adds the desired group of graphic sprites. Calls {@link CB_GraphicSprites#insertSprite} internally. * @function * @param {CB_GraphicSprites.SPRITES_OBJECT} [spritesGroup] - Object with the desired sprites. They will be stored in the {@link CB_GraphicSprites#spritesGroup} property. * @returns {CB_GraphicSprites.SPRITES_OBJECT} Returns the {@link CB_GraphicSprites#spritesGroup} property after updating it. */ CB_GraphicSprites.prototype.insertSprites = CB_GraphicSprites.prototype.insertSpritesGroup = function(spritesGroup) { //Sets the properties (sanitizing them): this.spritesGroup = this.spritesGroup || {}; spritesGroup = spritesGroup || {}; this.spritesGroup.type = "spritesGroup"; this.spritesGroup.container = this; this.parent = this.spritesGroup.parent = spritesGroup.parent; this.id = this.spritesGroup.id = spritesGroup.id = spritesGroup.id || "CB_GraphicSprites_" + CB_GraphicSprites._idUnique++; this.spritesGroup.src = spritesGroup.src = spritesGroup.src || ""; this.spritesGroup.srcType = spritesGroup.srcType = spritesGroup.srcType || CB_GraphicSprites.SRC_TYPE_DEFAULT; spritesGroup.srcLeft = parseFloat(spritesGroup.srcLeft); this.spritesGroup.srcLeft = spritesGroup.srcLeft = !isNaN(spritesGroup.srcLeft) ? spritesGroup.srcLeft : parseFloat(CB_GraphicSprites.LEFT_SOURCE_DEFAULT) || 0; spritesGroup.left = parseFloat(spritesGroup.left); this.spritesGroup.left = spritesGroup.left = !isNaN(spritesGroup.left) ? spritesGroup.left : parseFloat(CB_GraphicSprites.LEFT_DEFAULT) || 0; spritesGroup.srcTop = parseFloat(spritesGroup.srcTop); this.spritesGroup.srcTop = spritesGroup.srcTop = !isNaN(spritesGroup.srcTop) ? spritesGroup.srcTop : parseFloat(CB_GraphicSprites.TOP_SOURCE_DEFAULT) || 0; spritesGroup.top = parseFloat(spritesGroup.top); this.spritesGroup.top = spritesGroup.top = !isNaN(spritesGroup.top) ? spritesGroup.top : parseFloat(CB_GraphicSprites.TOP_DEFAULT) || 0; spritesGroup.srcWidth = parseFloat(spritesGroup.srcWidth); this.spritesGroup.srcWidth = spritesGroup.srcWidth = !isNaN(spritesGroup.srcWidth) ? spritesGroup.srcWidth : parseFloat(CB_GraphicSprites.WIDTH_SOURCE_DEFAULT) || 0; spritesGroup.width = parseFloat(spritesGroup.width); this.spritesGroup.width = spritesGroup.width = !isNaN(spritesGroup.width) ? spritesGroup.width : CB_GraphicSprites.WIDTH_DEFAULT; spritesGroup.srcHeight = parseFloat(spritesGroup.srcHeight); this.spritesGroup.srcHeight = spritesGroup.srcHeight = !isNaN(spritesGroup.srcHeight) ? spritesGroup.srcHeight : parseFloat(CB_GraphicSprites.HEIGHT_SOURCE_DEFAULT) || 0; spritesGroup.height = parseFloat(spritesGroup.height); this.spritesGroup.height = spritesGroup.height = !isNaN(spritesGroup.height) ? spritesGroup.height : parseFloat(CB_GraphicSprites.HEIGHT_DEFAULT) || 0; spritesGroup.zIndex = parseFloat(spritesGroup.zIndex); this.spritesGroup.disabled = !!spritesGroup.disabled; this.spritesGroup.zIndex = spritesGroup.zIndex = !isNaN(spritesGroup.zIndex) ? spritesGroup.zIndex : parseFloat(CB_GraphicSprites.ZINDEX_DEFAULT) || 0; this.spritesGroup.data = typeof(spritesGroup.data) === "object" && spritesGroup.data !== null ? CB_copyObject(spritesGroup.data, false) : {}; //Accepts any object but not other values. this.spritesGroup.data.this = this.spritesGroup; this.spritesGroup.data.getThis = function() { return this.this; }; spritesGroup.sprites = CB_isArray(spritesGroup.sprites) ? spritesGroup.sprites : []; //Inserts the given sprites, one by one: var spritesLength = spritesGroup.sprites.length; for (var x = 0; x < spritesLength; x++) { this.insertSprite(spritesGroup.sprites[x]); } //Returns the sprites: return this.spritesGroup; } /** * Alias for {@link CB_GraphicSprites#removeSprite}. * @function CB_GraphicSprites#remove * @see {@link CB_GraphicSprites#removeSprite} */ /** * Removes a sprite by its index (its position in the {@link CB_GraphicSprites#spritesGroup.sprites} array). * @function * @param {integer} [index=0] - The index where the sprite is located (its position in the {@link CB_GraphicSprites#spritesGroup.sprites} array). * @returns {boolean} Returns true if the sprite has been deleted or false otherwise. */ CB_GraphicSprites.prototype.removeSprite = CB_GraphicSprites.prototype.remove = function(index) { var removed = false; var spritesLeft = CB_Arrays.removeElementByPosition(this.spritesGroup.sprites, index, function() { removed = true; }); if (removed) { this.spritesGroup.sprites = spritesLeft; //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: this.setPointer(this.getPointer()); } return removed; } /** * Alias for {@link CB_GraphicSprites#removeSpriteById}. * @function CB_GraphicSprites#removeById * @see {@link CB_GraphicSprites#removeSpriteById} */ /** * Removes a sprite by its identifier. * @function * @param {string|*} [id=undefined] - The identifier of the sprite. * @returns {boolean} Returns true if the sprite has been deleted or false otherwise. * @todo Optimize it (maybe using a cache matching the IDs with their position). */ CB_GraphicSprites.prototype.removeSpriteById = CB_GraphicSprites.prototype.removeById = function(id) { var removed = false; var spritesLeft = CB_Arrays.removeDuplicated(this.spritesGroup.sprites, function(value, position, array) { if (value && value.id === id) { removed = true; return true; }; return false; }, true); if (removed) { this.spritesGroup.sprites = spritesLeft; //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: this.setPointer(this.getPointer()); } return removed; } /** * Alias for {@link CB_GraphicSprites#insertSprite}. * @function CB_GraphicSprites#insert * @see {@link CB_GraphicSprites#insertSprite} */ /** * 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. * @function * @param {CB_GraphicSprites.SPRITE_OBJECT} [sprite] - Object with the desired sprite. It will be stored inside the {@link CB_GraphicSprites#spritesGroup} property. * @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). */ CB_GraphicSprites.prototype.insertSprite = CB_GraphicSprites.prototype.insert = function(sprite) { //Sets the properties (sanitizing them): this.spritesGroup = this.spritesGroup || {}; sprite = sprite || {}; sprite.type = "sprite"; sprite.container = this; sprite.parent = this.spritesGroup; sprite.time = 0; sprite.id = sprite.id || "CB_GraphicSprites.sprite_" + CB_GraphicSprites._idSpriteUnique++; sprite.src = sprite.src || this.spritesGroup.src || ""; sprite.srcType = sprite.srcType || this.spritesGroup.srcType || CB_GraphicSprites.SRC_TYPE_DEFAULT; sprite.srcLeft = parseFloat(sprite.srcLeft); sprite.srcLeft = !isNaN(sprite.srcLeft) ? sprite.srcLeft : parseFloat(this.spritesGroup.srcLeft); sprite.srcLeft = !isNaN(sprite.srcLeft) ? sprite.srcLeft : parseFloat(CB_GraphicSprites.LEFT_SOURCE_DEFAULT) || 0; sprite.left = parseFloat(sprite.left); sprite.left = !isNaN(sprite.left) ? sprite.left : parseFloat(this.spritesGroup.left); sprite.left = !isNaN(sprite.left) ? sprite.left : parseFloat(CB_GraphicSprites.LEFT_DEFAULT) || 0; sprite.srcTop = parseFloat(sprite.srcTop); sprite.srcTop = !isNaN(sprite.srcTop) ? sprite.srcTop : parseFloat(this.spritesGroup.srcTop); sprite.srcTop = !isNaN(sprite.srcTop) ? sprite.srcTop : parseFloat(CB_GraphicSprites.TOP_SOURCE_DEFAULT) || 0; sprite.top = parseFloat(sprite.top); sprite.top = !isNaN(sprite.top) ? sprite.top : parseFloat(this.spritesGroup.top); sprite.top = !isNaN(sprite.top) ? sprite.top : parseFloat(CB_GraphicSprites.TOP_DEFAULT) || 0; sprite.srcWidth = parseFloat(sprite.srcWidth); sprite.srcWidth = !isNaN(sprite.srcWidth) ? sprite.srcWidth : parseFloat(this.spritesGroup.srcWidth); sprite.srcWidth = !isNaN(sprite.srcWidth) ? sprite.srcWidth : parseFloat(CB_GraphicSprites.WIDTH_SOURCE_DEFAULT) || 0; sprite.width = parseFloat(sprite.width); sprite.width = !isNaN(sprite.width) ? sprite.width : parseFloat(this.spritesGroup.width); sprite.width = !isNaN(sprite.width) ? sprite.width : parseFloat(CB_GraphicSprites.WIDTH_DEFAULT) || 0; sprite.srcHeight = parseFloat(sprite.srcHeight); sprite.srcHeight = !isNaN(sprite.srcHeight) ? sprite.srcHeight : parseFloat(this.spritesGroup.srcHeight); sprite.srcHeight = !isNaN(sprite.srcHeight) ? sprite.srcHeight : parseFloat(CB_GraphicSprites.HEIGHT_SOURCE_DEFAULT) || 0; sprite.height = parseFloat(sprite.height); sprite.height = !isNaN(sprite.height) ? sprite.height : parseFloat(this.spritesGroup.height); sprite.height = !isNaN(sprite.height) ? sprite.height : parseFloat(CB_GraphicSprites.HEIGHT_DEFAULT) || 0; sprite.zIndex = parseFloat(sprite.zIndex); sprite.zIndex = !isNaN(sprite.zIndex) ? sprite.zIndex : parseFloat(this.spritesGroup.zIndex); sprite.zIndex = !isNaN(sprite.zIndex) ? sprite.zIndex : parseFloat(CB_GraphicSprites.ZINDEX_DEFAULT) || 0; sprite.disabled = !!sprite.disabled || !!this.spritesGroup.disabled; if (!sprite.disabled && this.isDisabled()) { this.setDisabled(false); } //If it is enabled and its sprites group parent is not, all the sprites group must be enabled. sprite.data = typeof(sprite.data) === "object" && sprite.data !== null ? sprite.data : this.spritesGroup.data; sprite.data = typeof(sprite.data) === "object" && sprite.data !== null ? CB_copyObject(sprite.data, false) : {}; sprite.data.this = sprite; sprite.data.getThis = function() { return this.this; }; sprite.subSprites = CB_isArray(sprite.subSprites) ? sprite.subSprites : []; //Inserts the methods: sprite.removeAll = sprite.removeSubSprites = function() { return CB_GraphicSprites.prototype.removeSubSprites.call(sprite.container, sprite); } sprite.insertSubSprites = function(subSprites) { return CB_GraphicSprites.prototype.insertSubSprites.call(sprite.container, subSprites, sprite); } sprite.remove = function(index) { return CB_GraphicSprites.prototype.removeSubSprite.call(sprite.container, index, sprite); } sprite.removeById = function(id) { return CB_GraphicSprites.prototype.removeSubSpriteById.call(sprite.container, id, sprite); } sprite.insert = function(subSprite) { return CB_GraphicSprites.prototype.insertSubSprite.call(sprite.container, subSprite, sprite); } sprite.getAll = sprite.getSubSprites = function(returnValueOnFail) { return CB_GraphicSprites.prototype.getSubSprites.call(sprite.container, sprite, returnValueOnFail); } sprite.get = function(index, returnValueOnFail) { return CB_GraphicSprites.prototype.getSubSprite.call(sprite.container, index, sprite, returnValueOnFail); } sprite.getById = function(id, returnValueOnFail) { return CB_GraphicSprites.prototype.getSubSpriteById.call(sprite.container, id, sprite, returnValueOnFail); } sprite.getIndexById = function(id) { return CB_GraphicSprites.prototype.getSubSpriteIndexById.call(sprite.container, id, sprite); } sprite.executeFunctionAll = sprite.executeAll = sprite.forEach = function(functionEach, delayBetweenEach, returnSetTimeoutsArray, delayBetweenEachAffectsFirst, functionFinish) { return CB_GraphicSprites.prototype.executeFunctionAllSubSprites.call(sprite.container, functionEach, delayBetweenEach, sprite, returnSetTimeoutsArray, delayBetweenEachAffectsFirst, functionFinish); } sprite.isDisabled = function() { return CB_GraphicSprites.prototype.isDisabledSprite.call(sprite.container, sprite); } sprite.setDisabled = function(disabled, affectSubSprites, affectParent, affectParentChildren) { return CB_GraphicSprites.prototype.setDisabledSprite.call(sprite.container, sprite, disabled, affectSubSprites, affectParent, affectParentChildren); } sprite.setTime = function(time) { return CB_GraphicSprites.prototype.setTime.call(sprite, time, false); } sprite.getTime = function(returnValueOnFail) { return CB_GraphicSprites.prototype.getTime.call(sprite, returnValueOnFail); } sprite.getTimeElapsed = function(timeToCompare) { return CB_GraphicSprites.prototype.getTimeElapsed.call(sprite, timeToCompare, false); } sprite.getPointer = sprite.getCurrentPosition = function() { return CB_GraphicSprites.prototype.getPointer.call(sprite.container); } sprite.setPointer = sprite.setCurrentPosition = function(position, loop) { CB_GraphicSprites.prototype.setPointer.call(sprite.container, position, loop); return this.getCurrent(); } sprite.getCurrent = sprite.current = sprite.now = function() { return CB_GraphicSprites.prototype.getCurrent.call(sprite.container); } sprite.getNext = sprite.setNext = sprite.next = function(loop) { return CB_GraphicSprites.prototype.getNext.call(sprite.container, loop); } sprite.getPrevious = sprite.setPrevious = sprite.previous = function(loop) { return CB_GraphicSprites.prototype.getPrevious.call(sprite.container, loop); } //Inserts the given sub-sprites, one by one: this.insertSubSprites(sprite.subSprites, sprite); //Inserts the sprite: this.spritesGroup.sprites = this.spritesGroup.sprites || []; 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). position = position !== -1 ? position : this.spritesGroup.sprites.length; this.spritesGroup.sprites[position] = sprite; //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: this.setPointer(this.getPointer()); //Returns the sprite: return sprite; } /** * Alias for {@link CB_GraphicSprites#removeSubSprites}. * @function CB_GraphicSprites#removeSubSpritesAll * @see {@link CB_GraphicSprites#removeSubSprites} */ /** * Removes all the sub-sprites from a given sprite ({@link CB_GraphicSprites.SPRITE_OBJECT} object) by clearing its "subSprites" property (leaving an empty array). * @function * @param {CB_GraphicSprites.SPRITE_OBJECT} [sprite] - Object with the sprite whose sub-sprites we want to remove. * @returns {boolean} Returns true if the sub-sprites have been deleted or false otherwise. */ CB_GraphicSprites.prototype.removeSubSprites = CB_GraphicSprites.prototype.removeSubSpritesAll = function(sprite) { var removed = false; if (this.spritesGroup && this.spritesGroup.sprites) { var spritesLength = this.spritesGroup.sprites.length; for (var x = 0; x < spritesLength; x++) { if (this.spritesGroup.sprites[x] === sprite) { this.spritesGroup.sprites[x].subSprites = []; removed = true; break; } //Just removes one. } } return removed; } /** * Adds the given sub-sprites to the desired sprite. Calls {@link CB_GraphicSprites#insertSubSprite} internally. * @function * @param {array} [subSprites] - Numeric array with the desired sub-sprites ({@link CB_GraphicSprites.SUBSPRITE_OBJECT} objects). They will be stored inside the given sprite. * @param {CB_GraphicSprites.SPRITE_OBJECT} [sprite] - Object with the desired sprite. * @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). */ CB_GraphicSprites.prototype.insertSubSprites = function(subSprites, sprite) { //Sets the properties (sanitizing them): sprite = sprite || {}; subSprites = CB_isArray(subSprites) ? subSprites : []; //Inserts the given sub-sprites, one by one: var subSpritesInserted = []; var subSpritesLength = subSprites.length; for (var x = 0; x < subSpritesLength; x++) { subSpritesInserted[subSpritesInserted.length] = this.insertSubSprite(subSprites[x], sprite); } return subSpritesInserted; } /** * 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). * @function * @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). * @param {CB_GraphicSprites.SPRITE_OBJECT} [sprite] - Object with the sprite whose sub-sprites we want to remove. * @returns {boolean} Returns true if the sub-sprite has been deleted or false otherwise. */ CB_GraphicSprites.prototype.removeSubSprite = function(index, sprite) { var removed = false; if (this.spritesGroup && this.spritesGroup.sprites) { index = parseInt(index); index = isNaN(index) ? 0 : index; if (index < 0) { index *= -1; } //It must be a positive integer. var subSpritesLeft = null; var spritesLength = this.spritesGroup.sprites.length; for (var x = 0; x < spritesLength; x++) { if (this.spritesGroup.sprites[x] === sprite) { removed = false; subSpritesLeft = CB_Arrays.removeElementByPosition(this.spritesGroup.sprites[x].subSprites, index, function() { removed = true; }); if (removed) { this.spritesGroup.sprites[x].subSprites = subSpritesLeft; break; } //Just removes it from one. } } } return removed; } /** * Removes a sub-sprite from a given sprite ({@link CB_GraphicSprites.SPRITE_OBJECT} object) by its identifier. * @function * @param {string|*} [id=undefined] - The identifier of the sprite. * @param {CB_GraphicSprites.SPRITE_OBJECT} [sprite] - Object with the sprite whose sub-sprites we want to remove. * @returns {boolean} Returns true if the sub-sprite has been deleted or false otherwise. * @todo Optimize it (maybe using a cache matching the IDs with their position). */ CB_GraphicSprites.prototype.removeSubSpriteById = function(id, sprite) { var removed = false; if (this.spritesGroup && this.spritesGroup.sprites) { var subSpritesLeft = null; var spritesLength = this.spritesGroup.sprites.length; for (var x = 0; x < spritesLength; x++) { if (this.spritesGroup.sprites[x] === sprite) { removed = false; subSpritesLeft = CB_Arrays.removeDuplicated(this.spritesGroup.sprites[x].subSprites, function(value, position, array) { if (value && value.id === id) { removed = true; return true; }; return false; }, true); if (removed) { this.spritesGroup.sprites[x].subSprites = subSpritesLeft; break; } //Just removes it from one. } } } return removed; } /** * 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. * @function * @param {CB_GraphicSprites.SUBSPRITE_OBJECT} [subSprite] - Object with the desired sub-sprite. It will be stored inside the given sprite. * @param {CB_GraphicSprites.SPRITE_OBJECT} [sprite] - Object with the desired sprite. * @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). */ CB_GraphicSprites.prototype.insertSubSprite = function(subSprite, sprite) { //Sets the properties (sanitizing them): this.spritesGroup = this.spritesGroup || {}; sprite = sprite || {}; subSprite = subSprite || {}; subSprite.type = "subSprite"; subSprite.container = this; subSprite.parent = sprite; subSprite.id = subSprite.id || "CB_GraphicSprites.subSprite_" + CB_GraphicSprites._idSubSpriteUnique++; subSprite.src = subSprite.src || sprite.src || this.spritesGroup.src || ""; subSprite.srcType = subSprite.srcType || sprite.srcType || this.spritesGroup.srcType || CB_GraphicSprites.SRC_TYPE_DEFAULT; subSprite.srcLeft = parseFloat(subSprite.srcLeft); subSprite.srcLeft = !isNaN(subSprite.srcLeft) ? subSprite.srcLeft : parseFloat(sprite.srcLeft); subSprite.srcLeft = !isNaN(subSprite.srcLeft) ? subSprite.srcLeft : parseFloat(this.spritesGroup.srcLeft); subSprite.srcLeft = !isNaN(subSprite.srcLeft) ? subSprite.srcLeft : parseFloat(CB_GraphicSprites.LEFT_SOURCE_DEFAULT) || 0; subSprite.left = parseFloat(subSprite.left); subSprite.left = !isNaN(subSprite.left) ? subSprite.left : parseFloat(sprite.left); subSprite.left = !isNaN(subSprite.left) ? subSprite.left : parseFloat(this.spritesGroup.left); subSprite.left = !isNaN(subSprite.left) ? subSprite.left : parseFloat(CB_GraphicSprites.LEFT_DEFAULT) || 0; subSprite.srcTop = parseFloat(subSprite.srcTop); subSprite.srcTop = !isNaN(subSprite.srcTop) ? subSprite.srcTop : parseFloat(sprite.srcTop); subSprite.srcTop = !isNaN(subSprite.srcTop) ? subSprite.srcTop : parseFloat(this.spritesGroup.srcTop); subSprite.srcTop = !isNaN(subSprite.srcTop) ? subSprite.srcTop : parseFloat(CB_GraphicSprites.TOP_SOURCE_DEFAULT) || 0; subSprite.top = parseFloat(subSprite.top); subSprite.top = !isNaN(subSprite.top) ? subSprite.top : parseFloat(sprite.top); subSprite.top = !isNaN(subSprite.top) ? subSprite.top : parseFloat(this.spritesGroup.top); subSprite.top = !isNaN(subSprite.top) ? subSprite.top : parseFloat(CB_GraphicSprites.TOP_DEFAULT) || 0; subSprite.srcWidth = parseFloat(subSprite.srcWidth); subSprite.srcWidth = !isNaN(subSprite.srcWidth) ? subSprite.srcWidth : parseFloat(sprite.srcWidth); subSprite.srcWidth = !isNaN(subSprite.srcWidth) ? subSprite.srcWidth : parseFloat(this.spritesGroup.srcWidth); subSprite.srcWidth = !isNaN(subSprite.srcWidth) ? subSprite.srcWidth : parseFloat(CB_GraphicSprites.WIDTH_SOURCE_DEFAULT) || 0; subSprite.width = parseFloat(subSprite.width); subSprite.width = !isNaN(subSprite.width) ? subSprite.width : parseFloat(sprite.width); subSprite.width = !isNaN(subSprite.width) ? subSprite.width : parseFloat(this.spritesGroup.width); subSprite.width = !isNaN(subSprite.width) ? subSprite.width : parseFloat(CB_GraphicSprites.WIDTH_DEFAULT) || 0; subSprite.srcHeight = parseFloat(subSprite.srcHeight); subSprite.srcHeight = !isNaN(subSprite.srcHeight) ? subSprite.srcHeight : parseFloat(sprite.srcHeight); subSprite.srcHeight = !isNaN(subSprite.srcHeight) ? subSprite.srcHeight : parseFloat(this.spritesGroup.srcHeight); subSprite.srcHeight = !isNaN(subSprite.srcHeight) ? subSprite.srcHeight : parseFloat(CB_GraphicSprites.HEIGHT_SOURCE_DEFAULT) || 0; subSprite.height = parseFloat(subSprite.height); subSprite.height = !isNaN(subSprite.height) ? subSprite.height : parseFloat(sprite.height); subSprite.height = !isNaN(subSprite.height) ? subSprite.height : parseFloat(this.spritesGroup.height); subSprite.height = !isNaN(subSprite.height) ? subSprite.height : parseFloat(CB_GraphicSprites.HEIGHT_DEFAULT) || 0; subSprite.zIndex = parseFloat(subSprite.zIndex); subSprite.zIndex = !isNaN(subSprite.zIndex) ? subSprite.zIndex : parseFloat(sprite.zIndex); subSprite.zIndex = !isNaN(subSprite.zIndex) ? subSprite.zIndex : parseFloat(this.spritesGroup.zIndex); subSprite.zIndex = !isNaN(subSprite.zIndex) ? subSprite.zIndex : parseFloat(CB_GraphicSprites.ZINDEX_DEFAULT) || 0; subSprite.disabled = !!subSprite.disabled || !!sprite.disabled || !!this.spritesGroup.disabled; if (!subSprite.disabled && this.isDisabledSprite(sprite)) { this.setDisabled(false); } //If it is enabled but its sprite parent is not, all the sprites group must be enabled. subSprite.data = typeof(subSprite.data) === "object" && subSprite.data !== null ? subSprite.data : sprite.data; subSprite.data = typeof(subSprite.data) === "object" && subSprite.data !== null ? subSprite.data : this.spritesGroup.data; subSprite.data = typeof(subSprite.data) === "object" && subSprite.data !== null ? CB_copyObject(subSprite.data, false) : {}; subSprite.data.this = subSprite; subSprite.data.getThis = function() { return this.this; }; //Inserts the methods: subSprite.isDisabled = function() { return CB_GraphicSprites.prototype.isDisabledSubSprite.call(subSprite.container, subSprite); } subSprite.setDisabled = function(disabled, affectParents, affectParentsChildren) { return CB_GraphicSprites.prototype.setDisabledSubSprite.call(subSprite.container, subSprite, disabled, affectParents, affectParentsChildren); } //Inserts the sub-sprite: sprite.subSprites = sprite.subSprites || []; 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). position = position !== -1 ? position : sprite.subSprites.length; sprite.subSprites[position] = subSprite; //Returns the sub-sprite: return subSprite; } /** * Gets the sprites group object (the internal {@link CB_GraphicSprites.SPRITES_OBJECT} object, if any). * @function * @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. * @returns {CB_GraphicSprites.SPRITES_OBJECT|*} Returns a {@link CB_GraphicSprites.SPRITES_OBJECT} object with all the sprites or the value of "returnValueOnFail" otherwise. */ CB_GraphicSprites.prototype.getSpritesGroup = function(returnValueOnFail) { return this.spritesGroup || returnValueOnFail; } /** * Alias for {@link CB_GraphicSprites#getSprites}. * @function CB_GraphicSprites#getAll * @see {@link CB_GraphicSprites#getSprites} */ /** * Alias for {@link CB_GraphicSprites#getSprites}. * @function CB_GraphicSprites#getSpritesAll * @see {@link CB_GraphicSprites#getSprites} */ /** * Gets all the sprites (the "sprites" property of the internal {@link CB_GraphicSprites.SPRITES_OBJECT} object, if any). * @function * @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. * @returns {array|*} Returns an array with all the {@link CB_GraphicSprites.SPRITE_OBJECT} objects or the value of "returnValueOnFail" otherwise. */ CB_GraphicSprites.prototype.getSprites = CB_GraphicSprites.prototype.getSpritesAll = CB_GraphicSprites.prototype.getAll = function(returnValueOnFail) { return (this.spritesGroup && this.spritesGroup.sprites) ? this.spritesGroup.sprites : returnValueOnFail; } /** * Alias for {@link CB_GraphicSprites#getSprite}. * @function CB_GraphicSprites#get * @see {@link CB_GraphicSprites#getSprite} */ /** * 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. * @function * @param {integer} [index=0] - The index where the desired sprite must be located (its position in the {@link CB_GraphicSprites#spritesGroup.sprites} array). * @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. * @returns {CB_GraphicSprites.SPRITE_OBJECT|*} Returns a {@link CB_GraphicSprites.SPRITE_OBJECT} object if found or the value of "returnValueOnFail" otherwise. */ CB_GraphicSprites.prototype.getSprite = CB_GraphicSprites.prototype.get = function(index, returnValueOnFail) { index = parseInt(index); index = isNaN(index) ? 0 : index; if (index < 0) { index *= -1; } //It must be a positive integer. return this.spritesGroup && this.spritesGroup.sprites && this.spritesGroup.sprites[index] ? this.spritesGroup.sprites[index] : returnValueOnFail; } /** * Alias for {@link CB_GraphicSprites#getSpriteById}. * @function CB_GraphicSprites#getById * @see {@link CB_GraphicSprites#getSpriteById} */ /** * Gets a desired sprite object through its identifier. Slower than getting it through its index with the {@link CB_GraphicSprites#getSprite} method. * @function * @param {string|*} [id=undefined] - The identifier of the sprite that we want to get. * @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. * @returns {CB_GraphicSprites.SPRITE_OBJECT|*} Returns a {@link CB_GraphicSprites.SPRITE_OBJECT} object if found or the value of "returnValueOnFail" otherwise. */ CB_GraphicSprites.prototype.getSpriteById = CB_GraphicSprites.prototype.getById = function(id, returnValueOnFail) { var index = this.getSpriteIndexById(id); return index !== -1 ? this.spritesGroup.sprites[index] : returnValueOnFail; } /** * Alias for {@link CB_GraphicSprites#getSpriteIndexById}. * @function CB_GraphicSprites#getIndexById * @see {@link CB_GraphicSprites#getSpriteIndexById} */ /** * Gets the index (the position in the {@link CB_GraphicSprites#spritesGroup.sprites} array) of a desired sprite by its identifier. * @function * @param {string|*} [id=undefined] - The identifier of the sprite whose index we want to get. * @returns {integer} Returns the index (the position in the {@link CB_GraphicSprites#spritesGroup.sprites} array) of the desired sprite or -1 if not found. * @todo Optimize it (maybe using a cache matching the IDs with their position). */ CB_GraphicSprites.prototype.getSpriteIndexById = CB_GraphicSprites.prototype.getIndexById = function(id) { if (this.spritesGroup && this.spritesGroup.sprites) { var spritesLength = this.spritesGroup.sprites.length; for (var x = 0; x < spritesLength; x++) { if (this.spritesGroup.sprites[x].id === id) { return x; } } } return -1; } /** * Gets an array with all the {@link CB_GraphicSprites.SUBSPRITE_OBJECT} objects of a given {@link CB_GraphicSprites.SPRITE_OBJECT} object. * @function * @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). * @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. * @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. */ CB_GraphicSprites.prototype.getSubSprites = function(sprite, returnValueOnFail) { sprite = sprite || this.getCurrent(); return sprite && sprite.subSprites ? sprite.subSprites : returnValueOnFail; } /** * 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. * @function * @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). * @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). * @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. * @returns {CB_GraphicSprites.SUBSPRITE_OBJECT|*} Returns a {@link CB_GraphicSprites.SUBSPRITE_OBJECT} object if found or the value of "returnValueOnFail" otherwise. */ CB_GraphicSprites.prototype.getSubSprite = function(index, sprite, returnValueOnFail) { index = parseInt(index); index = isNaN(index) ? 0 : index; if (index < 0) { index *= -1; } //It must be a positive integer. sprite = sprite || this.getCurrent(); return sprite && sprite.subSprites && sprite.subSprites[index] ? sprite.subSprites[index] : returnValueOnFail; } /** * 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. * @function * @param {string|*} [id=undefined] - The identifier of the sub-sprite that we want to get. * @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). * @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. * @returns {CB_GraphicSprites.SUBSPRITE_OBJECT|*} Returns a {@link CB_GraphicSprites.SUBSPRITE_OBJECT} object if found or the value of "returnValueOnFail" otherwise. */ CB_GraphicSprites.prototype.getSubSpriteById = function(id, sprite, returnValueOnFail) { sprite = sprite || this.getCurrent(); var index = this.getSubSpriteIndexById(id, sprite); return index !== -1 ? sprite.subSprites[index] : returnValueOnFail; } /** * 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. * @function * @param {string|*} [id=undefined] - The identifier of the sub-sprite whose index we want to get. * @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). * @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. * @todo Optimize it (maybe using a cache matching the IDs with their position). */ CB_GraphicSprites.prototype.getSubSpriteIndexById = function(id, sprite) { sprite = sprite || this.getCurrent(); if (sprite && sprite.subSprites) { var subSpritesLength = sprite.subSprites.length; for (var x = 0; x < subSpritesLength; x++) { if (sprite.subSprites[x].id === id) { return x; } } } return -1; } /** * Alias for {@link CB_GraphicSprites#executeFunctionAll}. * @function CB_GraphicSprites#executeAll * @see {@link CB_GraphicSprites#executeFunctionAll} */ /** * Alias for {@link CB_GraphicSprites#executeFunctionAll}. * @function CB_GraphicSprites#forEach * @see {@link CB_GraphicSprites#executeFunctionAll} */ /** * Alias for {@link CB_GraphicSprites#executeFunctionAll}. * @function CB_GraphicSprites#forEachSprite * @see {@link CB_GraphicSprites#executeFunctionAll} */ /** * 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. * @function * @param {CB_Arrays.removeElement_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. * @param {number|CB_Arrays.removeElement_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). * @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. * @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). * @param {boolean} [delayBetweenEachAffectsFirst=false] - If set to true, the desired delay (if any) will also affect the first call to the "functionEach" function. * @param {CB_Arrays.removeElement_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. * @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. * @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. */ CB_GraphicSprites.prototype.executeFunctionAll = CB_GraphicSprites.prototype.executeAll = CB_GraphicSprites.prototype.forEachSprite = CB_GraphicSprites.prototype.forEach = function(functionEach, delayBetweenEach, sprites, returnSetTimeoutsArray, delayBetweenEachAffectsFirst, functionFinish) { return CB_Arrays.executeFunctionAll(CB_isArray(sprites) ? sprites : this.getSprites([]), functionEach, delayBetweenEach, returnSetTimeoutsArray, delayBetweenEachAffectsFirst, functionFinish); } /** * Alias for {@link CB_AudioFileSpritesPool#executeFunctionAllSubSprites}. * @function CB_AudioFileSpritesPool#executeAllSubSprites * @see {@link CB_AudioFileSpritesPool#executeFunctionAllSubSprites} */ /** * Alias for {@link CB_AudioFileSpritesPool#executeFunctionAllSubSprites}. * @function CB_AudioFileSpritesPool#forEachSubSprite * @see {@link CB_AudioFileSpritesPool#executeFunctionAllSubSprites} */ /** * 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. * @function * @param {CB_Arrays.removeElement_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. * @param {number|CB_Arrays.removeElement_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). * @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). * @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). * @param {boolean} [delayBetweenEachAffectsFirst=false] - If set to true, the desired delay (if any) will also affect the first call to the "functionEach" function. * @param {CB_Arrays.removeElement_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. * @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. * @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. */ CB_GraphicSprites.prototype.executeFunctionAllSubSprites = CB_GraphicSprites.prototype.executeAllSubSprites = CB_GraphicSprites.prototype.forEachSubSprite = function(functionEach, delayBetweenEach, sprite, returnSetTimeoutsArray, delayBetweenEachAffectsFirst, functionFinish) { return CB_Arrays.executeFunctionAll(this.getSubSprites(sprite, []), functionEach, delayBetweenEach, returnSetTimeoutsArray, delayBetweenEachAffectsFirst, functionFinish); } /** * Alias for {@link CB_GraphicSprites#getPointer}. * @function CB_GraphicSprites#getCurrentPosition * @see {@link CB_GraphicSprites#getPointer} */ /** * 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. * @function * @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). */ CB_GraphicSprites.prototype.getPointer = CB_GraphicSprites.prototype.getCurrentPosition = function() { return parseInt(this.pointer) && this.pointer >= 0 ? this.pointer : 0; } /** * Alias for {@link CB_GraphicSprites#setPointer}. * @function CB_GraphicSprites#setCurrentPosition * @see {@link CB_GraphicSprites#setPointer} */ /** * 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). * @function * @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). * @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. * @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). */ CB_GraphicSprites.prototype.setPointer = CB_GraphicSprites.prototype.setCurrentPosition = function(position, loop) { if (this.spritesGroup && this.spritesGroup.sprites && this.spritesGroup.sprites.length) { position = position || 0; if (loop) { if (position < 0) { position = position * -1; } //Converts it to a positive number. position %= this.spritesGroup.sprites.length; } else if (position < 0) { position = 0; } else if (position >= this.spritesGroup.sprites.length) { position = this.spritesGroup.sprites.length - 1; } if (this.pointer !== position) { this.pointer = position; this.setTime(undefined, true); } //Updates the pointer and "resets" the time. } return this.pointer || 0; } /** * Alias for {@link CB_GraphicSprites#getCurrent}. * @function CB_GraphicSprites#now * @see {@link CB_GraphicSprites#getCurrent} */ /** * Alias for {@link CB_GraphicSprites#getCurrent}. * @function CB_GraphicSprites#current * @see {@link CB_GraphicSprites#getCurrent} */ /** * 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). * @function * @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. */ CB_GraphicSprites.prototype.getCurrent = CB_GraphicSprites.prototype.current = CB_GraphicSprites.prototype.now = function() { return this.getSprite(this.getPointer(), null); } /** * Alias for {@link CB_GraphicSprites#getPrevious}. * @function CB_GraphicSprites#setPrevious * @see {@link CB_GraphicSprites#getPrevious} */ /** * Alias for {@link CB_GraphicSprites#getPrevious}. * @function CB_GraphicSprites#previous * @see {@link CB_GraphicSprites#getPrevious} */ /** * 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). * @function * @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. * @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. */ CB_GraphicSprites.prototype.getPrevious = CB_GraphicSprites.prototype.setPrevious = CB_GraphicSprites.prototype.previous = function(loop) { var pointer = this.getPointer() - 1; if (pointer < 0) { if (loop && this.spritesGroup && this.spritesGroup.sprites && this.spritesGroup.sprites.length) { pointer = this.spritesGroup.sprites.length + pointer; } else { return null; } } var sprite = this.getSprite(pointer, null); if (sprite !== null && this.pointer !== pointer) { this.pointer = pointer; this.setTime(undefined, true); } //Updates the pointer and "resets" the time. return sprite; } /** * Alias for {@link CB_GraphicSprites#getNext}. * @function CB_GraphicSprites#setNext * @see {@link CB_GraphicSprites#getNext} */ /** * Alias for {@link CB_GraphicSprites#getNext}. * @function CB_GraphicSprites#next * @see {@link CB_GraphicSprites#getNext} */ /** * 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). * @function * @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. * @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. */ CB_GraphicSprites.prototype.getNext = CB_GraphicSprites.prototype.setNext = CB_GraphicSprites.prototype.next = function(loop) { var pointer = this.getPointer() + 1; if (loop && this.spritesGroup && this.spritesGroup.sprites && this.spritesGroup.sprites.length) { pointer %= this.spritesGroup.sprites.length; } var sprite = this.getSprite(pointer, null); if (sprite !== null && this.pointer !== pointer) { this.pointer = pointer; this.setTime(undefined, true); } //Updates the pointer and "resets" the time. return sprite; } /** * 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. * @function * @returns {boolean} Returns whether the sprites group object (and the {@link CB_GraphicSprites} object itself) is disabled or not. */ CB_GraphicSprites.prototype.isDisabled = function() { return !!this.getSpritesGroup({}).disabled; } /** * 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. * @function * @param {boolean} [disabled=false] - Set to true to disable it or false to enable it. * @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. */ CB_GraphicSprites.prototype.setDisabled = function(disabled, affectChildren) { disabled = !!disabled; if (typeof(affectChildren) === "undefined" || affectChildren === null) { affectChildren = disabled; } this.spritesGroup = this.spritesGroup || {}; this.spritesGroup.disabled = disabled; if (affectChildren) { this.executeFunctionAll(function() { if (this.setDisabled && typeof(this.setDisabled) === "function") { this.setDisabled(disabled, true, false, false); } }); } } /** * 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. * @function * @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). * @returns {boolean} Returns whether the sprite is disabled or not. A sprite is considered disabled if its sprites group parent is also disabled. */ CB_GraphicSprites.prototype.isDisabledSprite = function(sprite) { sprite = sprite || this.getCurrent() || {}; return !!sprite.disabled || this.isDisabled(); } /** * Sets a given sprite disabled or enabled. Internally, it edits its "disabled" property. * @function * @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). * @param {boolean} [disabled=false] - Set to true to disable it or false to enable it. * @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. * @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. * @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. */ CB_GraphicSprites.prototype.setDisabledSprite = function(sprite, disabled, affectSubSprites, affectParent, affectParentChildren) { disabled = !!disabled; if (typeof(affectParentChildren) === "undefined" || affectParentChildren === null) { affectParentChildren = !disabled; } if (typeof(affectParent) === "undefined" || affectParent === null) { affectParent = affectParentChildren || !disabled; } sprite = sprite || this.getCurrent(); if (sprite) { sprite.disabled = disabled; if (typeof(affectSubSprites) === "undefined" || affectSubSprites === null) { affectSubSprites = disabled; } if (affectSubSprites) { if (typeof(sprite.executeFunctionAll) === "function") { sprite.executeFunctionAll(function() { if (this.setDisabled && typeof(this.setDisabled) === "function") { this.setDisabled(disabled, false, false); } }); } } if (affectParent && sprite && sprite.parent) { return this.setDisabled(disabled, affectParentChildren); //Disables/enables the sprites group parent (and also its children). } } } /** * 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). * @function * @param {CB_GraphicSprites.SUBSPRITE_OBJECT} subSprite - The {@link CB_GraphicSprites.SUBSPRITE_OBJECT} object which contains the sub-sprite. * @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). */ CB_GraphicSprites.prototype.isDisabledSubSprite = function(subSprite) { subSprite = subSprite || {}; return !!subSprite.disabled || this.isDisabledSprite(subSprite.parent || {}); } /** * Sets a given sub-sprite disabled or enabled. Internally, it edits its "disabled" property. * @function * @param {CB_GraphicSprites.SUBSPRITE_OBJECT} subSprite - The {@link CB_GraphicSprites.SUBSPRITE_OBJECT} object which contains the sub-sprite. * @param {boolean} [disabled=false] - Set to true to disable it or false to enable it. * @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 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. * @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. */ CB_GraphicSprites.prototype.setDisabledSubSprite = function(subSprite, disabled, affectParents, affectParentsChildren) { disabled = !!disabled; if (typeof(affectParentsChildren) === "undefined" || affectParentsChildren === null) { affectParentsChildren = !disabled; } if (typeof(affectParents) === "undefined" || affectParents === null) { affectParents = affectParentsChildren || !disabled; } if (subSprite) { subSprite.disabled = disabled; if (affectParents && subSprite.parent) { return this.setDisabledSprite(subSprite.parent, disabled, affectParentsChildren, true, affectParentsChildren); } } } /** * Sets (updates) the time in milliseconds when the current sprite started being pointed. * @function * @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). * @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). * @returns {number} Returns the time in milliseconds when the current 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). */ CB_GraphicSprites.prototype.setTime = function(time, updateTimeCurrentSprite) { time = parseFloat(time); time = !isNaN(time) && time >= 0 ? time : CB_Device.getTiming(); this.time = time; if (updateTimeCurrentSprite) { this.getSprite(this.getPointer(), {}).time = time; } return this.time; } /** * Gets the time in milliseconds when the current 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). * @function * @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. * @returns {number} Returns the time in milliseconds when the current 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". */ CB_GraphicSprites.prototype.getTime = function(returnValueOnFail) { return this.time || returnValueOnFail; } /** * Tells how many milliseconds elapsed since the current 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. * @function * @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). * @returns {number} Returns how many milliseconds elapsed since the current 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. */ CB_GraphicSprites.prototype.getTimeElapsed = function(timeToCompare) { timeToCompare = parseFloat(timeToCompare); timeToCompare = !isNaN(timeToCompare) && timeToCompare >= 0 ? timeToCompare : CB_Device.getTiming(); return timeToCompare - this.getTime(timeToCompare); }