# Class: CB_GraphicSpritesScene

## CB_GraphicSpritesScene

Class to manage different groups of graphic sprites (2D or 3D). Internally, it manages `CB_GraphicSprites` objects.

#### new CB_GraphicSpritesScene( [spritesGroups] [, byReference]) → {CB_GraphicSpritesScene}

  Class to manage different groups of graphic sprites (2D or 3D). Internally, it manages `CB_GraphicSprites` objects.

  ##### Parameters:

  Name | Type | Argument | Default | Description
  --- | --- | --- | --- | ---
  `spritesGroups` | CB_GraphicSpritesScene.SPRITES_GROUPS_OBJECT | <optional> |  | Object with the desired groups of sprites. The information will be used for the `CB_GraphicSpritesScene#spritesGroups` property. Used as the "spritesGroups" parameter when calling the `CB_GraphicSpritesScene#insertSpritesGroups` method internally.
  `byReference` | boolean | <optional> | false | This value will be used as the "byReference" parameter of the constructor when creating the new internal `CB_GraphicSprites` objects. If a boolean value is not provided, it will use the value of the `CB_GraphicSpritesScene.SPRITES_GROUPS_OBJECT.byReference_DEFAULT` property of the given `CB_GraphicSpritesScene.SPRITES_GROUPS_OBJECT` object (parsed to boolean).

  Source:
    - CrossBase/audiovisual/image/CB_GraphicSpritesScene.js, line 127
  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 group object when the same sprite group is received by parameter. The same to remove a `CB_GraphicSprites` object, receiving a `CB_GraphicSprites` object by parameter. The same to remove the sprites groups object, receiving a sprites groups object by parameter. Only remove them if they match exactly.
    - Think about a method to insert `CB_GraphicSprites` object directly. The same with a method that inserts many `CB_GraphicSprites` objects (receiving an array with them).

  ##### Returns:

  Returns a new `CB_GraphicSpritesScene` object.

  Type
    CB_GraphicSpritesScene

### Members

#### <readonly> id :string|*

  Identifier of the sprites groups object (the "id" property of the `CB_GraphicSpritesScene.SPRITES_GROUPS_OBJECT` stored in the `CB_GraphicSpritesScene#spritesGroups` property) and the `CB_GraphicSpritesScene` 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_GraphicSpritesScene_' + CB_GraphicSpritesScene._idUnique++
  Source:
    - CrossBase/audiovisual/image/CB_GraphicSpritesScene.js, line 140

#### <constant> isSpritesScene :boolean

  Property which is always set to true to help identify this type of object.

  ##### Type:

  - boolean
  Default Value:
    - true
  Source:
    - CrossBase/audiovisual/image/CB_GraphicSpritesScene.js, line 173

#### <readonly> parent :*

  Property pointing to or containing its parent. It is the same as the "parent" property of the `CB_GraphicSprites.SPRITES_GROUPS_OBJECT` stored in the `CB_GraphicSprites#spritesGroups` property.

  ##### Type:

  - *
  Source:
    - CrossBase/audiovisual/image/CB_GraphicSpritesScene.js, line 149

#### <readonly> spritesGroups :SPRITES_GROUPS_OBJECT

  Object containing all the internally-created `CB_GraphicSprites` objects and their information.

  ##### Type:

  - SPRITES_GROUPS_OBJECT
  Default Value:
    - {}
  Source:
    - CrossBase/audiovisual/image/CB_GraphicSpritesScene.js, line 159

#### <constant> type :string

  Indicates the type of object (always "spritesScene").

  ##### Type:

  - string
  Default Value:
    - spritesScene
  Source:
    - CrossBase/audiovisual/image/CB_GraphicSpritesScene.js, line 182

### Methods

#### destructor()

  Destroys the graphic sprites scene object (removing all the sprites groups and the internal `CB_GraphicSprites` objects, etc.) and frees memory.

  Source:
    - CrossBase/audiovisual/image/CB_GraphicSpritesScene.js, line 201

#### executeAll()

  Alias for `CB_GraphicSpritesScene#executeFunctionAll`.

  Source:
    - CrossBase/audiovisual/image/CB_GraphicSpritesScene.js, line 600
  See:
    - `CB_GraphicSpritesScene#executeFunctionAll`

#### executeFunctionAll(functionEach [, orderedByZIndex] [, delayBetweenEach] [, graphicSpritesObjects] [, returnSetTimeoutsArray] [, delayBetweenEachAffectsFirst] [, functionFinish]) → {integer|array}

  Performs a desired action, using the provided function, on all the existing `CB_GraphicSprites` 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 `CB_GraphicSprites` object. As the first parameter it receives the `CB_GraphicSprites` object of the "graphicSpritesObjects" being looped, as the second parameter the position of this `CB_GraphicSprites` object in the "graphicSpritesObjects" array provided (or, if not provided, in the array returned by the `CB_GraphicSpritesScene#getGraphicSpritesAll` method), the third parameter is the array being looped and the fourth parameter will be the "delayBetweenEach" being used, being "this" the `CB_GraphicSprites` object itself.
  `orderedByZIndex` | boolean | <optional> | false | If set to true, it will loop the `CB_GraphicSprites` 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` object).
  `graphicSpritesObjects` | array | <optional> | `CB_GraphicSpritesScene#getGraphicSpritesAll`() | A numeric array containing the `CB_GraphicSprites` objects that we want to loop. It should contain only `CB_GraphicSprites` objects which are already in the current `CB_GraphicSpritesScene` object. If not provided, it will use all the `CB_GraphicSprites` objects contained in the `CB_GraphicSpritesScene` 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:
    - CrossBase/audiovisual/image/CB_GraphicSpritesScene.js, line 628
  To Do:
    - Think about only allowing `CB_GraphicSprites` objects (in the "graphicSpritesObjects" parameter) which are already in the `CB_GraphicSpritesScene` (identify them by their ID), to avoid problems.

  ##### 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` objects given in the "graphicSpritesObjects" 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` 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

#### forEach()

  Alias for `CB_GraphicSpritesScene#executeFunctionAll`.

  Source:
    - CrossBase/audiovisual/image/CB_GraphicSpritesScene.js, line 605
  See:
    - `CB_GraphicSpritesScene#executeFunctionAll`

#### forEachGraphicSprites()

  Alias for `CB_GraphicSpritesScene#executeFunctionAll`.

  Source:
    - CrossBase/audiovisual/image/CB_GraphicSpritesScene.js, line 610
  See:
    - `CB_GraphicSpritesScene#executeFunctionAll`

#### get()

  Alias for `CB_GraphicSpritesScene#getGraphicSprites`.

  Source:
    - CrossBase/audiovisual/image/CB_GraphicSpritesScene.js, line 534
  See:
    - `CB_GraphicSpritesScene#getGraphicSprites`

#### getAll()

  Alias for `CB_GraphicSpritesScene#getGraphicSpritesAll`.

  Source:
    - CrossBase/audiovisual/image/CB_GraphicSpritesScene.js, line 505
  See:
    - `CB_GraphicSpritesScene#getGraphicSpritesAll`

#### getById()

  Alias for `CB_GraphicSpritesScene#getGraphicSpritesById`.

  Source:
    - CrossBase/audiovisual/image/CB_GraphicSpritesScene.js, line 555
  See:
    - `CB_GraphicSpritesScene#getGraphicSpritesById`

#### getCopy( [avoidCopyingPointers] [, avoidCopyingTimes] [, clearReferences] [, filterProperties] [, propertiesToKeepObject]) → {CB_GraphicSpritesScene}

  Gets a new copy of this object with the same attributes (all sub-objects will be a copy, they will not use the same reference).

  ##### Parameters:

  Name | Type | Argument | Default | Description
  --- | --- | --- | --- | ---
  `avoidCopyingPointers` | boolean | <optional> | false | If set to true, it will not copy the `CB_GraphicSprites#pointer` property of each `CB_GraphicSprites` object.
  `avoidCopyingTimes` | boolean | <optional> | false | If set to true, it will not copy neither the `CB_GraphicSprites#time` property of each `CB_GraphicSprites` object nor the "time" property of each of their 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:
    - CrossBase/audiovisual/image/CB_GraphicSpritesScene.js, line 665

  ##### Returns:

  Returns a copy of this object with the same attributes (all sub-objects will be a copy, not the same reference).

  Type
    CB_GraphicSpritesScene

#### getGraphicSprites( [index] [, returnValueOnFail]) → {CB_GraphicSprites|*}

  Gets a desired `CB_GraphicSprites` object through its index (its position in the `CB_GraphicSpritesScene#spritesGroups.items` array). Faster than getting it through its identifier with the `CB_GraphicSpritesScene#getGraphicSpritesById` method.

  ##### Parameters:

  Name | Type | Argument | Default | Description
  --- | --- | --- | --- | ---
  `index` | integer | <optional> | 0 | The index where the desired `CB_GraphicSprites` object must be located (its position in the `CB_GraphicSpritesScene#spritesGroups.items` 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:
    - CrossBase/audiovisual/image/CB_GraphicSpritesScene.js, line 546

  ##### Returns:

  Returns a `CB_GraphicSprites` object if found or the value of "returnValueOnFail" otherwise.

  Type
    CB_GraphicSprites | *

#### getGraphicSpritesAll( [orderedByZIndex] [, returnValueOnFail]) → {array|*}

  Gets all the sprites graphic objects (the "items" property of the internal `CB_GraphicSpritesScene.SPRITES_GROUPS_OBJECT` object, if any).

  ##### Parameters:

  Name | Type | Argument | Default | Description
  --- | --- | --- | --- | ---
  `orderedByZIndex` | boolean | <optional> | false | If set to true, it will return the `CB_GraphicSprites` objects 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:
    - CrossBase/audiovisual/image/CB_GraphicSpritesScene.js, line 517

  ##### Returns:

  Returns an array with all the `CB_GraphicSprites` objects or the value of "returnValueOnFail" otherwise.

  Type
    array | *

#### getGraphicSpritesById( [id] [, returnValueOnFail]) → {CB_GraphicSprites|*}

  Gets a desired `CB_GraphicSprites` object through its identifier. Slower than getting it through its index with the `CB_GraphicSpritesScene#getGraphicSprites` method.

  ##### Parameters:

  Name | Type | Argument | Description
  --- | --- | --- | ---
  `id` | string | * | <optional> | The identifier of the `CB_GraphicSprites` object 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:
    - CrossBase/audiovisual/image/CB_GraphicSpritesScene.js, line 567

  ##### Returns:

  Returns a `CB_GraphicSprites` object if found or the value of "returnValueOnFail" otherwise.

  Type
    CB_GraphicSprites | *

#### getGraphicSpritesIndexById( [id]) → {integer}

  Gets the index (the position in the `CB_GraphicSpritesScene#spritesGroups.items` array) of a desired `CB_GraphicSprites` object by its identifier.

  ##### Parameters:

  Name | Type | Argument | Description
  --- | --- | --- | ---
  `id` | string | * | <optional> | The identifier of the `CB_GraphicSprites` object whose index we want to get.

  Source:
    - CrossBase/audiovisual/image/CB_GraphicSpritesScene.js, line 586
  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_GraphicSpritesScene#spritesGroups.items` array) of the desired `CB_GraphicSprites` object or -1 if not found.

  Type
    integer

#### getIndexById()

  Alias for `CB_GraphicSpritesScene#getGraphicSpritesIndexById`.

  Source:
    - CrossBase/audiovisual/image/CB_GraphicSpritesScene.js, line 574
  See:
    - `CB_GraphicSpritesScene#getGraphicSpritesIndexById`

#### getSpritesGroups( [returnValueOnFail]) → {CB_GraphicSpritesScene.SPRITES_GROUPS_OBJECT|*}

  Gets the sprites groups object (the `CB_GraphicSpritesScene.SPRITES_GROUPS_OBJECT` object which is in the `CB_GraphicSpritesScene#spritesGroups` property), 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:
    - CrossBase/audiovisual/image/CB_GraphicSpritesScene.js, line 499

  ##### Returns:

  Returns the sprites groups object (the `CB_GraphicSpritesScene.SPRITES_GROUPS_OBJECT` object which is in the `CB_GraphicSpritesScene#spritesGroups` property), if any, or the value of "returnValueOnFail" otherwise.

  Type
    CB_GraphicSpritesScene.SPRITES_GROUPS_OBJECT | *

#### getSpritesGroupsAll()

  Alias for `CB_GraphicSpritesScene#getSpritesGroups`.

  Source:
    - CrossBase/audiovisual/image/CB_GraphicSpritesScene.js, line 488
  See:
    - `CB_GraphicSpritesScene#getSpritesGroups`

#### insert()

  Alias for `CB_GraphicSpritesScene#insertSpritesGroup`.

  Source:
    - CrossBase/audiovisual/image/CB_GraphicSpritesScene.js, line 397
  See:
    - `CB_GraphicSpritesScene#insertSpritesGroup`

#### insertSpritesGroup( [spritesGroup] [, avoidUpdatingGraphicSpritesByZIndex] [, byReference]) → {CB_GraphicSpritesScene.insertSpritesGroup_OBJECT}

  Adds the desired group of graphic sprites. Creates internal `CB_GraphicSprites` objects.

  ##### Parameters:

  Name | Type | Argument | Default | Description
  --- | --- | --- | --- | ---
  `spritesGroup` | CB_GraphicSprites.SPRITES_OBJECT | <optional> |  | Object with the desired sprites group. It will be stored in the "`CB_GraphicSpritesScene#spritesGroups`.spritesGroups" property and the `CB_GraphicSprites` object created internally will be stored in the "`CB_GraphicSpritesScene#spritesGroups`.items" property.
  `avoidUpdatingGraphicSpritesByZIndex` | boolean | <optional> | false | If set to true, it will not call the {CB_GraphicSpritesScene#updateGraphicSpritesByZIndex} method internally. Internal usage recommended only.
  `byReference` | boolean | <optional> | false | This value will be used as the "byReference" parameter of the constructor when creating the new internal `CB_GraphicSprites` objects.

  Source:
    - CrossBase/audiovisual/image/CB_GraphicSpritesScene.js, line 410

  ##### Returns:

  Returns an object whose "spritesGroup" property contains the `CB_GraphicSpritesScene.SPRITES_GROUPS_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) and was used to create the internal `CB_GraphicSprites` object when calling its constructor and the "item" property contains the `CB_GraphicSprites` object created and inserted.

  Type
    CB_GraphicSpritesScene.insertSpritesGroup_OBJECT

#### insertSpritesGroups( [spritesGroups] [, byReference]) → {CB_GraphicSpritesScene.SPRITES_GROUPS_OBJECT}

  Adds the desired groups of graphic sprites. Calls the `CB_GraphicSpritesScene#insertSpritesGroup` and `CB_GraphicSpritesScene#updateGraphicSpritesByZIndex` methods internally.

  ##### Parameters:

  Name | Type | Argument | Default | Description
  --- | --- | --- | --- | ---
  `spritesGroups` | CB_GraphicSpritesScene.SPRITES_GROUPS_OBJECT | <optional> |  | Object with the desired sprites groups. They will be stored in the "`CB_GraphicSpritesScene#spritesGroups`.spritesGroups" property and the `CB_GraphicSprites` objects created internally will be stored in the "`CB_GraphicSpritesScene#spritesGroups`.items" property.
  `byReference` | boolean | <optional> | !!`CB_GraphicSpritesScene.SPRITES_GROUPS_OBJECT.byReference_DEFAULT` | This value will be used as the "byReference" parameter of the constructor when creating the new internal `CB_GraphicSprites` objects. If a boolean value is not provided, it will use the value of the `CB_GraphicSpritesScene.SPRITES_GROUPS_OBJECT.byReference_DEFAULT` property of the given `CB_GraphicSpritesScene.SPRITES_GROUPS_OBJECT` object (parsed to boolean).

  Source:
    - CrossBase/audiovisual/image/CB_GraphicSpritesScene.js, line 238

  ##### Returns:

  Returns the `CB_GraphicSpritesScene#spritesGroups` property after updating it.

  Type
    CB_GraphicSpritesScene.SPRITES_GROUPS_OBJECT

#### remove()

  Alias for `CB_GraphicSpritesScene#removeSpritesGroup`.

  Source:
    - CrossBase/audiovisual/image/CB_GraphicSpritesScene.js, line 323
  See:
    - `CB_GraphicSpritesScene#removeSpritesGroup`

#### removeAll()

  Alias for `CB_GraphicSpritesScene#removeSpritesGroups`.

  Source:
    - CrossBase/audiovisual/image/CB_GraphicSpritesScene.js, line 211
  See:
    - `CB_GraphicSpritesScene#removeSpritesGroups`

#### removeById()

  Alias for `CB_GraphicSpritesScene#removeSpritesGroupById`.

  Source:
    - CrossBase/audiovisual/image/CB_GraphicSpritesScene.js, line 355
  See:
    - `CB_GraphicSpritesScene#removeSpritesGroupById`

#### removeGraphicSprites()

  Alias for `CB_GraphicSpritesScene#removeSpritesGroup`.

  Source:
    - CrossBase/audiovisual/image/CB_GraphicSpritesScene.js, line 328
  See:
    - `CB_GraphicSpritesScene#removeSpritesGroup`

#### removeGraphicSpritesById()

  Alias for `CB_GraphicSpritesScene#removeSpritesGroupById`.

  Source:
    - CrossBase/audiovisual/image/CB_GraphicSpritesScene.js, line 360
  See:
    - `CB_GraphicSpritesScene#removeSpritesGroupById`

#### removeSpritesGroup( [index]) → {boolean}

  Removes a sprites group and its `CB_GraphicSprites` object by its index (its position in the `CB_GraphicSpritesScene#spritesGroups.items` array). Calls the `CB_GraphicSpritesScene#updateGraphicSpritesByZIndex` method internally.

  ##### Parameters:

  Name | Type | Argument | Default | Description
  --- | --- | --- | --- | ---
  `index` | integer | <optional> | 0 | The index where the `CB_GraphicSprites` object is located (its position in the `CB_GraphicSpritesScene#spritesGroups.items` array).

  Source:
    - CrossBase/audiovisual/image/CB_GraphicSpritesScene.js, line 339

  ##### Returns:

  Returns true if the `CB_GraphicSprites` object has been deleted from the graphic sprites scene object or false otherwise.

  Type
    boolean

#### removeSpritesGroupById( [id]) → {boolean}

  Removes a sprites group and its `CB_GraphicSprites` object by its identifier. Calls the `CB_GraphicSpritesScene#updateGraphicSpritesByZIndex` method internally.

  ##### Parameters:

  Name | Type | Argument | Description
  --- | --- | --- | ---
  `id` | string | * | <optional> | The identifier of the `CB_GraphicSprites` object.

  Source:
    - CrossBase/audiovisual/image/CB_GraphicSpritesScene.js, line 372
  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 `CB_GraphicSprites` object has been deleted from the graphic sprites scene object or false otherwise.

  Type
    boolean

#### removeSpritesGroups()

  Removes all the sprites groups (and all the `CB_GraphicSprites` objects) by clearing the `CB_GraphicSprites#spritesGroups` property.

  Source:
    - CrossBase/audiovisual/image/CB_GraphicSpritesScene.js, line 225

#### removeSpritesGroupsAll()

  Alias for `CB_GraphicSpritesScene#removeSpritesGroups`.

  Source:
    - CrossBase/audiovisual/image/CB_GraphicSpritesScene.js, line 216
  See:
    - `CB_GraphicSpritesScene#removeSpritesGroups`

#### setPropertyCascade(propertyName [, value] [, onlyCurrent]) → {integer}

  Sets the desired value of a given property name to the `CB_GraphicSpritesScene.SPRITES_GROUPS_OBJECT` object as well to its `CB_GraphicSprites` objects and their children (their `CB_GraphicSprites.SPRITES_OBJECT` object, including their `CB_GraphicSprites.SPRITE_OBJECT` and their `CB_GraphicSprites.SUBSPRITE_OBJECT` objects). Calls the `CB_GraphicSprites#setPropertyCascade` method internally.

  ##### Parameters:

  Name | Type | Argument | Default | Description
  --- | --- | --- | --- | ---
  `propertyName` | number |  |  | The name of the property we want to affect. Also used as the "propertyName" parameter when calling the `CB_GraphicSprites#setPropertyCascade` method internally.
  `value` | * | <optional> |  | The value desired for the given property. Also used as the "value" parameter when calling the `CB_GraphicSprites#setPropertyCascade` method internally.
  `onlyCurrent` | boolean | <optional> | false | If set to true, it will only affect the current sprite and its sub-sprites of each `CB_GraphicSprites` object (and also the `CB_GraphicSpritesScene.SPRITES_GROUPS_OBJECT` object and the `CB_GraphicSprites.SPRITES_OBJECT` object of each `CB_GraphicSprites` object). Used as the "propertyName" parameter when calling the `CB_GraphicSprites#setPropertyCascade` method internally.

  Source:
    - CrossBase/audiovisual/image/CB_GraphicSpritesScene.js, line 642

  ##### Returns:

  Returns the number of elements affected (counting the `CB_GraphicSpritesScene.SPRITES_GROUPS_OBJECT` object and the `CB_GraphicSprites.SPRITES_OBJECT` objects).

  Type
    integer

#### updateGraphicSpritesByZIndex() → {array}

  Updates (sorts again) the "itemsByZIndex" property (which is an array with the `CB_GraphicSprites` objects ordered by z-index, whose data comes from the array in the "items" property of the `CB_GraphicSpritesScene#spritesGroups` object) of the `CB_GraphicSpritesScene#spritesGroups` object.

  Source:
    - CrossBase/audiovisual/image/CB_GraphicSpritesScene.js, line 300

  ##### Returns:

  Returns the "itemsByZIndex" array of the `CB_GraphicSpritesScene#spritesGroups` object after updating it. Returns null if the property could not be obtained or updated.

  Type
    array

#### updateItemsByZIndex()

  Alias for `CB_GraphicSpritesScene#updateGraphicSpritesByZIndex`.

  Source:
    - CrossBase/audiovisual/image/CB_GraphicSpritesScene.js, line 290
  See:
    - `CB_GraphicSpritesScene#updateGraphicSpritesByZIndex`

### Type Definitions

#### SPRITES_GROUPS_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_GraphicSpritesScene_' + CB_GraphicSpritesScene._idUnique++ | Identifier of the sprites groups object and also for the graphic sprites scene (also used as the `CB_GraphicSprites.id` property for the `CB_GraphicSpritesScene` 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> | "" | The value for the "src" property which will be used as default if not provided (or the provided one was wrong) in the given `CB_GraphicSprites.SPRITES_OBJECT` objects (in the "spritesGroups" property), when creating the internal `CB_GraphicSprites` objects.
  `srcType` | string | <optional> | `CB_GraphicSprites.SRC_TYPES_DEFAULT` | The value for the "srcType" property which will be used as default if not provided (or the provided one was wrong) in the given `CB_GraphicSprites.SPRITES_OBJECT` objects (in the "spritesGroups" property), when creating the internal `CB_GraphicSprites` objects. 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` | The value for the "srcLeft" property which will be used as default if not provided (or the provided one was wrong) in the given `CB_GraphicSprites.SPRITES_OBJECT` objects (in the "spritesGroups" property), when creating the internal `CB_GraphicSprites` objects.
  `srcTop` | number | <optional> | `CB_GraphicSprites.TOP_SOURCE_DEFAULT` | The value for the "srcTop" property which will be used as default if not provided (or the provided one was wrong) in the given `CB_GraphicSprites.SPRITES_OBJECT` objects (in the "spritesGroups" property), when creating the internal `CB_GraphicSprites` objects.
  `srcWidth` | number | <optional> | `CB_GraphicSprites.WIDTH_SOURCE_DEFAULT` | The value for the "srcWidth" property which will be used as default if not provided (or the provided one was wrong) in the given `CB_GraphicSprites.SPRITES_OBJECT` objects (in the "spritesGroups" property), when creating the internal `CB_GraphicSprites` objects.
  `srcHeight` | number | <optional> | `CB_GraphicSprites.HEIGHT_SOURCE_DEFAULT` | The value for the "srcHeight" property which will be used as default if not provided (or the provided one was wrong) in the given `CB_GraphicSprites.SPRITES_OBJECT` objects (in the "spritesGroups" property), when creating the internal `CB_GraphicSprites` objects.
  `left` | number | <optional> | `CB_GraphicSprites.LEFT_DEFAULT` | The value for the "left" property which will be used as default if not provided (or the provided one was wrong) in the given `CB_GraphicSprites.SPRITES_OBJECT` objects (in the "spritesGroups" property), when creating the internal `CB_GraphicSprites` objects.
  `top` | number | <optional> | `CB_GraphicSprites.TOP_DEFAULT` | The value for the "top" property which will be used as default if not provided (or the provided one was wrong) in the given `CB_GraphicSprites.SPRITES_OBJECT` objects (in the "spritesGroups" property), when creating the internal `CB_GraphicSprites` objects.
  `width` | number | <optional> | `CB_GraphicSprites.WIDTH_DEFAULT` | The value for the "width" property which will be used as default if not provided (or the provided one was wrong) in the given `CB_GraphicSprites.SPRITES_OBJECT` objects (in the "spritesGroups" property), when creating the internal `CB_GraphicSprites` objects.
  `height` | number | <optional> | `CB_GraphicSprites.HEIGHT_DEFAULT` | The value for the "height" property which will be used as default if not provided (or the provided one was wrong) in the given `CB_GraphicSprites.SPRITES_OBJECT` objects (in the "spritesGroups" property), when creating the internal `CB_GraphicSprites` objects.
  `zIndex` | number | <optional> | `CB_GraphicSprites.ZINDEX_DEFAULT` | The value for the "zIndex" property which will be used as default if not provided (or the provided one was wrong) in the given `CB_GraphicSprites.SPRITES_OBJECT` objects (in the "spritesGroups" property), when creating the internal `CB_GraphicSprites` objects.
  `disabled` | boolean | <optional> | false | The value for the "disabled" property which will be used as default if not provided (or the provided one was wrong) in the given `CB_GraphicSprites.SPRITES_OBJECT` objects (in the "spritesGroups" property), when creating the internal `CB_GraphicSprites` objects.
  `data` | object | <optional> | { 'that' : CB_GraphicSprites.SPRITES_GROUPS_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_GROUPS_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. The value given will also be used for the "data" property which will be used as default if not provided (or the provided one was wrong) in the given `CB_GraphicSprites.SPRITES_OBJECT` objects (in the "spritesGroups" property), when creating the internal `CB_GraphicSprites` objects.
  `spritesGroups` | array | <optional> | [] | Numeric array containing `CB_GraphicSprites.SPRITES_OBJECT` objects with all the sprites groups that are useful for creating the internal `CB_GraphicSprites` objects. Recommended at least to provide one `CB_GraphicSprites.SPRITES_OBJECT` object in the first index.
  `parent` | * | <optional> |  | Property pointing to or containing its parent (also used as the `CB_GraphicSpritesScene.parent` property for the `CB_GraphicSpritesScene` object).
  `items` | array |  |  | Read-only numeric array containing `CB_GraphicSprites` objects created internally. Their "parent" property will be set to point the current `CB_GraphicSpritesScene` object which contains them.
  `itemsByZIndex` | array |  |  | Read-only property containing a numeric array of all the `CB_GraphicSprites` objects ordered by their z-index ("zIndex" property). It is updated automatically when the z-index of a sprite is set with its `CB_GraphicSprites#setZIndex` method or when inserting/removing `CB_GraphicSprites` objects through the `CB_GraphicSpritesScene#insertSpritesGroups`, `CB_GraphicSpritesScene#insertSpritesGroup`, `CB_GraphicSpritesScene#removeSpritesGroup` or `CB_GraphicSpritesScene#removeSpritesGroupById` methods.
  `byReference_DEFAULT` | boolean | <optional> | false | Default value to use as the "byReference" parameter for the constructor and for the `CB_GraphicSpritesScene#insertSpritesGroups` method. If a boolean value is not provided, it will be parsed to boolean (resulting undefined to be false).
  `container` | CB_GraphicSpritesScene |  |  | Read-only property pointing to the `CB_GraphicSpritesScene` object which contains it.
  `isSpritesGroups` | boolean |  |  | Read-only property which is always set to true to help identify this type of object.
  `type` | 'spritesGroups' |  |  | Read-only property indicating the type of object (always "spritesGroups").

  Source:
    - CrossBase/audiovisual/image/CB_GraphicSpritesScene.js, line 8

  ##### Example

      {
      	//'my_sprites_scene_1':
      	id: "my_sprites_scene_1",
      	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 groups:
      	spritesGroups:
      	[
      		//'my_sprites_1':
      		{
      			id: "my_sprites_1",
      			src: "path/to/image.gif",
      			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 }
      					]
      				}
      			]
      		 },
      		//'my_sprites_2':
      		{
      			id: "my_sprites_2",
      			src: "path/to/image2.gif",
      			sprites:
      			[
      				//'my_sprite_3':
      				{
      					id: "my_sprite_3",
      					subSprites:
      					[
      						//'my_subsprite_1':
      						{ id: "my_subsprite_5", srcLeft: 10, srcTop: 20, zIndex: 1 },
      						//'my_subsprite_2':
      						{ id: "my_subsprite_6", srcLeft: 20, srcTop: 40, zIndex: 2 }
      					]
      				},
      				//'my_sprite_4':
      				{
      					id: "my_sprite_4",
      					subSprites:
      					[
      						//'my_subsprite_3':
      						{ id: "my_subsprite_7", srcLeft: 30, srcTop: 60, zIndex: 1 },
      						//'my_subsprite_4':
      						{ id: "my_subsprite_8", srcLeft: 40, srcTop: 80, zIndex: 2 }
      					]
      				}
      			]
      		}
      	]
       }

#### insertSpritesGroup_OBJECT

  Object used as the returning value of the `CB_GraphicSpritesScene#insertSpritesGroup` method.

  ##### Type:

  - Object

  ##### Properties:

  Name | Type | Description
  --- | --- | ---
  `spritesGroup` | CB_GraphicSprites.SPRITES_OBJECT | The `CB_GraphicSpritesScene.SPRITES_GROUPS_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) and was used to create the internal `CB_GraphicSprites` object when calling its constructor.
  `item` | CB_GraphicSprites | The `CB_GraphicSprites` object created and inserted from the `CB_GraphicSprites.SPRITES_OBJECT`.

  Source:
    - CrossBase/audiovisual/image/CB_GraphicSpritesScene.js, line 389

#### Search results