new CB_GraphicSprites( [spritesGroup] [, byReference]) → {CB_GraphicSprites}
Class to manage a group of graphic sprites (2D or 3D).
Parameters:
Name | Type | Argument | Default | Description |
---|---|---|---|---|
spritesGroup |
CB_GraphicSprites.SPRITES_OBJECT |
<optional> |
Object with the desired sprites. The information will be used for the |
|
byReference |
boolean |
<optional> |
!!CB_GraphicSprites.SPRITES_OBJECT.byReference_DEFAULT
|
This value will be used as the default value when the "byReference" property is not given in the sprites ( |
- Source:
- To Do:
-
- 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).
- 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.
Returns:
Returns a new CB_GraphicSprites
object.
- Type
- CB_GraphicSprites
Members
-
byReference_DEFAULT :boolean
-
This value will be used as the default value when the "byReference" property is not given in the sprites (
CB_GraphicSprites.SPRITE_OBJECT
objects) or sub-sprites (CB_GraphicSprites.SUBSPRITE_OBJECT
objects).Type:
- boolean
-
<readonly> id :string|*
-
Identifier of the sprites group object (the "id" property of the
CB_GraphicSprites.SPRITES_OBJECT
stored in theCB_GraphicSprites#spritesGroup
property) and theCB_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).Type:
- string | *
- Default Value:
-
- 'CB_GraphicSprites_' + CB_GraphicSprites._idUnique++
- Source:
-
<constant> isSprites :boolean
-
Property which is always set to true to help identify this type of object.
Type:
- boolean
- Default Value:
-
- true
- Source:
-
<readonly> parent :*
-
Property pointing to or containing its parent. It could be a
CB_GraphicSpritesScene
object. It is the same as the "parent" property of theCB_GraphicSprites.SPRITES_OBJECT
stored in theCB_GraphicSprites#spritesGroup
property.Type:
- *
-
<readonly> pointer :integer
-
Pointer with the position of the current sprite (belongs to an index of the
CB_GraphicSprites#spritesGroup.sprites
array).Type:
- integer
-
<readonly> pointerPrevious :integer
-
Keeps the previous value of the
CB_GraphicSprites#pointer
property (if any).Type:
- integer
-
<readonly> spritesGroup :CB_GraphicSprites.SPRITES_OBJECT
-
Object with information about the sprites.
Type:
- Default Value:
-
- {}
- Source:
-
<readonly> time :integer
-
Stores the time in milliseconds when the current sprite was started being pointed (time elapsed since the time origin which will be obtained calling the
CB_Device.getTiming
function internally).Type:
- integer
-
<constant> type :string
-
Indicates the type of object (always "sprites").
Type:
- string
- Default Value:
-
- sprites
- Source:
-
<readonly> zIndex :number
-
Z-index of the sprites group object (the "zIndex" property of the
CB_GraphicSprites.SPRITES_OBJECT
stored in theCB_GraphicSprites#spritesGroup
property) and theCB_GraphicSprites
object itself (same one). To change the value of this property, use theCB_GraphicSprites#setZIndex
method (which will call theCB_GraphicSpritesScene#updateGraphicSpritesByZIndex
method internally if there is aCB_GraphicSpritesScene
parent object). Only numeric values which are not zero (0) are allowed.Type:
- number
- Default Value:
-
- CB_GraphicSprites.ZINDEX_DEFAULT
- Source:
-
<static, constant> HEIGHT_DEFAULT :number
-
Default "height" of the destiny. Unit agnostic.
Type:
- number
-
<static, constant> HEIGHT_SOURCE_DEFAULT :number
-
Default height ("srcHeight") of the original source. Unit agnostic.
Type:
- number
- Default Value:
-
- 32
- Source:
-
<static, constant> LEFT_DEFAULT :number
-
Default "left" (horizontal position) in the destiny. Unit agnostic.
Type:
- number
-
<static, constant> LEFT_SOURCE_DEFAULT :number
-
Default left ("srcLeft", horizontal position) in the original source. Unit agnostic.
Type:
- number
-
<static, constant> SRC_TYPES :object
-
Object with some "srcType". Each property of this object belong to one source type, having an integer as value which represents it. You can define more source types here.
Type:
- object
- Default Value:
-
- {"DEFAULT":0,"IMAGE":0,"TEXT":1,"SEGMENT":2,"PIXEL":3,"RECTANGLE":4,"CIRCLE":5,"ARC":6,"ELLIPSE":7,"TRIANGLE":8,"BEZIER_CURVE":9,"QUADRATIC_BEZIER_CURVE":10,"BITMAP":11,"MAP":12}
- Source:
-
<static, constant> SRC_TYPES_DEFAULT :integer
-
Default "srcType", the type of the original source.
Type:
- integer
- Default Value:
-
CB_GraphicSprites.SRC_TYPES.IMAGE
- Source:
-
<static, constant> TOP_DEFAULT :number
-
Default "top" (vertical position) in the destiny. Unit agnostic.
Type:
- number
-
<static, constant> TOP_SOURCE_DEFAULT :number
-
Default top ("srcTop", vertical position) in the original source. Unit agnostic.
Type:
- number
-
<static, constant> WIDTH_DEFAULT :number
-
Default "width" of the destiny. Unit agnostic.
Type:
- number
-
<static, constant> WIDTH_SOURCE_DEFAULT :number
-
Default width ("srcWidth") of the original source. Unit agnostic.
Type:
- number
- Default Value:
-
- 32
- Source:
-
<static, constant> ZINDEX_DEFAULT :number
-
Default "zIndex" in the destiny.
Type:
- number
- Default Value:
-
- 1
- Source:
-
<static, constant> filterProperties_DEFAULT_PROPERTIES :CB_GraphicSprites.filterProperties_propertiesToKeepObject_TYPE
-
Object used as the default value for the "propertiesToKeepObject" parameter if not provided when calling the
CB_GraphicSprites.filterProperties
function.Type:
- Default Value:
-
- {"spritesScene":"","spritesGroups":"","sprites":"","spritesGroup":"","sprite":"","subSprite":""}
- Source:
Methods
-
current()
-
Alias for
CB_GraphicSprites#getCurrent
. -
destructor()
-
Destroys the graphic sprites object (removing all the sprites and their sub-sprites, etc.) and frees memory.
-
executeAll()
-
Alias for
CB_GraphicSprites#executeFunctionAll
. -
executeFunctionAll(functionEach [, orderedByZIndex] [, delayBetweenEach] [, sprites] [, returnSetTimeoutsArray] [, delayBetweenEachAffectsFirst] [, functionFinish]) → {integer|array}
-
Performs a desired action, using the provided function, on all the existing sprites (
CB_GraphicSprites.SPRITE_OBJECT
objects) or on the desired ones (if provided). Calls theCB_Arrays.executeFunctionAll
function internally and returns its returning value.Parameters:
Name Type Argument Default Description functionEach
CB_Arrays.executeFunctionAll_ON_LOOP_CALLBACK Function that will be called for each sprite (
CB_GraphicSprites.SPRITE_OBJECT
object). As the first parameter it receives theCB_GraphicSprites.SPRITE_OBJECT
object of the "sprites" being looped, as the second parameter the position of thisCB_GraphicSprites.SPRITE_OBJECT
object in the "sprites" array provided (or, if not provided, in the array returned by theCB_GraphicSprites#getSprites
method), the third parameter is the array being looped and the fourth parameter will be the "delayBetweenEach" being used, being "this" theCB_GraphicSprites.SPRITE_OBJECT
object itself.orderedByZIndex
boolean <optional>
false If set to true, it will loop the sprites sorted by their z-index (ascending order).
delayBetweenEach
number | CB_Arrays.executeFunctionAll_ON_LOOP_CALLBACK <optional>
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 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
CB_GraphicSprites.SPRITE_OBJECT
object).sprites
array <optional>
CB_GraphicSprites#getSprites
()A numeric array containing the sprites (
CB_GraphicSprites.SPRITE_OBJECT
objects) that we want to loop. It should contain onlyCB_GraphicSprites.SPRITE_OBJECT
objects which are already in the currentCB_GraphicSprites
object. If not provided, it will use all theCB_GraphicSprites.SPRITE_OBJECT
objects contained in theCB_GraphicSprites
object.returnSetTimeoutsArray
boolean <optional>
false Defines whether we want the method to return an integer or a numeric array with information of each setTimeout call. Returning an array with information of each setTimeout call is only useful when the setTimeout function is called internally, which happens when the "delayBetweenEach" parameter is greater than 0 (zero).
delayBetweenEachAffectsFirst
boolean <optional>
false If set to true, the desired delay (if any) will also affect the first call to the "functionEach" function.
functionFinish
CB_Arrays.executeFunctionAll_ON_FINISH_CALLBACK <optional>
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.
- Source:
- To Do:
-
- Think about only allowing
CB_GraphicSprites.SPRITE_OBJECT
objects (in the "sprites" parameter) which are already in theCB_GraphicSprites
(identify them by their ID), to avoid problems.
- Think about only allowing
Returns:
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
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 aCB_Arrays.executeFunctionAll_OBJECT
object for eachCB_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 function.- Type
- integer | array
-
executeFunctionAllSubSprites(functionEach [, orderedByZIndex] [, delayBetweenEach] [, sprite] [, returnSetTimeoutsArray] [, delayBetweenEachAffectsFirst] [, functionFinish]) → {integer|array}
-
Performs a desired action, using the provided function, on all the existing sub-sprites (
CB_GraphicSprites.SUBSPRITE_OBJECT
objects) from a given sprite (CB_GraphicSprites.SPRITE_OBJECT
object). Calls theCB_Arrays.executeFunctionAll
function internally and returns its returning value.Parameters:
Name Type Argument Default Description functionEach
CB_Arrays.executeFunctionAll_ON_LOOP_CALLBACK Function that will be called for each sub-sprite (
CB_GraphicSprites.SUBSPRITE_OBJECT
object) from the given sprite (CB_GraphicSprites.SPRITE_OBJECT
object). As the first parameter it receives theCB_GraphicSprites.SUBSPRITE_OBJECT
object of the sub-sprites being looped, as the second parameter the position of thisCB_GraphicSprites.SUBSPRITE_OBJECT
object in the "subSprites" property of the sprite (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" theCB_GraphicSprites.SUBSPRITE_OBJECT
object itself.orderedByZIndex
boolean <optional>
false If set to true, it will loop the sub-sprites sorted by their z-index (ascending order).
delayBetweenEach
number | CB_Arrays.executeFunctionAll_ON_LOOP_CALLBACK <optional>
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 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
CB_GraphicSprites.SUBSPRITE_OBJECT
object).sprite
CB_GraphicSprites.SPRITE_OBJECT <optional>
CB_GraphicSprites#getCurrent() The
CB_GraphicSprites.SPRITE_OBJECT
object which contains the sprite and its sub-sprites. If not provided, it will use theCB_GraphicSprites.SPRITE_OBJECT
object which the pointer (set in theCB_GraphicSprites#pointer
property) is currently pointing to (using the returning value of theCB_GraphicSprites#getCurrent
method internally).returnSetTimeoutsArray
boolean <optional>
false Defines whether we want the method to return an integer or a numeric array with information of each setTimeout call. Returning an array with information of each setTimeout call is only useful when the setTimeout function is called internally, which happens when the "delayBetweenEach" parameter is greater than 0 (zero).
delayBetweenEachAffectsFirst
boolean <optional>
false If set to true, the desired delay (if any) will also affect the first call to the "functionEach" function.
functionFinish
CB_Arrays.executeFunctionAll_ON_FINISH_CALLBACK <optional>
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.
- Source:
- To Do:
-
- Think about only allowing
CB_GraphicSprites.SPRITE_OBJECT
objects (in the "sprite" parameter) which are already in theCB_GraphicSprites.SPRITE_OBJECT
(identify them by their ID), to avoid problems.
- Think about only allowing
Returns:
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
CB_GraphicSprites.SUBSPRITE_OBJECT
objects in the givenCB_GraphicSprites.SPRITE_OBJECT
object). Otherwise, if the "returnSetTimeoutsArray" is set to true, it will return a numeric array with aCB_Arrays.executeFunctionAll_OBJECT
object for eachCB_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 function.- Type
- integer | array
-
forEach()
-
Alias for
CB_GraphicSprites#executeFunctionAll
. -
forEachSprite()
-
Alias for
CB_GraphicSprites#executeFunctionAll
. -
get()
-
Alias for
CB_GraphicSprites#getSprite
. -
getAll()
-
Alias for
CB_GraphicSprites#getSprites
. -
getById()
-
Alias for
CB_GraphicSprites#getSpriteById
. -
getCopy( [avoidCopyingPointer] [, avoidCopyingTimes] [, clearReferences] [, filterProperties] [, propertiesToKeepObject]) → {CB_GraphicSprites}
-
Gets a new copy of this object with the same attributes (all sub-objects will be a copy, they will not use the same reference).
Parameters:
Name Type Argument Default Description avoidCopyingPointer
boolean <optional>
false If set to true, it will not copy the
CB_GraphicSprites#pointer
property of the object.avoidCopyingTimes
boolean <optional>
false If set to true, it will not copy neither the
CB_GraphicSprites#time
property property of the object nor the "time" property of each of its sprites (CB_GraphicSprites.SPRITE_OBJECT
objects).clearReferences
boolean <optional>
false If set to true, it will not copy neither the "container" nor the "parent" nor the "data.that" nor the "data.getThis" properties of any element. Useful to be able to stringify the object preventing the "TypeError: cyclic object value" error. When set to true, calls the
CB_GraphicSprites.clearReferences
function internally. If set to true and the "filterProperties" parameter is also set to true, theCB_GraphicSprites.filterProperties
will always be called before calling theCB_GraphicSprites.clearReferences
function.filterProperties
boolean <optional>
false If set to true, it will call the
CB_GraphicSprites.filterProperties
function internally to filter the properties that we do not want to keep (using the given "propertiesToKeepObject" as the parameter to call it). When set to true, calls theCB_GraphicSprites.filterProperties
function internally. If set to true and the "clearReferences" parameter is also set to true, theCB_GraphicSprites.filterProperties
will always be called before calling theCB_GraphicSprites.clearReferences
function.propertiesToKeepObject
CB_GraphicSprites.filterProperties_propertiesToKeepObject_TYPE <optional>
CB_GraphicSprites.filterProperties_DEFAULT_PROPERTIES The object with the properties that we want to keep. Only used when the "filterProperties" parameter is set to true, as the "propertiesToKeepObject" when calling the
CB_GraphicSprites.filterProperties
function internally.Returns:
Returns a copy of this object with the same attributes (all sub-objects will be a copy, not the same reference).
- Type
- CB_GraphicSprites
-
getCurrent() → {CB_GraphicSprites.SPRITE_OBJECT|null}
-
Gets the sprite (a
CB_GraphicSprites.SPRITE_OBJECT
object) which is being currently pointed (by the pointer set in theCB_GraphicSprites#pointer
property).Returns:
Returns the
CB_GraphicSprites.SPRITE_OBJECT
object which is currently pointed by the pointer (set in theCB_GraphicSprites#pointer
property). Returns null if not found.- Type
- CB_GraphicSprites.SPRITE_OBJECT | null
-
getCurrentPosition()
-
Alias for
CB_GraphicSprites#getPointer
. -
getIndexById()
-
Alias for
CB_GraphicSprites#getSpriteIndexById
. -
getPointer() → {integer}
-
Gets the current position of the pointer. It belongs to an index of the
CB_GraphicSprites#spritesGroup.sprites
array where aCB_GraphicSprites.SPRITE_OBJECT
object is placed (containing a sprite). Internally, it uses theCB_GraphicSprites#pointer
property.Returns:
Returns the position where the pointer is currently pointing to. It belongs to an index of the
CB_GraphicSprites#spritesGroup.sprites
array where aCB_GraphicSprites.SPRITE_OBJECT
object is placed (containing a sprite). If not found, returns zero (0) by default.- Type
- integer
-
getPointerPrevious() → {integer}
-
Gets the previous position of the pointer. It belongs to an index of the
CB_GraphicSprites#spritesGroup.sprites
array where aCB_GraphicSprites.SPRITE_OBJECT
object is placed (containing a sprite). Internally, it uses theCB_GraphicSprites#pointerPrevious
property.Returns:
Returns the position where the pointer was previously pointing to. It belongs to an index of the
CB_GraphicSprites#spritesGroup.sprites
array where aCB_GraphicSprites.SPRITE_OBJECT
object is placed (containing a sprite). If not found, returns -1 by default.- Type
- integer
-
getPrevious() → {CB_GraphicSprites.SPRITE_OBJECT|null}
-
Gets the sprite (a
CB_GraphicSprites.SPRITE_OBJECT
object) which was previously pointed (by the previous value of the pointer set in theCB_GraphicSprites#pointer
property, whose value is now in theCB_GraphicSprites#pointerPrevious
property).Returns:
Returns the
CB_GraphicSprites.SPRITE_OBJECT
object which was previously pointed by the pointer (by the previous value of the pointer set in theCB_GraphicSprites#pointer
property, whose value is now in theCB_GraphicSprites#pointerPrevious
property). Returns null if not found.- Type
- CB_GraphicSprites.SPRITE_OBJECT | null
-
getPreviousPosition()
-
Alias for
CB_GraphicSprites#getPointerPrevious
. -
getSprite( [index] [, returnValueOnFail]) → {CB_GraphicSprites.SPRITE_OBJECT|*}
-
Gets a desired sprite object through its index (its position in the
CB_GraphicSprites#spritesGroup.sprites
array). Faster than getting it through its identifier with theCB_GraphicSprites#getSpriteById
method.Parameters:
Name Type Argument Default Description index
integer <optional>
0 The index where the desired sprite must be located (its position in the
CB_GraphicSprites#spritesGroup.sprites
array).returnValueOnFail
* <optional>
The value we want it to return in the case that no value is found. If not provided, undefined will be returned.
Returns:
Returns a
CB_GraphicSprites.SPRITE_OBJECT
object if found or the value of "returnValueOnFail" otherwise.- Type
- CB_GraphicSprites.SPRITE_OBJECT | *
-
getSpriteById( [id] [, returnValueOnFail]) → {CB_GraphicSprites.SPRITE_OBJECT|*}
-
Gets a desired sprite object through its identifier. Slower than getting it through its index with the
CB_GraphicSprites#getSprite
method.Parameters:
Name Type Argument Description id
string | * <optional>
The identifier of the sprite that we want to get.
returnValueOnFail
* <optional>
The value we want it to return in the case that no value is found. If not provided, undefined will be returned.
Returns:
Returns a
CB_GraphicSprites.SPRITE_OBJECT
object if found or the value of "returnValueOnFail" otherwise.- Type
- CB_GraphicSprites.SPRITE_OBJECT | *
-
getSpriteIndexById( [id]) → {integer}
-
Gets the index (the position in the
CB_GraphicSprites#spritesGroup.sprites
array) of a desired sprite by its identifier.Parameters:
Name Type Argument Description id
string | * <optional>
The identifier of the sprite whose index we want to get.
- Source:
- To Do:
-
- Optimize it (perhaps using a cache matching the IDs with their position, maybe using the "position" or "positionByZIndex" properties).
Returns:
Returns the index (the position in the
CB_GraphicSprites#spritesGroup.sprites
array) of the desired sprite or -1 if not found.- Type
- integer
-
getSprites( [orderedByZIndex] [, returnValueOnFail]) → {array|*}
-
Gets all the sprites (the "sprites" property of the internal
CB_GraphicSprites.SPRITES_OBJECT
object, if any).Parameters:
Name Type Argument Default Description orderedByZIndex
boolean <optional>
false If set to true, it will return the sprites sorted by their z-index (ascending order).
returnValueOnFail
* <optional>
The value we want it to return in the case that no value is found. If not provided, undefined will be returned.
Returns:
Returns an array with all the
CB_GraphicSprites.SPRITE_OBJECT
objects or the value of "returnValueOnFail" otherwise.- Type
- array | *
-
getSpritesAll()
-
Alias for
CB_GraphicSprites#getSprites
. -
getSpritesGroup( [returnValueOnFail]) → {CB_GraphicSprites.SPRITES_OBJECT|*}
-
Gets the sprites group object (the internal
CB_GraphicSprites.SPRITES_OBJECT
object, if any).Parameters:
Name Type Argument Description returnValueOnFail
* <optional>
The value we want it to return in the case that no value is found. If not provided, undefined will be returned.
Returns:
Returns a
CB_GraphicSprites.SPRITES_OBJECT
object with all the sprites or the value of "returnValueOnFail" otherwise.- Type
- CB_GraphicSprites.SPRITES_OBJECT | *
-
getSubSprite( [index] [, sprite] [, returnValueOnFail]) → {CB_GraphicSprites.SUBSPRITE_OBJECT|*}
-
Gets a desired sub-sprite object through its index (its position in the array which is in the "subSprites" property of the given
CB_GraphicSprites.SPRITE_OBJECT
object). Faster than getting it through its identifier with theCB_GraphicSprites#getSubSpriteById
method.Parameters:
Name Type Argument Default Description index
integer <optional>
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
CB_GraphicSprites.SPRITE_OBJECT
object).sprite
CB_GraphicSprites.SPRITE_OBJECT <optional>
CB_GraphicSprites#getCurrent() The
CB_GraphicSprites.SPRITE_OBJECT
object which contains the sprite and its sub-sprites. If not provided, it will use theCB_GraphicSprites.SPRITE_OBJECT
object which the pointer (set in theCB_GraphicSprites#pointer
property) is currently pointing to (using the returning value of theCB_GraphicSprites#getCurrent
method internally).returnValueOnFail
* <optional>
The value we want it to return in the case that no value is found. If not provided, undefined will be returned.
Returns:
Returns a
CB_GraphicSprites.SUBSPRITE_OBJECT
object if found or the value of "returnValueOnFail" otherwise.- Type
- CB_GraphicSprites.SUBSPRITE_OBJECT | *
-
getSubSpriteById( [id] [, sprite] [, returnValueOnFail]) → {CB_GraphicSprites.SUBSPRITE_OBJECT|*}
-
Gets a desired sub-sprite object through its identifier from the given
CB_GraphicSprites.SPRITE_OBJECT
object. Slower than getting it through its index with theCB_GraphicSprites#getSubSprite
method.Parameters:
Name Type Argument Default Description id
string | * <optional>
The identifier of the sub-sprite that we want to get.
sprite
CB_GraphicSprites.SPRITE_OBJECT <optional>
CB_GraphicSprites#getCurrent() The
CB_GraphicSprites.SPRITE_OBJECT
object which contains the sprite and its sub-sprites. If not provided, it will use theCB_GraphicSprites.SPRITE_OBJECT
object which the pointer (set in theCB_GraphicSprites#pointer
property) is currently pointing to (using the returning value of theCB_GraphicSprites#getCurrent
method internally).returnValueOnFail
* <optional>
The value we want it to return in the case that no value is found. If not provided, undefined will be returned.
Returns:
Returns a
CB_GraphicSprites.SUBSPRITE_OBJECT
object if found or the value of "returnValueOnFail" otherwise.- Type
- CB_GraphicSprites.SUBSPRITE_OBJECT | *
-
getSubSpriteIndexById( [id] [, sprite]) → {integer}
-
Gets the index (its position in the array which is in the "subSprites" property of the given
CB_GraphicSprites.SPRITE_OBJECT
object) of a desired sub-sprite by its identifier.Parameters:
Name Type Argument Default Description id
string | * <optional>
The identifier of the sub-sprite whose index we want to get.
sprite
CB_GraphicSprites.SPRITE_OBJECT <optional>
CB_GraphicSprites#getCurrent() The
CB_GraphicSprites.SPRITE_OBJECT
object which contains the sprite and its sub-sprites. If not provided, it will use theCB_GraphicSprites.SPRITE_OBJECT
object which the pointer (set in theCB_GraphicSprites#pointer
property) is currently pointing to (using the returning value of theCB_GraphicSprites#getCurrent
method internally).- Source:
- To Do:
-
- Optimize it (perhaps using a cache matching the IDs with their position, maybe using the "position" or "positionByZIndex" properties).
Returns:
Returns the index (its position in the array which is in the "subSprites" property of the given
CB_GraphicSprites.SPRITE_OBJECT
object) of the desired sub-sprite or -1 if not found.- Type
- integer
-
getSubSprites( [sprite] [, orderedByZIndex] [, returnValueOnFail]) → {array|*}
-
Gets an array with all the
CB_GraphicSprites.SUBSPRITE_OBJECT
objects of a givenCB_GraphicSprites.SPRITE_OBJECT
object.Parameters:
Name Type Argument Default Description sprite
CB_GraphicSprites.SPRITE_OBJECT <optional>
CB_GraphicSprites#getCurrent() The
CB_GraphicSprites.SPRITE_OBJECT
object which contains the sprite and its sub-sprites. If not provided, it will use theCB_GraphicSprites.SPRITE_OBJECT
object which the pointer (set in theCB_GraphicSprites#pointer
property) is currently pointing to (using the returning value of theCB_GraphicSprites#getCurrent
method internally).orderedByZIndex
boolean <optional>
false If set to true, it will return the sub-sprites sorted by their z-index (ascending order).
returnValueOnFail
* <optional>
The value we want it to return in the case that no value is found. If not provided, undefined will be returned.
Returns:
Returns an array with all the
CB_GraphicSprites.SUBSPRITE_OBJECT
objects of the givenCB_GraphicSprites.SPRITE_OBJECT
object or the value of "returnValueOnFail" otherwise.- Type
- array | *
-
getTime( [returnValueOnFail] [, parentTimeFallback]) → {number}
-
Gets the time in milliseconds when the current sprite or a sub-sprite started being pointed (time elapsed since the time origin which was obtained calling the
CB_Device.getTiming
function internally).Parameters:
Name Type Argument Default Description returnValueOnFail
* <optional>
The value we want it to return in the case that no value is found. If not provided, undefined will be returned.
parentTimeFallback
boolean <optional>
false If the "time" property of "this" is not found, it will try to get the "time" property of "this.time" before returning "returnValueOnFail".
Returns:
Returns the time in milliseconds when the current sprite or a sub-sprite started being pointed (time elapsed since the time origin which was obtained calling the
CB_Device.getTiming
function internally). If it could not be found, it will return "returnValueOnFail".- Type
- number
-
getTimeElapsed( [timeToCompare] [, parentTimeFallback]) → {number}
-
Tells how many milliseconds elapsed since the current sprite or a sub-sprite was or will be pointed (checking the
CB_GraphicSprites#time
property), comparing with the time given in milliseconds (time elapsed since the time origin which can be obtained calling theCB_Device.getTiming
function) or with the current one if none is given.Parameters:
Name Type Argument Default Description timeToCompare
number <optional>
CB_Device.getTiming() The time (time elapsed since the time origin which can obtained calling the
CB_Device.getTiming
function) that we want to compare to (normally, it will be a newer time than the one stored in theCB_GraphicSprites#time
property). It must be a positive number (or zero). If not provided, it will use the current time (by calling theCB_Device.getTiming
function internally).parentTimeFallback
boolean <optional>
false If the "time" property of "this" is not found, it will try to get the "time" property of "this.time" before using "returnValueOnFail".
Returns:
Returns how many milliseconds elapsed since the current sprite or a sub-sprite was or will be pointed, comparing with the time given (in milliseconds) or with the current one if none was given. This is just the given "timeToCompare" minus the returning value of calling the
CB_GraphicSprites#getTime
method.- Type
- number
-
getZIndex( [returnValueOnFail]) → {number}
-
Gets the z-index ("zIndex" property) of the sprites group object (and the {@CB_GraphicSprites} object itself).
Parameters:
Name Type Argument Description returnValueOnFail
* <optional>
The value we want it to return in the case that no value is found. If not provided, undefined will be returned.
Returns:
Returns the z-index ("zIndex") of the sprites group object (and the {@CB_GraphicSprites} object itself). If not found, returns the value of the
CB_GraphicSprites.ZINDEX_DEFAULT
property of evaluates to true or "returnValueOnFail" otherwise.- Type
- number
-
getZIndexSprite( [sprite] [, returnValueOnFail]) → {number}
-
Gets the z-index ("zIndex" property) of a given sprite object.
Parameters:
Name Type Argument Default Description sprite
CB_GraphicSprites.SPRITE_OBJECT <optional>
CB_GraphicSprites#getCurrent() The
CB_GraphicSprites.SPRITE_OBJECT
object which contains the sprite. If not provided, it will use theCB_GraphicSprites.SPRITE_OBJECT
object which the pointer (set in theCB_GraphicSprites#pointer
property) is currently pointing to (using the returning value of theCB_GraphicSprites#getCurrent
method internally).returnValueOnFail
* <optional>
The value we want it to return in the case that no value is found. If not provided, undefined will be returned.
Returns:
Returns the z-index ("zIndex") of the given sprite. If not found, returns the value of the
CB_GraphicSprites.ZINDEX_DEFAULT
property of evaluates to true or "returnValueOnFail" otherwise.- Type
- number
-
getZIndexSubSprite(subSprite [, returnValueOnFail]) → {number}
-
Gets the z-index ("zIndex" property) of a given sub-sprite object.
Parameters:
Name Type Argument Description subSprite
CB_GraphicSprites.SUBSPRITE_OBJECT The
CB_GraphicSprites.SUBSPRITE_OBJECT
object which contains the sub-sprite.returnValueOnFail
* <optional>
The value we want it to return in the case that no value is found. If not provided, undefined will be returned.
Returns:
Returns the z-index ("zIndex") of the given sub-sprite. If not found, returns the value of the
CB_GraphicSprites.ZINDEX_DEFAULT
property of evaluates to true or "returnValueOnFail" otherwise.- Type
- number
-
insert()
-
Alias for
CB_GraphicSprites#insertSprite
. -
insertSprite( [sprite] [, avoidUpdatingSpritesByZIndex]) → {CB_GraphicSprites.SPRITE_OBJECT}
-
Adds the desired graphic sprite. Calls
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.Parameters:
Name Type Argument Default Description sprite
CB_GraphicSprites.SPRITE_OBJECT <optional>
Object with the desired sprite. It will be stored inside the
CB_GraphicSprites#spritesGroup
property.avoidUpdatingSpritesByZIndex
boolean <optional>
false If set to true, it will not call the {CB_GraphicSprites#updateSpritesByZIndex} method internally. Internal usage recommended only.
Returns:
Returns the
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). -
insertSprites( [spritesGroup] [, byReference]) → {CB_GraphicSprites.SPRITES_OBJECT}
-
Adds the desired group of graphic sprites. Calls the
CB_GraphicSprites#insertSprite
andCB_GraphicSprites#updateSpritesByZIndex
methods internally.Parameters:
Name Type Argument Default Description spritesGroup
CB_GraphicSprites.SPRITES_OBJECT <optional>
Object with the desired sprites. They will be stored in the
CB_GraphicSprites#spritesGroup
property.byReference
boolean <optional>
!! CB_GraphicSprites.SPRITES_OBJECT.byReference_DEFAULT
This value will be used as the default value when the "byReference" property is not given in the sprites (
CB_GraphicSprites.SPRITE_OBJECT
objects) or sub-sprites (CB_GraphicSprites.SUBSPRITE_OBJECT
objects). The value will be stored in theCB_GraphicSprites#byReference_DEFAULT
property. If a boolean value is not provided, it will use the value of theCB_GraphicSprites.SPRITES_OBJECT.byReference_DEFAULT
property of the givenCB_GraphicSprites.SPRITES_OBJECT
object (parsed to boolean).Returns:
Returns the
CB_GraphicSprites#spritesGroup
property after updating it. -
insertSpritesGroup()
-
Alias for
CB_GraphicSprites#insertSprites
. -
insertSubSprite(subSprite, sprite [, avoidUpdatingSubSpritesByZIndex]) → {CB_GraphicSprites.SUBSPRITE_OBJECT}
-
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.
Parameters:
Name Type Argument Default Description subSprite
CB_GraphicSprites.SUBSPRITE_OBJECT Object with the desired sub-sprite. It will be stored inside the given sprite.
sprite
CB_GraphicSprites.SPRITE_OBJECT Object with the desired sprite.
avoidUpdatingSubSpritesByZIndex
boolean <optional>
false If set to true, it will not call the {CB_GraphicSprites#updateSubSpritesByZIndex} method internally. Internal usage recommended only.
Returns:
Returns the
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). -
insertSubSprites(subSprites [, sprite]) → {array}
-
Adds the given sub-sprites to the desired sprite. Calls the
CB_GraphicSprites#insertSubSprite
andCB_GraphicSprites#updateSubSpritesByZIndex
methods internally.Parameters:
Name Type Argument Default Description subSprites
array Numeric array with the desired sub-sprites (
CB_GraphicSprites.SUBSPRITE_OBJECT
objects). They will be stored inside the given sprite. If a value which is not an array is provided, it will be tried to be processed internally as the first and unique value of an array.sprite
CB_GraphicSprites.SPRITE_OBJECT <optional>
CB_GraphicSprites#getCurrent() Object with the desired sprite. If not provided, it will use the
CB_GraphicSprites.SPRITE_OBJECT
object which the pointer (set in theCB_GraphicSprites#pointer
property) is currently pointing to (using the returning value of theCB_GraphicSprites#getCurrent
method internally).Returns:
Returns an array with the
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).- Type
- array
-
isDisabled() → {boolean}
-
Tells whether the sprites group object (and the {@CB_GraphicSprites} object itself) is disabled or not. Internally, it checks the "
CB_GraphicSprites.spritesGroup
.disabled" property.Returns:
Returns whether the sprites group object (and the
CB_GraphicSprites
object itself) is disabled or not.- Type
- boolean
-
isDisabledSprite( [sprite]) → {boolean}
-
Tells whether the given sprite is disabled or not. Internally, it checks its "disabled" property and also the "
CB_GraphicSprites.spritesGroup
.disabled" property (calling theCB_GraphicSprites#isDisabled
method internally). A sprite is considered disabled if its sprites group parent is also disabled.Parameters:
Name Type Argument Default Description sprite
CB_GraphicSprites.SPRITE_OBJECT <optional>
CB_GraphicSprites#getCurrent() The
CB_GraphicSprites.SPRITE_OBJECT
object which contains the sprite. If not provided, it will use theCB_GraphicSprites.SPRITE_OBJECT
object which the pointer (set in theCB_GraphicSprites#pointer
property) is currently pointing to (using the returning value of theCB_GraphicSprites#getCurrent
method internally).Returns:
Returns whether the sprite is disabled or not. A sprite is considered disabled if its sprites group parent is also disabled.
- Type
- boolean
-
isDisabledSubSprite(subSprite) → {boolean}
-
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
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).Parameters:
Name Type Description subSprite
CB_GraphicSprites.SUBSPRITE_OBJECT The
CB_GraphicSprites.SUBSPRITE_OBJECT
object which contains the sub-sprite.Returns:
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).
- Type
- boolean
-
next()
-
Alias for
CB_GraphicSprites#setNext
. -
now()
-
Alias for
CB_GraphicSprites#getCurrent
. -
previous()
-
Alias for
CB_GraphicSprites#setPrevious
. -
remove()
-
Alias for
CB_GraphicSprites#removeSprite
. -
removeAll()
-
Alias for
CB_GraphicSprites#removeSprites
. -
removeById()
-
Alias for
CB_GraphicSprites#removeSpriteById
. -
removeSprite( [index]) → {boolean}
-
Removes a sprite by its index (its position in the
CB_GraphicSprites#spritesGroup.sprites
array). Calls theCB_GraphicSprites#updateSpritesByZIndex
method internally.Parameters:
Name Type Argument Default Description index
integer <optional>
0 The index where the sprite is located (its position in the
CB_GraphicSprites#spritesGroup.sprites
array).Returns:
Returns true if the sprite has been deleted or false otherwise.
- Type
- boolean
-
removeSpriteById( [id]) → {boolean}
-
Removes a sprite by its identifier. Calls the
CB_GraphicSprites#updateSpritesByZIndex
method internally.Parameters:
Name Type Argument Description id
string | * <optional>
The identifier of the sprite.
- Source:
- To Do:
-
- Optimize it (perhaps using a cache matching the IDs with their position, maybe using the "position" or "positionByZIndex" properties).
Returns:
Returns true if the sprite has been deleted or false otherwise.
- Type
- boolean
-
removeSprites()
-
Removes all the sprites by clearing the
CB_GraphicSprites#spritesGroup
property. -
removeSpritesAll()
-
Alias for
CB_GraphicSprites#removeSprites
. -
removeSpritesGroup()
-
Alias for
CB_GraphicSprites#removeSprites
. -
removeSubSprite( [index] [, sprite]) → {boolean}
-
Removes a sub-sprite from a given sprite (
CB_GraphicSprites.SPRITE_OBJECT
object) by its index (its position in the array which is in the "subSprites" property of the givenCB_GraphicSprites.SPRITE_OBJECT
object). Calls theCB_GraphicSprites#updateSubSpritesByZIndex
method internally.Parameters:
Name Type Argument Default Description index
integer <optional>
0 The index where the sub-sprite is located (its position in the array which is in the "subSprites" property of the given
CB_GraphicSprites.SPRITE_OBJECT
object).sprite
CB_GraphicSprites.SPRITE_OBJECT <optional>
CB_GraphicSprites#getCurrent() Object with the sprite whose sub-sprites we want to remove. If not provided, it will use the
CB_GraphicSprites.SPRITE_OBJECT
object which the pointer (set in theCB_GraphicSprites#pointer
property) is currently pointing to (using the returning value of theCB_GraphicSprites#getCurrent
method internally).Returns:
Returns true if the sub-sprite has been deleted or false otherwise.
- Type
- boolean
-
removeSubSpriteById( [id] [, sprite]) → {boolean}
-
Removes a sub-sprite from a given sprite (
CB_GraphicSprites.SPRITE_OBJECT
object) by its identifier. Calls theCB_GraphicSprites#updateSubSpritesByZIndex
method internally.Parameters:
Name Type Argument Default Description id
string | * <optional>
The identifier of the sprite.
sprite
CB_GraphicSprites.SPRITE_OBJECT <optional>
CB_GraphicSprites#getCurrent Object with the sprite whose sub-sprites we want to remove.
- Source:
- To Do:
-
- Optimize it (perhaps using a cache matching the IDs with their position, maybe using the "position" or "positionByZIndex" properties).
Returns:
Returns true if the sub-sprite has been deleted or false otherwise.
- Type
- boolean
-
removeSubSprites( [sprite]) → {boolean}
-
Removes all the sub-sprites from a given sprite (
CB_GraphicSprites.SPRITE_OBJECT
object) by clearing its "subSprites" property (leaving an empty array).Parameters:
Name Type Argument Default Description sprite
CB_GraphicSprites.SPRITE_OBJECT <optional>
CB_GraphicSprites#getCurrent() Object with the sprite whose sub-sprites we want to remove. If not provided, it will use the
CB_GraphicSprites.SPRITE_OBJECT
object which the pointer (set in theCB_GraphicSprites#pointer
property) is currently pointing to (using the returning value of theCB_GraphicSprites#getCurrent
method internally).Returns:
Returns true if the sub-sprites have been deleted or false otherwise.
- Type
- boolean
-
removeSubSpritesAll()
-
Alias for
CB_GraphicSprites#removeSubSprites
. -
setCurrentPosition()
-
Alias for
CB_GraphicSprites#setPointer
. -
setDisabled( [disabled] [, affectChildren])
-
Sets whether the sprites group object (and the {@CB_GraphicSprites} object itself) is disabled or enabled. Internally, it edits the "
CB_GraphicSprites.spritesGroup
.disabled" property.Parameters:
Name Type Argument Default Description disabled
boolean <optional>
false Set to true to disable it or false to enable it.
affectChildren
boolean <optional>
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.
-
setDisabledSprite( [sprite] [, disabled] [, affectSubSprites] [, affectParent] [, affectParentChildren])
-
Sets a given sprite disabled or enabled. Internally, it edits its "disabled" property.
Parameters:
Name Type Argument Default Description sprite
CB_GraphicSprites.SPRITE_OBJECT <optional>
CB_GraphicSprites#getCurrent() The
CB_GraphicSprites.SPRITE_OBJECT
object which contains the sprite. If not provided, it will use theCB_GraphicSprites.SPRITE_OBJECT
object which the pointer (set in theCB_GraphicSprites#pointer
property) is currently pointing to (using the returning value of theCB_GraphicSprites#getCurrent
method internally).disabled
boolean <optional>
false Set to true to disable it or false to enable it.
affectSubSprites
boolean <optional>
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
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.affectParent
boolean <optional>
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.
affectParentChildren
boolean <optional>
!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
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. -
setDisabledSubSprite(subSprite [, disabled] [, affectParents] [, affectParentsChildren])
-
Sets a given sub-sprite disabled or enabled. Internally, it edits its "disabled" property.
Parameters:
Name Type Argument Default Description subSprite
CB_GraphicSprites.SUBSPRITE_OBJECT The
CB_GraphicSprites.SUBSPRITE_OBJECT
object which contains the sub-sprite.disabled
boolean <optional>
false Set to true to disable it or false to enable it.
affectParents
boolean <optional>
affectParentsChildren|!disabled If this parameter is set to true, it will also modify the "disabled" property of the sprite parent and of the sprites group object (which is considered the status of the whole {@CB_GraphicSprites} object). By default, it is true if either the "affectParentChildren" parameter is set to true or the "disabled" parameter is set to false and it is false otherwise.
affectParentsChildren
boolean <optional>
!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
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. -
setNext( [loop]) → {CB_GraphicSprites.SPRITE_OBJECT|null}
-
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
CB_GraphicSprites#spritesGroup.sprites
array where aCB_GraphicSprites.SPRITE_OBJECT
object is placed (containing a sprite) and it will be returned if found. Internally, it modifies theCB_GraphicSprites#pointer
property (if possible). If the position was updated, it will also update theCB_GraphicSprites#time
property (setting the current time in milliseconds).Parameters:
Name Type Argument Default Description loop
boolean <optional>
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:
Makes it to point to the next
CB_GraphicSprites.SPRITE_OBJECT
object (making it the current one) and returns it. Returns null if it cannot be found.- Type
- CB_GraphicSprites.SPRITE_OBJECT | null
-
setPointer( [position] [, loop]) → {integer}
-
Sets the pointer to the desired position (if possible). The position should belong to an index of the
CB_GraphicSprites#spritesGroup.sprites
array where aCB_GraphicSprites.SPRITE_OBJECT
object is placed (containing a sprite). Internally, it modifies theCB_GraphicSprites#pointer
property (if possible). If the position was updated, it will also reset theCB_GraphicSprites#time
property (setting the current time in milliseconds).Parameters:
Name Type Argument Default Description position
integer <optional>
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
CB_GraphicSprites#spritesGroup.sprites
array where aCB_GraphicSprites.SPRITE_OBJECT
object is placed (containing a sprite).loop
boolean <optional>
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:
Returns the position where the pointer is currently pointing to. It belongs to an index of the
CB_GraphicSprites#spritesGroup.sprites
array where aCB_GraphicSprites.SPRITE_OBJECT
object is placed (containing a sprite).- Type
- integer
-
setPrevious( [loop]) → {CB_GraphicSprites.SPRITE_OBJECT|null}
-
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
CB_GraphicSprites#spritesGroup.sprites
array where aCB_GraphicSprites.SPRITE_OBJECT
object is placed (containing a sprite) and it will be returned if found. Internally, it modifies theCB_GraphicSprites#pointer
property (if possible). If the position was updated, it will update also theCB_GraphicSprites#time
property (setting the current time in milliseconds).Parameters:
Name Type Argument Default Description loop
boolean <optional>
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:
Makes it to point to the previous
CB_GraphicSprites.SPRITE_OBJECT
object (making it the current one) and returns it. Returns null if it cannot be found.- Type
- CB_GraphicSprites.SPRITE_OBJECT | null
-
setPropertyCascade(propertyName [, value] [, onlyCurrent]) → {integer}
-
Sets the desired value of a given property name to the
CB_GraphicSprites.SPRITES_OBJECT
object as well to its children elements (CB_GraphicSprites.SPRITE_OBJECT
andCB_GraphicSprites.SUBSPRITE_OBJECT
objects).Parameters:
Name Type Argument Default Description propertyName
number The name of the property we want to affect.
value
* <optional>
The value desired for the given property.
onlyCurrent
boolean <optional>
false If set to true, it will only affect the current sprite and its sub-sprites (and also the
CB_GraphicSprites.SPRITES_OBJECT
object).Returns:
Returns the number of elements affected (counting the
CB_GraphicSprites.SPRITES_OBJECT
object).- Type
- integer
-
setTime( [time] [, updateTimeCurrentSprite] [, updateTimeCurrentSpriteSubSprites]) → {number}
-
Sets (updates) the time in milliseconds when the current sprite or a sub-sprite started being pointed.
Parameters:
Name Type Argument Default Description time
number <optional>
CB_Device.getTiming() The time that we want to set, in milliseconds (time elapsed since the time origin which can be obtained calling the
CB_Device.getTiming
function). It must be a positive number (or zero). If not provided, it will use the current time (by calling theCB_Device.getTiming
function internally).updateTimeCurrentSprite
boolean <optional>
false If set to true, it will also update the "time" property of the
CB_GraphicSprites.SPRITE_OBJECT
object which is currently pointed by the pointer (set in theCB_GraphicSprites#pointer
property).updateTimeCurrentSpriteSubSprites
boolean <optional>
false If set to true and the "updateTimeCurrentSprite" is set to true, it will also update the "time" property of the
CB_GraphicSprites.SUBSPRITE_OBJECT
objects that belong to the sprite which is currently pointed by the pointer (set in theCB_GraphicSprites#pointer
property). This parameter is ignored if the "updateTimeCurrentSprite" parameter is set to false.Returns:
Returns the time in milliseconds when the current sprite or a sub-sprite started being pointed (time elapsed since the time origin which can be obtained calling the
CB_Device.getTiming
function).- Type
- number
-
setZIndex( [zIndex]) → {number}
-
Sets the desired z-index ("zIndex" property) of the sprites group object (and the {@CB_GraphicSprites} object itself). If there is a
CB_GraphicSpritesScene
parent object (set in theCB_GraphicSprites.parent
property), it will also call itsCB_GraphicSpritesScene#updateGraphicSpritesByZIndex
method internally.Parameters:
Name Type Argument Default Description zIndex
number <optional>
parseFloat(zIndex)||CB_GraphicSprites.ZINDEX_DEFAULT||1 The z-index value we want. It must be a number but never zero (0). If no valid number is given, it will use the value of the
CB_GraphicSprites.ZINDEX_DEFAULT
property of evaluates to true or 1 otherwise.Returns:
Returns the z-index ("zIndex") of the sprites group object (and the {@CB_GraphicSprites} object itself) after setting it (it could have been sanitized).
- Type
- number
-
setZIndexSprite( [sprite] [, zIndex]) → {number}
-
Sets the desired z-index ("zIndex") of the given sprite object. Calls the
CB_GraphicSprites#updateSpritesByZIndex
method internally.Parameters:
Name Type Argument Default Description sprite
CB_GraphicSprites.SPRITE_OBJECT <optional>
CB_GraphicSprites#getCurrent() The
CB_GraphicSprites.SPRITE_OBJECT
object which contains the sprite. If not provided, it will use theCB_GraphicSprites.SPRITE_OBJECT
object which the pointer (set in theCB_GraphicSprites#pointer
property) is currently pointing to (using the returning value of theCB_GraphicSprites#getCurrent
method internally).zIndex
number <optional>
parseFloat(zIndex)||CB_GraphicSprites.ZINDEX_DEFAULT||1 The z-index value we want. It must be a number but never zero (0). If no valid number is given, it will use the value of the
CB_GraphicSprites.ZINDEX_DEFAULT
property of evaluates to true or 1 otherwise.Returns:
Returns the z-index ("zIndex") of the given sprite after setting it (it could have been sanitized).
- Type
- number
-
setZIndexSubSprite(sprite [, zIndex]) → {number}
-
Sets the desired z-index ("zIndex") of the given sub-sprite object. Calls the
CB_GraphicSprites#updateSubSpritesByZIndex
method internally.Parameters:
Name Type Argument Default Description sprite
CB_GraphicSprites.SUBSPRITE_OBJECT The
CB_GraphicSprites.SUBSPRITE_OBJECT
object which contains the sub-sprite.zIndex
number <optional>
parseFloat(zIndex)||CB_GraphicSprites.ZINDEX_DEFAULT||0 The z-index value we want. It must be a number but never zero (0). If no valid number is given, it will use the value of the
CB_GraphicSprites.ZINDEX_DEFAULT
property of evaluates to true or 1 otherwise.Returns:
Returns the z-index ("zIndex") of the given sub-sprite after setting it (it could have been sanitized).
- Type
- number
-
updateSpritesByZIndex() → {array}
-
Updates (sorts again) the "spritesByZIndex" property (which is an array with the sprites ordered by z-index, whose data comes from the array in the "sprites" property of the
CB_GraphicSprites#spritesGroup
object) of theCB_GraphicSprites#spritesGroup
object.Returns:
Returns the "spritesByZIndex" array of the
CB_GraphicSprites#spritesGroup
object after updating it. Returns null if the property could not be obtained or updated.- Type
- array
-
updateSubSpritesByZIndex( [sprite]) → {array}
-
Updates (sorts again) the "subSpritesByZIndex" property (which is an array with the sub-sprites ordered by z-index, whose data comes from the array in the "subSprites" property of the given
CB_GraphicSprites.SPRITE_OBJECT
object)) of the desired sprite.Parameters:
Name Type Argument Default Description sprite
CB_GraphicSprites.SPRITE_OBJECT <optional>
CB_GraphicSprites#getCurrent() Object with the sprite whose sub-sprites we want to remove. If not provided, it will use the
CB_GraphicSprites.SPRITE_OBJECT
object which the pointer (set in theCB_GraphicSprites#pointer
property) is currently pointing to (using the returning value of theCB_GraphicSprites#getCurrent
method internally).Returns:
Returns the "subSpritesByZIndex" array after updating it. Returns null if the property could not be obtained or updated.
- Type
- array
-
<static> clearReferences(element) → {*}
-
Clears the "container", the "parent" and the "data.that" properties (sets to null) of the given object and its sub-objects (works recursively, internally).
Parameters:
Name Type Description element
* The object whose properties we want to clear. It can be different kinds (
CB_GraphicSpritesScene
,CB_GraphicSpritesScene.SPRITES_GROUPS_OBJECT
,CB_GraphicSprites
,CB_GraphicSprites.SPRITES_OBJECT
,CB_GraphicSprites.SPRITE_OBJECT
,CB_GraphicSprites.SUBSPRITE_OBJECT
, etc.).Returns:
Returns the same object with the the "container", the "parent", "data.that" and the "data.getThis" properties cleared (set to null), if possible.
- Type
- *
-
<static> filterProperties(element [, propertiesToKeepObject]) → {*}
-
Gets a new object with the properties filtered of a given element and its sub-elements, keeping only the ones that are in the given "propertiesToKeepObject" (works recursively, internally).
Parameters:
Name Type Argument Default Description element
* The object whose properties we want to clear. It can be different kinds (
CB_GraphicSpritesScene
,CB_GraphicSpritesScene.SPRITES_GROUPS_OBJECT
,CB_GraphicSprites
,CB_GraphicSprites.SPRITES_OBJECT
,CB_GraphicSprites.SPRITE_OBJECT
,CB_GraphicSprites.SUBSPRITE_OBJECT
, etc.).propertiesToKeepObject
CB_GraphicSprites.filterProperties_propertiesToKeepObject_TYPE <optional>
CB_GraphicSprites.filterProperties_DEFAULT_PROPERTIES The object with the properties that we want to keep.
- Source:
- To Do:
-
- Implement a boolean property and when it is true it will not keep the properties whose values are the default ones (for example, if "byReference" property is false it will not be kept as it is its default value). So the output can be reduced this way.
Returns:
Returns a new object with the properties filtered of a given element and its sub-elements, keeping only the ones that are in the given "propertiesToKeepObject". If no valid "element" is provided, returns null.
- Type
- *
Type Definitions
-
SPRITES_OBJECT
-
An object with the information that belongs to a group of graphic sprites.
Type:
- Object
- Source:
Properties:
Name Type Argument Default Description id
string | * <optional>
'CB_GraphicSprites_' + CB_GraphicSprites._idUnique++ Identifier of the group of graphic sprites (also used as the
CB_GraphicSprites.id
property for theCB_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).src
* <optional>
"" 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.
srcType
string <optional>
CB_GraphicSprites.SRC_TYPES_DEFAULT
Type of the source of origin. It should point to a property of the
CB_GraphicSprites.SRC_TYPES
object. You can use other values of theCB_GraphicSprites.SRC_TYPES
object or create new ones.srcLeft
number <optional>
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
CB_GraphicSprites.LEFT_SOURCE_DEFAULT
.srcTop
number <optional>
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
CB_GraphicSprites.TOP_SOURCE_DEFAULT
.srcWidth
number <optional>
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
CB_GraphicSprites.WIDTH_SOURCE_DEFAULT
.srcHeight
number <optional>
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
CB_GraphicSprites.HEIGHT_SOURCE_DEFAULT
.left
number <optional>
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
CB_GraphicSprites.LEFT_DEFAULT
.top
number <optional>
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
CB_GraphicSprites.TOP_DEFAULT
.width
number <optional>
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
CB_GraphicSprites.WIDTH_DEFAULT
.height
number <optional>
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
CB_GraphicSprites.HEIGHT_DEFAULT
.zIndex
number <optional>
CB_GraphicSprites.ZINDEX_DEFAULT
The z-index for the destiny (only numeric values which are not zero (0) are allowed). Also used as the
CB_GraphicSprites.zIndex
property for theCB_GraphicSprites
object. If not provided, as default it will use the value fromCB_GraphicSprites.ZINDEX_DEFAULT
. To change the value of this property, use theCB_GraphicSprites#setZIndex
method (which will call theCB_GraphicSpritesScene#updateGraphicSpritesByZIndex
method internally if there is aCB_GraphicSpritesScene
parent object).disabled
boolean <optional>
false Tells whether this sprites group (and the
CB_GraphicSprites
object itself) is disabled or not. If not provided, as default it will be false (which means it is enabled).data
object <optional>
{ 'that' : CB_GraphicSprites.SPRITES_OBJECT, 'getThis' = function() { return this.that; } } Object with any additional data desired which can be any kind. It will always have a "that" property pointing to the
CB_GraphicSprites.SPRITES_OBJECT
object where it belongs to and a function in its "getThis" property returning the same value (added automatically). These properties ("that" and "getThis") cannot be overridden.sprites
array <optional>
[] Numeric array containing
CB_GraphicSprites.SPRITE_OBJECT
objects with all the sprites that will be used. Recommended at least to provide oneCB_GraphicSprites.SPRITE_OBJECT
object in the first index.spritesByZIndex
array Read-only property containing a numeric array of all the
CB_GraphicSprites.SPRITE_OBJECT
objects ordered by their z-index ("zIndex" property). It is updated automatically when the z-index of a sprite is set with its "setZIndex" method (or when calling theCB_GraphicSprites#setZIndexSprite
method) or when inserting/removing sprites through theCB_GraphicSprites#insertSprites
,CB_GraphicSprites#insertSprite
,CB_GraphicSprites#removeSprite
orCB_GraphicSprites#removeSpriteById
methods.byReference_DEFAULT
boolean <optional>
false Default value to use as the "byReference" parameter for the constructor and for the
CB_GraphicSprites#insertSprites
method. If a boolean value is not provided, it will be parsed to boolean (resulting undefined to be false).parent
* <optional>
undefined| CB_GraphicSpritesScene
Property pointing to or containing its parent (also used as the
CB_GraphicSprites.parent
property for theCB_GraphicSprites
object). It could be aCB_GraphicSpritesScene
object.container
CB_GraphicSprites Read-only property pointing to the
CB_GraphicSprites
object which contains it.isSpritesGroup
boolean Read-only property which is always set to true to help identify this type of object.
type
'spritesGroup' Read-only property indicating the type of object (always "spritesGroup").
position
integer <optional>
Read-only property indicating the position of this
CB_GraphicSprites
object in the array which is set the "items" property inside theCB_GraphicSpritesScene#spritesGroups
object which is in theCB_GraphicSpritesScene
object parent (if any).positionByZIndex
integer <optional>
Read-only property indicating the position of this
CB_GraphicSprites
object in the array which is set the "itemsByZIndex" property inside theCB_GraphicSpritesScene#spritesGroups
object which is in theCB_GraphicSpritesScene
object parent (if any).Example
{ //'my_sprites_1': id: "my_sprites_1", src: "path/to/image.gif", srcType: CB_GraphicSprites.SRC_TYPES.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 } ] } ] }
-
SPRITE_OBJECT
-
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).
Type:
- Object
- Source:
Properties:
Name Type Argument Default Description id
string | * <optional>
'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).
src
* <optional>
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.
srcType
string <optional>
this.parent.srcType| CB_GraphicSprites.SRC_TYPES_DEFAULT
Type of the source of origin. If not provided, as default it will use the value from the sprites group that it belongs to. It should point to a property of the
CB_GraphicSprites.SRC_TYPES
object. You can use other values of theCB_GraphicSprites.SRC_TYPES
object or create new ones.srcLeft
number <optional>
this.parent.srcLeft| 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.
srcTop
number <optional>
this.parent.srcTop| 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.
srcWidth
number <optional>
this.parent.srcWidth| 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.
srcHeight
number <optional>
this.parent.srcHeight| 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.
left
number <optional>
CB_GraphicSprites.LEFT_DEFAULT
Left (horizontal) position in the destiny (inside the sprites group). Unit agnostic (only numeric values are allowed).
top
number <optional>
CB_GraphicSprites.TOP_DEFAULT
Top (vertical) position in the destiny (inside the sprites group). Unit agnostic (only numeric values are allowed).
width
number <optional>
this.parent.width| 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.
height
number <optional>
this.parent.height| 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.
zIndex
number <optional>
this.parent.zIndex| CB_GraphicSprites.ZINDEX_DEFAULT
The z-index for the destiny (inside the sprites group). Only numeric values which are not zero (0) are allowed. If not provided, as default it will use the value from the sprites group that it belongs to. To change the value of this property, use the "setZIndex" method of the sprite or the
CB_GraphicSprites#setZIndexSprite
method (which will call theCB_GraphicSpritesScene#updateSpritesByZIndex
method internally).disabled
boolean <optional>
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.
data
object <optional>
CB_combineJSON(this.parent.data, this.data)||this.parent.data||{ 'that' : CB_GraphicSprites.SPRITES_OBJECT, 'getThis' = function() { return this.that; } } Object with any additional data desired which can be any kind. If not provided, missing properties as default will use the value from the sprites group that it belongs to. It will always have a "that" property pointing to the
CB_GraphicSprites.SPRITE_OBJECT
object where it belongs to and a function in its "getThis" property returning the same value (added automatically). These properties ("that" and "getThis") cannot be overridden.subSprites
array <optional>
[] Numeric array containing
CB_GraphicSprites.SUBSPRITE_OBJECT
objects with the sub-sprites that this sprite uses.subSpritesByZIndex
array Read-only property containing a numeric array of all the
CB_GraphicSprites.SUBSPRITE_OBJECT
objects of the sprite ordered by their z-index ("zIndex" property). It is updated automatically when the z-index of a sub-sprite is set with its "setZIndex" method (or when calling theCB_GraphicSprites#setZIndexSubSprite
method) or when inserting/removing sub-sprites through theCB_GraphicSprites#insertSubSprites
,CB_GraphicSprites#insertSubSprite
,CB_GraphicSprites#removeSubSprite
orCB_GraphicSprites#removeSubSpriteById
methods.byReference
boolean <optional>
false If set to true, when inserting the sprite, its "subSprites" property will use exactly the object given for that property (without making a copy) and the same sprite itself (
CB_GraphicSprites.SPRITE_OBJECT
object) will be inserted internally directly without making a copy of itself.parent
CB_GraphicSprites.SPRITES_OBJECT Read-only property pointing to its parent (
CB_GraphicSprites.SPRITES_OBJECT
object).container
CB_GraphicSprites Read-only property pointing to the
CB_GraphicSprites
object which contains it.isSprite
boolean Read-only property which is always set to true to help identify this type of object.
type
'sprite' Read-only property indicating the type of object (always "sprite").
position
integer Read-only property indicating the position of this sprite in the array which is set the "sprites" property of the sprites group parent (
CB_GraphicSprites.SPRITES_OBJECT
object).positionByZIndex
integer Read-only property indicating the position of this sprite in the array which is set the "spritesByZIndex" property of the sprites group parent (
CB_GraphicSprites.SPRITES_OBJECT
object).time
integer Property which stores the time in milliseconds when the sprite was started being pointed for the last time (time elapsed since the time origin which was obtained calling the
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.setTime
function Read-only property which is a method that updates the "time" property of the sprite (calls
CB_GraphicSprites#setTime
internally and returns its returning value). With only one parameter which belongs to the "time" parameter of theCB_GraphicSprites#setTime
method.getTime
function Read-only property which is a method that returns the "time" property of the sprite (calls
CB_GraphicSprites#getTime
internally and returns its returning value). With only one parameter which belongs to the "returnValueOnFail" parameter of theCB_GraphicSprites#getTime
method.getTimeElapsed
function 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 which can be obtained calling the
CB_Device.getTiming
function) or with the current one if none is given (callsCB_GraphicSprites#getTimeElapsed
internally and returns its returning value). With only one parameter which belongs to the "timeToCompare" parameter of theCB_GraphicSprites#getTimeElapsed
method.removeAll
function Read-only property which is a method that removes all the internal sub-sprites (
CB_GraphicSprites.SUBSPRITE_OBJECT
objects) from the sprite which are in the "subSprites" property (callsCB_GraphicSprites#removeSubSprites
internally and returns its returning value). With no parameters.removeSubSprites
function Alias for the "removeAll" method.
insertSubSprites
function Read-only property which is a method that inserts the given sub-sprites (
CB_GraphicSprites.SUBSPRITE_OBJECT
objects) in the sprite, adding them to the "subSprites" property (callsCB_GraphicSprites#insertSubSprites
internally and returns its returning value). With only one parameter which belongs to the "subSprites" parameter of theCB_GraphicSprites#insertSubSprites
method.remove
function Read-only property which is a method that removes an internal sub-sprite (
CB_GraphicSprites.SUBSPRITE_OBJECT
object) by its index (position in the "subSprites" array) from the sprite, removing it from the "subSprites" property (callsCB_GraphicSprites#removeSubSprite
internally and returns its returning value). With only one parameter which belongs to the "index" parameter of theCB_GraphicSprites#removeSubSprite
method.removeById
function Read-only property which is a method that removes an internal sub-sprite (
CB_GraphicSprites.SUBSPRITE_OBJECT
object) by its identifier from the sprite, removing it from the "subSprites" property (callsCB_GraphicSprites#removeSubSpriteById
internally and returns its returning value). With only one parameter which belongs to the "id" parameter of theCB_GraphicSprites#removeSubSpriteById
method.insertSubSprite
function Read-only property which is a method that inserts a given sub-sprite (
CB_GraphicSprites.SUBSPRITE_OBJECT
object) in the sprite, adding it to the "subSprites" property (callsCB_GraphicSprites#insertSubSprite
internally and returns its returning value). With only one parameter which belongs to the "subSprite" parameter of theCB_GraphicSprites#insertSubSprite
method.insert
function Alias for the "insertSubSprite" method.
getAll
function Read-only property which is a method that returns all the internal sub-sprites (
CB_GraphicSprites.SUBSPRITE_OBJECT
objects) in the sprite, getting them from the "subSprites" property (callsCB_GraphicSprites#getAll
internally and returns its returning value). With two parameters ("orderedByZIndex" and "returnValueOnFail") which belong to the parameters with the same name of theCB_GraphicSprites#getAll
method.getSubSprites
function Alias for the "getAll" method.
get
function Read-only property which is a method that returns a sub-sprite (
CB_GraphicSprites.SUBSPRITE_OBJECT
object) by its index (position in the "subSprites" array) from the sprite, getting it from the "subSprites" property (callsCB_GraphicSprites#getSubSprite
internally and returns its returning value). With two parameters ("index" and "returnValueOnFail") which belong to the parameters with the same name of theCB_GraphicSprites#getSubSprite
method.getById
function Read-only property which is a method that returns a sub-sprite (
CB_GraphicSprites.SUBSPRITE_OBJECT
object) by its identifier from the sprite, getting it from the "subSprites" property (callsCB_GraphicSprites#getSubSpriteById
internally and returns its returning value). With two parameters ("id" and "returnValueOnFail") which belong to the parameters with the same name of theCB_GraphicSprites#getSubSpriteById
method.getIndexById
function Read-only property which is a method that returns the index (position in the "subSprites" array) of a sub-sprite (
CB_GraphicSprites.SUBSPRITE_OBJECT
object) by its identifier (callsCB_GraphicSprites#getSubSpriteIndexById
internally and returns its returning value). With only one parameter which belongs to the "id" parameter of theCB_GraphicSprites#getSubSpriteIndexById
method.executeFunctionAll
function Read-only property which is a method that executes the desired function for each sub-sprite (
CB_GraphicSprites.SUBSPRITE_OBJECT
objects which are in the "subSprites" property) in the sprite (callsCB_GraphicSprites#executeFunctionAllSubSprites
internally and returns its returning value). With five parameters ("functionEach", "orderedByZIndex", "delayBetweenEach", "returnSetTimeoutsArray", "delayBetweenEachAffectsFirst" and "functionFinish") which belong to the parameters with the same name of theCB_GraphicSprites#executeFunctionAllSubSprites
method.executeAll
function Alias for the "executeFunctionAll" method.
forEach
function Alias for the "executeFunctionAll" method.
getZIndex
function Read-only property which is a method that returns the z-index ("z-index" property) of the sprite (calls
CB_GraphicSprites#getZIndexSprite
internally and returns its returning value). With only one parameter which belongs to the "returnValueOnFail" parameter of theCB_GraphicSprites#getZIndexSprite
method.setZIndex
function Read-only property which is a method to set the z-index ("z-index" property) of the sprite (calls
CB_GraphicSprites#setZIndexSprite
internally and returns its returning value). With only one parameter which belongs to the "zIndex" parameter of theCB_GraphicSprites#setZIndexSprite
method.isDisabled
function Read-only property which is a method that tells whether the sprite is disabled or not (calls
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.setDisabled
function Read-only property which is a method to disable or enable the sprite (calls
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 theCB_GraphicSprites#setDisabledSprite
method.getPointer
function Read-only property which is a method that gets the current position of the pointer. It belongs to an index of the
CB_GraphicSprites#spritesGroup.sprites
array where aCB_GraphicSprites.SPRITE_OBJECT
object is placed (containing a sprite). Internally, it uses theCB_GraphicSprites#pointer
property. CallsCB_GraphicSprites#getPointer
internally and returns its returning value. With no parameters.getCurrentPosition
function Alias for the "getPointer" method.
getPointerPrevious
function Read-only property which is a method that gets the previous position of the pointer. Internally, it uses the
CB_GraphicSprites#pointerPrevious
property. CallsCB_GraphicSprites#getPointerPrevious
internally and returns its returning value. With no parameters.getPreviousPosition
function Alias for the "getPointerPrevious" method.
setPointer
function 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
CB_GraphicSprites#spritesGroup.sprites
array where aCB_GraphicSprites.SPRITE_OBJECT
object is placed (containing a sprite). Internally, it modifies theCB_GraphicSprites#pointer
property (if possible). If the position was updated, it will also reset theCB_GraphicSprites#time
property (setting the current time in milliseconds). CallsCB_GraphicSprites#setPointer
internally and returns the sprite (aCB_GraphicSprites.SPRITE_OBJECT
object) which is being currently pointed (by the pointer set in theCB_GraphicSprites#pointer
property). With two parameters ("position" and "loop") which belong to the parameters with the same name of theCB_GraphicSprites#setPointer
method.setCurrentPosition
function Alias for the "setPointer" method.
getCurrent
function Read-only property which is a method that gets the sprite (a
CB_GraphicSprites.SPRITE_OBJECT
object) which is being currently pointed (by the pointer set in theCB_GraphicSprites#pointer
property). CallsCB_GraphicSprites#getCurrent
internally and returns its returning value. With no parameters.current
function Alias for the "getCurrent" method.
now
function Alias for the "getCurrent" method.
getPrevious
function Read-only property which is a method that gets the sprite which was previously pointed if any or returns null otherwise. It does not modify the
CB_GraphicSprites#pointer
property. CallsCB_GraphicSprites#getPrevious
internally and returns its returning value. With no parameters.setPrevious
function 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
CB_GraphicSprites#spritesGroup.sprites
array where aCB_GraphicSprites.SPRITE_OBJECT
object is placed (containing a sprite) and it will be returned if found. Internally, it modifies theCB_GraphicSprites#pointer
property (if possible). If the position was updated, it will update also theCB_GraphicSprites#time
property (setting the current time in milliseconds). CallsCB_GraphicSprites#setPrevious
internally and returns its returning value. With only one parameter which belongs to the "loop" parameter of theCB_GraphicSprites#setPrevious
method.previous
function Alias for the "setPrevious" method.
setNext
function 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
CB_GraphicSprites#spritesGroup.sprites
array where aCB_GraphicSprites.SPRITE_OBJECT
object is placed (containing a sprite) and it will be returned if found. Internally, it modifies theCB_GraphicSprites#pointer
property (if possible). If the position was updated, it will also update theCB_GraphicSprites#time
property (setting the current time in milliseconds). CallsCB_GraphicSprites#setNext
internally and returns its returning value. With only one parameter which belongs to the "loop" parameter of theCB_GraphicSprites#setNext
method.next
function Alias for the "setNext" method.
setPropertyCascade
function Read-only property which is a method that sets the desired value of a given property name to the sprite itself and all of its sub-sprites (if any). Calls
CB_GraphicSprites#setPropertyCascade
internally and returns its returning value. With two parameters ("propertyName" and "value") which belong to the parameters with the same name of theCB_GraphicSprites#setPropertyCascade
method.Example
{ //'my_sprite_1': id: "my_sprite_1", src: "path/to/image.gif", srcType: CB_GraphicSprites.SRC_TYPES.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 } ] }
-
SUBSPRITE_OBJECT
-
An object with the information that belongs to a sub-sprite (data which belongs to a certain source) used by a graphic sprite.
Type:
- Object
- Source:
Properties:
Name Type Argument Default Description id
string | * <optional>
'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).
src
* <optional>
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.
srcType
string <optional>
this.parent.srcType| CB_GraphicSprites.SRC_TYPES_DEFAULT
Type of the source of origin. If not provided, as default it will use the value from the sprite that it belongs to. It should point to a property of the
CB_GraphicSprites.SRC_TYPES
object. You can use other values of theCB_GraphicSprites.SRC_TYPES
object or create new ones.srcLeft
number <optional>
this.parent.srcLeft| 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.
srcTop
number <optional>
this.parent.srcTop| 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.
srcWidth
number <optional>
this.parent.srcWidth| 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.
srcHeight
number <optional>
this.parent.srcHeight| 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.
left
number <optional>
CB_GraphicSprites.LEFT_DEFAULT
Left (horizontal) position in the destiny (inside the sprite). Unit agnostic (only numeric values are allowed).
top
number <optional>
CB_GraphicSprites.TOP_DEFAULT
Top (vertical) position in the destiny (inside the sprite). Unit agnostic (only numeric values are allowed).
width
number <optional>
this.parent.width| 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.
height
number <optional>
this.parent.height| 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.
zIndex
number <optional>
this.parent.zIndex| CB_GraphicSprites.ZINDEX_DEFAULT
The z-index for the destiny (inside the sprite). Only numeric values which are not zero (0) are allowed. If not provided, as default it will use the value from the sprite that it belongs to. To change the value of this property, use the "setZIndex" method of the sub-sprite or the
CB_GraphicSprites#setZIndexSubSprite
method (which will call theCB_GraphicSpritesScene#updateSubSpritesByZIndex
method internally).disabled
boolean <optional>
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.
data
object <optional>
CB_combineJSON(this.parent.data, this.data)||this.parent.data||{ 'that' : CB_GraphicSprites.SPRITES_OBJECT, 'getThis' = function() { return this.that; } } Object with any additional data desired which can be any kind. If not provided, missing properties as default will use the value from the sprite that it belongs to. It will always have a "that" property pointing to the
CB_GraphicSprites.SUBSPRITE_OBJECT
object where it belongs to and a function in its "getThis" property returning the same value (added automatically). These properties ("that" and "getThis") cannot be overridden.byReference
boolean <optional>
false If set to true, when inserting the sub-sprite, the same sub-sprite itself (
CB_GraphicSprites.SUBSPRITE_OBJECT
object) will be inserted internally directly without making a copy of itself.parent
CB_GraphicSprites.SPRITE_OBJECT Read-only property pointing to its parent (
CB_GraphicSprites.SPRITE_OBJECT
object).container
CB_GraphicSprites Read-only property pointing to the
CB_GraphicSprites
object which contains it.isSubSprite
boolean Read-only property which is always set to true to help identify this type of object.
type
'subSprite' Read-only property indicating the type of object (always "subSprite").
position
integer Read-only property indicating the position of this sub-sprite in the array which is set the "subSprites" property of the sprite parent (
CB_GraphicSprites.SPRITE_OBJECT
object).positionByZIndex
integer Read-only property indicating the position of this sub-sprite in the array which is set the "subSpritesByZIndex" property of the sprite parent (
CB_GraphicSprites.SPRITE_OBJECT
object).time
integer Property which stores the time in milliseconds when its parent sprite was started being pointed for the last time (time elapsed since the time origin which was obtained calling the
CB_Device.getTiming
function internally). Note that the parent could being not pointed anymore. If it has never being pointed before, it will be set to 0. It normally has the same value as the "time" property of its parent object but they can be modified independently.setTime
function Read-only property which is a method that updates the "time" property of the sub-sprite (calls
CB_GraphicSprites#setTime
internally and returns its returning value). With only one parameter which belongs to the "time" parameter of theCB_GraphicSprites#setTime
method.getTime
function Read-only property which is a method that returns the "time" property of the sub-sprite (calls
CB_GraphicSprites#getTime
internally and returns its returning value). With only one parameter which belongs to the "returnValueOnFail" parameter of theCB_GraphicSprites#getTime
method. If the "time" property of the sub-sprite is not found, it will use the "time" property from its sprite parent.getTimeElapsed
function 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 which can be obtained calling the
CB_Device.getTiming
function) or with the current one if none is given (callsCB_GraphicSprites#getTimeElapsed
internally and returns its returning value). With only one parameter which belongs to the "timeToCompare" parameter of theCB_GraphicSprites#getTimeElapsed
method. If the "time" property of the sub-sprite is not found, it will use the "time" property from its sprite parent.getZIndex
function Read-only property which is a method that returns the z-index ("z-index" property) of the sub-sprite (calls
CB_GraphicSprites#getZIndexSubSprite
internally and returns its returning value). With only one parameter which belongs to the "returnValueOnFail" parameter of theCB_GraphicSprites#getZIndexSubSprite
method.setZIndex
function Read-only property which is a method to set the z-index ("z-index" property) of the sub-sprite (calls
CB_GraphicSprites#setZIndexSubSprite
internally and returns its returning value). With only one parameter which belongs to the "zIndex" parameter of theCB_GraphicSprites#setZIndexSubSprite
method.isDisabled
function Read-only property which is a method that tells whether the sub-sprite is disabled or not (calls
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).setDisabled
function Read-only property which is a method to disable or enable the sub-sprite (calls
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 theCB_GraphicSprites#setDisabledSubSprite
method.Example
{ id: "my_subsprite_1", src: "path/to/image.gif", srcType: CB_GraphicSprites.SRC_TYPES.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" ] } }
-
filterProperties_propertiesToKeepObject_TYPE
-
Object used to know what properties keep when calling the
CB_GraphicSprites.filterProperties
function (type used for its "propertiesToKeepObject" parameter). Its properties must have the name that matches the value returned by the "type" property of each element, being their value an array of strings with the name of the properties we want to keep. The property names which start with a "" symbol will not considered inherited from the element's parent and will always be copied. The other properties (which do not start with the "" symbol) will only be copied when the element contains a value which is different from the same property of its parent.Type:
- Object
- Source:
Properties:
Name Type Argument Description spritesScene
array <optional>
Array of strings with the name of the properties to keep for the
CB_GraphicSpritesScene
objects. If no provided, no properties will be kept for this kind of element.spritesGroups
array <optional>
Array of strings with the name of the properties to keep for the
CB_GraphicSpritesScene.SPRITES_GROUPS_OBJECT
objects. If no provided, no properties will be kept for this kind of element.sprites
array <optional>
Array of strings with the name of the properties to keep for the
CB_GraphicSprites
objects. If no provided, no properties will be kept for this kind of element.spritesGroup
array <optional>
Array of strings with the name of the properties to keep for the
CB_GraphicSprites.SPRITES_OBJECT
objects. If no provided, no properties will be kept for this kind of element.sprite
array <optional>
Array of strings with the name of the properties to keep for the
CB_GraphicSprites.SPRITE_OBJECT
objects. If no provided, no properties will be kept for this kind of element.subSprite
array <optional>
Array of strings with the name of the properties to keep for the
CB_GraphicSprites.SUBSPRITE_OBJECT
objects. If no provided, no properties will be kept for this kind of element.