CrossBrowdy API documentation

Class: CB_GraphicSprites

CB_GraphicSprites

Class to manage a group of graphic sprites (2D or 3D).

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 CB_GraphicSprites#spritesGroup property. Used as the "spritesGroup" parameter when calling the CB_GraphicSprites#insertSprites method internally.
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 the CB_GraphicSprites#byReference_DEFAULT property. If a boolean value is not provided, it will use the value of the CB_GraphicSprites.SPRITES_OBJECT.byReference_DEFAULT property of the given CB_GraphicSprites.SPRITES_OBJECT object (parsed to boolean).
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
Source:

<readonly> id :string|*

Identifier of the sprites group object (the "id" property of the CB_GraphicSprites.SPRITES_OBJECT stored in the CB_GraphicSprites#spritesGroup property) and the CB_GraphicSprites object itself (same one). It should be unique. It must be a value which evaluates to true. By default, it is generated automatically (with an internal counter).

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 the CB_GraphicSprites.SPRITES_OBJECT stored in the CB_GraphicSprites#spritesGroup property.

Type:
  • *
Source:

<readonly> pointer :integer

Pointer with the position of the current sprite (belongs to an index of the CB_GraphicSprites#spritesGroup.sprites array).

Type:
  • integer
Source:

<readonly> pointerPrevious :integer

Keeps the previous value of the CB_GraphicSprites#pointer property (if any).

Type:
  • integer
Source:

<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
Source:

<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 the CB_GraphicSprites#spritesGroup property) and the CB_GraphicSprites object itself (same one). To change the value of this property, use the CB_GraphicSprites#setZIndex method (which will call the CB_GraphicSpritesScene#updateGraphicSpritesByZIndex method internally if there is a CB_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
Source:

<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
Source:

<static, constant> LEFT_SOURCE_DEFAULT :number

Default left ("srcLeft", horizontal position) in the original source. Unit agnostic.

Type:
  • number
Source:

<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
Source:

<static, constant> TOP_SOURCE_DEFAULT :number

Default top ("srcTop", vertical position) in the original source. Unit agnostic.

Type:
  • number
Source:

<static, constant> WIDTH_DEFAULT :number

Default "width" of the destiny. Unit agnostic.

Type:
  • number
Source:

<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.

Source:
See:

destructor()

Destroys the graphic sprites object (removing all the sprites and their sub-sprites, etc.) and frees memory.

Source:

executeAll()

Alias for CB_GraphicSprites#executeFunctionAll.

Source:
See:

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 the CB_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 the CB_GraphicSprites.SPRITE_OBJECT object of the "sprites" being looped, as the second parameter the position of this CB_GraphicSprites.SPRITE_OBJECT object in the "sprites" array provided (or, if not provided, in the array returned by the CB_GraphicSprites#getSprites method), the third parameter is the array being looped and the fourth parameter will be the "delayBetweenEach" being used, being "this" the CB_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 only CB_GraphicSprites.SPRITE_OBJECT objects which are already in the current CB_GraphicSprites object. If not provided, it will use all the CB_GraphicSprites.SPRITE_OBJECT objects contained in the CB_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:
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 a CB_Arrays.executeFunctionAll_OBJECT object for each CB_GraphicSprites.SPRITE_OBJECT given. The length of this array will also be the number of calls to the "functionEach" function that were performed. Note that if a value greater than 0 (zero) for the "delayBetweenEach" parameter has been provided, perhaps not all calls of the "functionEach" function will have been performed yet when exiting this method because of the asynchronous nature of the setTimeout 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 the CB_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 the CB_GraphicSprites.SUBSPRITE_OBJECT object of the sub-sprites being looped, as the second parameter the position of this CB_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" the CB_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 the CB_GraphicSprites.SPRITE_OBJECT object which the pointer (set in the CB_GraphicSprites#pointer property) is currently pointing to (using the returning value of the CB_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:
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 given CB_GraphicSprites.SPRITE_OBJECT object). Otherwise, if the "returnSetTimeoutsArray" is set to true, it will return a numeric array with a CB_Arrays.executeFunctionAll_OBJECT object for each CB_GraphicSprites.SUBSPRITE_OBJECT. The length of this array will also be the number of calls to the "functionEach" function that were performed. Note that if a value greater than 0 (zero) for the "delayBetweenEach" parameter has been provided, perhaps not all calls of the "functionEach" function will have been performed yet when exiting this method because of the asynchronous nature of the setTimeout function.

Type
integer | array

forEach()

Alias for CB_GraphicSprites#executeFunctionAll.

Source:
See:

forEachSprite()

Alias for CB_GraphicSprites#executeFunctionAll.

Source:
See:

get()

Alias for CB_GraphicSprites#getSprite.

Source:
See:

getAll()

Alias for CB_GraphicSprites#getSprites.

Source:
See:

getById()

Alias for CB_GraphicSprites#getSpriteById.

Source:
See:

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 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, the CB_GraphicSprites.filterProperties will always be called before calling the CB_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 the CB_GraphicSprites.filterProperties function internally. If set to true and the "clearReferences" parameter is also set to true, the CB_GraphicSprites.filterProperties will always be called before calling the CB_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.
Source:
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 the CB_GraphicSprites#pointer property).

Source:
Returns:

Returns the CB_GraphicSprites.SPRITE_OBJECT object which is currently pointed by the pointer (set in the CB_GraphicSprites#pointer property). Returns null if not found.

Type
CB_GraphicSprites.SPRITE_OBJECT | null

getCurrentPosition()

Alias for CB_GraphicSprites#getPointer.

Source:
See:

getIndexById()

Alias for CB_GraphicSprites#getSpriteIndexById.

Source:
See:

getPointer() → {integer}

Gets the current position of the pointer. It belongs to an index of the CB_GraphicSprites#spritesGroup.sprites array where a CB_GraphicSprites.SPRITE_OBJECT object is placed (containing a sprite). Internally, it uses the CB_GraphicSprites#pointer property.

Source:
Returns:

Returns the position where the pointer is currently pointing to. It belongs to an index of the CB_GraphicSprites#spritesGroup.sprites array where a CB_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 a CB_GraphicSprites.SPRITE_OBJECT object is placed (containing a sprite). Internally, it uses the CB_GraphicSprites#pointerPrevious property.

Source:
Returns:

Returns the position where the pointer was previously pointing to. It belongs to an index of the CB_GraphicSprites#spritesGroup.sprites array where a CB_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 the CB_GraphicSprites#pointer property, whose value is now in the CB_GraphicSprites#pointerPrevious property).

Source:
Returns:

Returns the CB_GraphicSprites.SPRITE_OBJECT object which was previously pointed by the pointer (by the previous value of the pointer set in the CB_GraphicSprites#pointer property, whose value is now in the CB_GraphicSprites#pointerPrevious property). Returns null if not found.

Type
CB_GraphicSprites.SPRITE_OBJECT | null

getPreviousPosition()

Alias for CB_GraphicSprites#getPointerPrevious.

Source:
See:

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 the CB_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.
Source:
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.
Source:
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.
Source:
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.

Source:
See:

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.
Source:
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 the CB_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 the CB_GraphicSprites.SPRITE_OBJECT object which the pointer (set in the CB_GraphicSprites#pointer property) is currently pointing to (using the returning value of the CB_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.
Source:
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 the CB_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 the CB_GraphicSprites.SPRITE_OBJECT object which the pointer (set in the CB_GraphicSprites#pointer property) is currently pointing to (using the returning value of the CB_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.
Source:
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 the CB_GraphicSprites.SPRITE_OBJECT object which the pointer (set in the CB_GraphicSprites#pointer property) is currently pointing to (using the returning value of the CB_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 given CB_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 the CB_GraphicSprites.SPRITE_OBJECT object which the pointer (set in the CB_GraphicSprites#pointer property) is currently pointing to (using the returning value of the CB_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.
Source:
Returns:

Returns an array with all the CB_GraphicSprites.SUBSPRITE_OBJECT objects of the given CB_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".
Source:
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 the CB_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 the CB_GraphicSprites#time property). It must be a positive number (or zero). If not provided, it will use the current time (by calling the CB_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".
Source:
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.
Source:
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 the CB_GraphicSprites.SPRITE_OBJECT object which the pointer (set in the CB_GraphicSprites#pointer property) is currently pointing to (using the returning value of the CB_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.
Source:
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.
Source:
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.

Source:
See:

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.
Source:
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).

Type
CB_GraphicSprites.SPRITE_OBJECT

insertSprites( [spritesGroup] [, byReference]) → {CB_GraphicSprites.SPRITES_OBJECT}

Adds the desired group of graphic sprites. Calls the CB_GraphicSprites#insertSprite and CB_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 the CB_GraphicSprites#byReference_DEFAULT property. If a boolean value is not provided, it will use the value of the CB_GraphicSprites.SPRITES_OBJECT.byReference_DEFAULT property of the given CB_GraphicSprites.SPRITES_OBJECT object (parsed to boolean).
Source:
Returns:

Returns the CB_GraphicSprites#spritesGroup property after updating it.

Type
CB_GraphicSprites.SPRITES_OBJECT

insertSpritesGroup()

Alias for CB_GraphicSprites#insertSprites.

Source:
See:

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.
Source:
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).

Type
CB_GraphicSprites.SUBSPRITE_OBJECT

insertSubSprites(subSprites [, sprite]) → {array}

Adds the given sub-sprites to the desired sprite. Calls the CB_GraphicSprites#insertSubSprite and CB_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.
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 the CB_GraphicSprites#pointer property) is currently pointing to (using the returning value of the CB_GraphicSprites#getCurrent method internally).
Source:
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.

Source:
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 the CB_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 the CB_GraphicSprites.SPRITE_OBJECT object which the pointer (set in the CB_GraphicSprites#pointer property) is currently pointing to (using the returning value of the CB_GraphicSprites#getCurrent method internally).
Source:
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.
Source:
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.

Source:
See:

now()

Alias for CB_GraphicSprites#getCurrent.

Source:
See:

previous()

Alias for CB_GraphicSprites#setPrevious.

Source:
See:

remove()

Alias for CB_GraphicSprites#removeSprite.

Source:
See:

removeAll()

Alias for CB_GraphicSprites#removeSprites.

Source:
See:

removeById()

Alias for CB_GraphicSprites#removeSpriteById.

Source:
See:

removeSprite( [index]) → {boolean}

Removes a sprite by its index (its position in the CB_GraphicSprites#spritesGroup.sprites array). Calls the CB_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).
Source:
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.

Source:

removeSpritesAll()

Alias for CB_GraphicSprites#removeSprites.

Source:
See:

removeSpritesGroup()

Alias for CB_GraphicSprites#removeSprites.

Source:
See:

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 given CB_GraphicSprites.SPRITE_OBJECT object). Calls the CB_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 the CB_GraphicSprites#pointer property) is currently pointing to (using the returning value of the CB_GraphicSprites#getCurrent method internally).
Source:
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 the CB_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 the CB_GraphicSprites#pointer property) is currently pointing to (using the returning value of the CB_GraphicSprites#getCurrent method internally).
Source:
Returns:

Returns true if the sub-sprites have been deleted or false otherwise.

Type
boolean

removeSubSpritesAll()

Alias for CB_GraphicSprites#removeSubSprites.

Source:
See:

setCurrentPosition()

Alias for CB_GraphicSprites#setPointer.

Source:
See:

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.
Source:

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 the CB_GraphicSprites.SPRITE_OBJECT object which the pointer (set in the CB_GraphicSprites#pointer property) is currently pointing to (using the returning value of the CB_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.
Source:

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.
Source:

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 a CB_GraphicSprites.SPRITE_OBJECT object is placed (containing a sprite) and it will be returned if found. Internally, it modifies the CB_GraphicSprites#pointer property (if possible). If the position was updated, it will also update the CB_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.
Source:
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 a CB_GraphicSprites.SPRITE_OBJECT object is placed (containing a sprite). Internally, it modifies the CB_GraphicSprites#pointer property (if possible). If the position was updated, it will also reset the CB_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 a CB_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.
Source:
Returns:

Returns the position where the pointer is currently pointing to. It belongs to an index of the CB_GraphicSprites#spritesGroup.sprites array where a CB_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 a CB_GraphicSprites.SPRITE_OBJECT object is placed (containing a sprite) and it will be returned if found. Internally, it modifies the CB_GraphicSprites#pointer property (if possible). If the position was updated, it will update also the CB_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.
Source:
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 and CB_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).
Source:
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 the CB_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 the CB_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 the CB_GraphicSprites#pointer property). This parameter is ignored if the "updateTimeCurrentSprite" parameter is set to false.
Source:
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 the CB_GraphicSprites.parent property), it will also call its CB_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.
Source:
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 the CB_GraphicSprites.SPRITE_OBJECT object which the pointer (set in the CB_GraphicSprites#pointer property) is currently pointing to (using the returning value of the CB_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.
Source:
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.
Source:
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 the CB_GraphicSprites#spritesGroup object.

Source:
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 the CB_GraphicSprites#pointer property) is currently pointing to (using the returning value of the CB_GraphicSprites#getCurrent method internally).
Source:
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.).
Source:
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
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 the CB_GraphicSprites object). It should be unique. Recommended. It must be a value which evaluates to true. By default, it is generated automatically (with an internal counter).
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 the CB_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 the CB_GraphicSprites object. If not provided, as default it will use the value from CB_GraphicSprites.ZINDEX_DEFAULT. To change the value of this property, use the CB_GraphicSprites#setZIndex method (which will call the CB_GraphicSpritesScene#updateGraphicSpritesByZIndex method internally if there is a CB_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 one CB_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 the CB_GraphicSprites#setZIndexSprite method) or when inserting/removing sprites through the CB_GraphicSprites#insertSprites, CB_GraphicSprites#insertSprite, CB_GraphicSprites#removeSprite or CB_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 the CB_GraphicSprites object). It could be a CB_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 the CB_GraphicSpritesScene#spritesGroups object which is in the CB_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 the CB_GraphicSpritesScene#spritesGroups object which is in the CB_GraphicSpritesScene object parent (if any).
Source:
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
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 the CB_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 the CB_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 the CB_GraphicSprites#setZIndexSubSprite method) or when inserting/removing sub-sprites through the CB_GraphicSprites#insertSubSprites, CB_GraphicSprites#insertSubSprite, CB_GraphicSprites#removeSubSprite or CB_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 the CB_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 the CB_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 (calls CB_GraphicSprites#getTimeElapsed internally and returns its returning value). With only one parameter which belongs to the "timeToCompare" parameter of the CB_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 (calls CB_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 (calls CB_GraphicSprites#insertSubSprites internally and returns its returning value). With only one parameter which belongs to the "subSprites" parameter of the CB_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 (calls CB_GraphicSprites#removeSubSprite internally and returns its returning value). With only one parameter which belongs to the "index" parameter of the CB_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 (calls CB_GraphicSprites#removeSubSpriteById internally and returns its returning value). With only one parameter which belongs to the "id" parameter of the CB_GraphicSprites#removeSubSpriteById method.
insert 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 (calls CB_GraphicSprites#insertSubSprite internally and returns its returning value). With only one parameter which belongs to the "subSprite" parameter of the CB_GraphicSprites#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 (calls CB_GraphicSprites#getAll internally and returns its returning value). With two parameters ("orderedByZIndex" and "returnValueOnFail") which belong to the parameters with the same name of the CB_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 (calls CB_GraphicSprites#getSubSprite internally and returns its returning value). With two parameters ("index" and "returnValueOnFail") which belong to the parameters with the same name of the CB_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 (calls CB_GraphicSprites#getSubSpriteById internally and returns its returning value). With two parameters ("id" and "returnValueOnFail") which belong to the parameters with the same name of the CB_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 (calls CB_GraphicSprites#getSubSpriteIndexById internally and returns its returning value). With only one parameter which belongs to the "id" parameter of the CB_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 (calls CB_GraphicSprites#executeFunctionAllSubSprites internally and returns its returning value). With five parameters ("functionEach", "orderedByZIndex", "delayBetweenEach", "returnSetTimeoutsArray", "delayBetweenEachAffectsFirst" and "functionFinish") which belong to the parameters with the same name of the CB_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 the CB_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 the CB_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 the CB_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 a CB_GraphicSprites.SPRITE_OBJECT object is placed (containing a sprite). Internally, it uses the CB_GraphicSprites#pointer property. Calls CB_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. Calls CB_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 a CB_GraphicSprites.SPRITE_OBJECT object is placed (containing a sprite). Internally, it modifies the CB_GraphicSprites#pointer property (if possible). If the position was updated, it will also reset the CB_GraphicSprites#time property (setting the current time in milliseconds). Calls CB_GraphicSprites#setPointer internally and returns the sprite (a CB_GraphicSprites.SPRITE_OBJECT object) which is being currently pointed (by the pointer set in the CB_GraphicSprites#pointer property). With two parameters ("position" and "loop") which belong to the parameters with the same name of the CB_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 the CB_GraphicSprites#pointer property). Calls CB_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. Calls CB_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 a CB_GraphicSprites.SPRITE_OBJECT object is placed (containing a sprite) and it will be returned if found. Internally, it modifies the CB_GraphicSprites#pointer property (if possible). If the position was updated, it will update also the CB_GraphicSprites#time property (setting the current time in milliseconds). Calls CB_GraphicSprites#setPrevious internally and returns its returning value. With only one parameter which belongs to the "loop" parameter of the CB_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 a CB_GraphicSprites.SPRITE_OBJECT object is placed (containing a sprite) and it will be returned if found. Internally, it modifies the CB_GraphicSprites#pointer property (if possible). If the position was updated, it will also update the CB_GraphicSprites#time property (setting the current time in milliseconds). Calls CB_GraphicSprites#setNext internally and returns its returning value. With only one parameter which belongs to the "loop" parameter of the CB_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 the CB_GraphicSprites#setPropertyCascade method.
Source:
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
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 the CB_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 the CB_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 the CB_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 the CB_GraphicSprites#getTime method. If the "time" property of the sub-sprite is not found, it will use the "time" property from its sprite parent.
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 (calls CB_GraphicSprites#getTimeElapsed internally and returns its returning value). With only one parameter which belongs to the "timeToCompare" parameter of the CB_GraphicSprites#getTimeElapsed method. If the "time" property of the sub-sprite is not found, it will use the "time" property from its sprite parent.
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 the CB_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 the CB_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 the CB_GraphicSprites#setDisabledSubSprite method.
Source:
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
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.
Source: