Parameters:

Object with the desired data and options for the groups of audio sprites. Each group will have a CB_AudioFileSprites object. Some of its properties ("preferredAPIs", "preferredFormats", "minimumAudioFiles", "maximumAudioFiles", "minimumAudioFilesFree", "newAudioFilesWhenNeeded", "retries", "checkManually", "checkManuallyOnNeededCreated", "checkManuallyOnPlayingFailed", "checkManuallyOnCheckingFailed" and "disableAutoLoad") will be used as the default value to create internally the CB_AudioFileSprites objects when the value is not given in the CB_AudioFileSpritesPool.SPRITES_GROUPS_OBJECT object (set as the value of the CB_AudioFileSpritesPool.DATA_OBJECT#spritesGroups property).

Type:

<static, constant> CHECKING :integer

Status value for an audio file sprites pool which is being checked currently. Can be used to compare the value returned by the CB_AudioFileSpritesPool#getStatus method. Recommended for internal usage only.

Type:

<static, constant> FAILED :integer

Status value for an audio file sprites pool which failed to be loaded or failed for any other reason. Can be used to compare the value returned by the CB_AudioFileSpritesPool#getStatus method. Recommended for internal usage only.

Type:

<static, constant> UNCHECKED :integer

Status value for an audio file sprites pool which has not been checked yet. Can be used to compare the value returned by the CB_AudioFileSpritesPool#getStatus method. Recommended for internal usage only.

<readonly> id :string

Type:

<readonly> maximumAudioFiles :integer|null

Maximum CB_AudioFile objects that are to be created internally for each CB_AudioFileSprites object. If it is set to null, there will not be a maximum (it will be unlimited). If an integer is provided, it must be the same number or greater than the value set in the CB_AudioFileCache#minimumAudioFiles property, allowing 1 minimum. Internal usage only recommended.

Type:

<readonly> minimumAudioFilesFree :integer

New CB_AudioFile objects will be created internally for each CB_AudioFileSprites object when the number of free CB_AudioFile objects reaches this limit. It must be an integer being 0 (zero) the minimum. Internal usage only recommended.

Type:

<readonly> onError :function

Desired function to be called when any kind of error happens. The first and unique parameter will be a string with the error description (if it could be determined), being "this" the current CB_AudioFileSpritesPool object. If a function is set, it will always be called through the CB_AudioFileSpritesPool#errorFunction method whenever the "onError" event of an internally-created CB_AudioFileSprites object is fired.

Type:

<readonly> onLoad :function

Desired function to be called once the pool has been loaded. The first and unique parameter will be an integer with the CB_AudioFile objects that still need to be checked, if any, being "this" the current CB_AudioFileSpritesPool object.

Type:

<readonly> preferredFormats :array

Stores an array of strings with the preferred audio format or audio formats (they can include just the format as 'audio/ogg' or also the codec as for example 'audio/ogg; codecs="vorbis"'), in order of preference. Internal usage only recommended.

Type:

<readonly> retries :integer

Number of retries to try to load a CB_AudioFile object internally before trying to load the next possible one internally (if any). It must be an integer being 0 the minimum. Internal usage only recommended.

Parameters:

A function which will be called if all the CB_AudioFile objects whose CB_AudioFile#getStatus method returned the "unchecked" value (which belongs to the value of the CB_AudioFile#UNCHECKED property) could finally be checked successfully and all can be played, being "this" the CB_AudioFileSpritesPool object itself.

A function which will be called if not all the CB_AudioFile objects whose CB_AudioFile#getStatus method returned the "unchecked" value (which belongs to the value of the CB_AudioFile#UNCHECKED property) could finally be checked successfully and any cannot be played, being "this" the CB_AudioFileSpritesPool object itself. This function will be called immediately if the method was previously called and it is still running currently.

Returns:

Returns the number of CB_AudioFile objects whose status belonged to the "unchecked" value (the value of the CB_AudioFile#UNCHECKED property) before the execution of this method. It will return 0 (zero) if the method is tried to be executed while there is another previous call of it still running. It will also return 0 (zero) if the status of audio sprites pool is neither loaded (the CB_AudioFileSpritesPool#getStatus method does not returns the value set in the CB_AudioFileSpritesPool.LOADED property) nor unchecked (the CB_AudioFileSpritesPool#status method does not return the value set in the CB_AudioFileSpritesPool.UNCHECKED property).

If set to true (not recommended), it will not assign the status of "ABORTED" (it will not set the CB_AudioFileSpritesPool#_aborted property to true}. Used as the "preventAbortedStatus" parameter when calling internally the CB_AudioFileSprites#destructor method of all the internally-created CB_AudioFileSprites objects.

If it is set to false, it will return the number of calls to the "functionEach" function that were performed. Otherwise, if it is set to true, it will return a numeric array and each value (which will belong to each sprites group) will be another numeric array with a CB_AudioFileCache.executeFunctionAll_OBJECT object for each CB_AudioFile of that sprites group.

Function that will be called for when it has finished looping all the items. The first parameter will be the array containing all the items which were 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.

Think about consider executing only one by one (now it will loop CB_AudioFile objects from different sprites groups simultaneously).

Returns:

If the "returnArrayOfSetTimeoutsArray" parameter is set to false, it will return the number of calls to the "functionEach" function that were performed. Otherwise, if the "returnArrayOfSetTimeoutsArray" is set to true, it will return a numeric array and each value will be another numeric array with a CB_AudioFileCache.executeFunctionAll_OBJECT object for each CB_AudioFile given. 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.

Function that will be called for when it has finished looping all the items. The first parameter will be the array containing all the items which were 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.

Think about consider executing only one by one (now it will loop CB_AudioFile objects from different sprites groups simultaneously).

Returns:

It will return the number of calls to the "functionEach" function that were performed (which should be the same number as the CB_AudioFile objects used by the sound instances that belong to the sprites of each sprites group). 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.

Parameters:

If it is set to true, the method will return an array with all the CB_AudioFile objects. Otherwise, if it is set to false, the method will return an object whose property names will be the ID of each sprites group and their value will be an array with all the CB_AudioFile objects that belong to that sprites group.

Returns:

If the "oneDimension" parameter is set to true, returns an array with all the CB_AudioFile objects. Otherwise, if the "oneDimension" parameter is set to false, it will return an object whose property names will be the ID of each sprites group and their value will be an array with all the CB_AudioFile objects that belong to that sprites group.

Parameters:

Name

Type

Argument

Default

Description

oneDimension

boolean

<optional>

false

If it is set to true, the method will return an array with the busy CB_AudioFile objects. Otherwise, if it is set to false, the method will return an object whose property names will be the ID of each sprites group and their value will be an array with the busy CB_AudioFile objects that belong to that sprites group.

Returns:

If the "oneDimension" parameter is set to true, returns an array with the busy CB_AudioFile objects. Otherwise, if the "oneDimension" parameter is set to false, it will return an object whose property names will be the ID of each sprites group and their value will be an array with the busy CB_AudioFile objects that belong to that sprites group.

Parameters:

Name

Type

Argument

Default

Description

oneDimension

boolean

<optional>

false

If it is set to true, the method will return an array with the free CB_AudioFile objects. Otherwise, if it is set to false, the method will return an object whose property names will be the ID of each sprites group and their value will be an array with the free CB_AudioFile objects that belong to that sprites group.

Returns:

If the "oneDimension" parameter is set to true, returns an array with the free CB_AudioFile objects. Otherwise, if the "oneDimension" parameter is set to false, it will return an object whose property names will be the ID of each sprites group and their value will be an array with the free CB_AudioFile objects that belong to that sprites group.

Returns the CB_AudioFile objects used by all the sounds instances of all the sprites groups.

Parameters:

Name

Type

Argument

Default

Description

oneDimension

boolean

<optional>

false

If set to false, it will return an object whose property names will be the ID of each sprites group and their value will be the an object whose property names are the sprite identifiers (including the "_WITHOUT_SPRITE_ASSOCIATED" property for sound instances without a sprite associated, if the "includeWithoutSpriteAssociated" is set to true) and their value will be a numeric array with the CB_AudioFile objects used. Otherwise, if set to true, it will return a numeric array with the CB_AudioFile objects used (if the "includeWithoutSpriteAssociated" parameter is set to true, it will also contain the CB_AudioFile objects whose sound instance ID is not associated to any sprite).

includeWithoutSpriteAssociated

boolean

<optional>

false

If set to true, it will also return the CB_AudioFile objects whose sound instance ID is not associated to any sprite. Used as the "includeWithoutSpriteAssociated" parameter when calling the CB_AudioFileSprites#getAudioFilesUsed method internally.

Returns:

Returns the CB_AudioFile objects used by all the sounds instances of all the sprites groups. If the "oneDimension" parameter is set to false, it will return a CB_AudioFileSpritesPool.getAudioFilesUsed_OBJECT object whose property names will be the ID of each sprites group and their value will be a CB_AudioFileSprites.getAudioFilesUsed_OBJECT object whose property names are the sprite identifiers (including the "_WITHOUT_SPRITE_ASSOCIATED" property for sound instances without a sprite associated, if the "includeWithoutSpriteAssociated" is set to true) and their value will be a numeric array with the CB_AudioFile objects used. Otherwise, if the "oneDimension" parameter set to true, it will return a numeric array with the CB_AudioFile objects used (if the "includeWithoutSpriteAssociated" parameter is set to true, it will also contain the CB_AudioFile objects whose sound instance ID is not associated to any sprite).

Returns a number representing the percentage of the loading progress for the audio sprites pool object (from 0 to 100, being 100 a complete loading progress). The way to calculate it internally may differ from one audio API to another and it is not totally reliable. Uses the CB_AudioFileSprites#getProgress method internally.

Returns:

Returns a number representing the percentage of the loading progress for the audio sprites pool object (from 0 to 100, being 100 a complete loading progress). The way to calculate it internally may differ from one audio API to another and it is not totally reliable.

Parameters:

Name

Type

Argument

Default

Description

oneDimension

boolean

<optional>

false

If set to false, it will return an object whose property names will be the ID of each sprites group and their value will be the CB_AudioFileSprites#spriteSoundInstances property of each CB_AudioFileSprites object (which includes the "_WITHOUT_SPRITE_ASSOCIATED" property for sound instances without a sprite associated) which belongs to that sprites group. Otherwise, if it is set to true, it will return a numeric array whose values are the sound instance IDs.

includeWithoutSpriteAssociated

boolean

<optional>

false

If set to true, it will also return the sound instance identifiers which are not associated to any sprite. Used as the "includeWithoutSpriteAssociated" parameter when calling the CB_AudioFileSprites#getSoundInstancesId method internally. Only used when the "oneDimension" parameter is set to true.

Returns:

Returns the sound instances (their ID) used (stored in the CB_AudioFileSprites#spriteSoundInstances property). If the "oneDimension" parameter is set to false, it will return an object whose property names will be the ID of each sprites group and their value will be the CB_AudioFileSprites#spriteSoundInstances property of each CB_AudioFileSprites object (which includes the "_WITHOUT_SPRITE_ASSOCIATED" property for sound instances without a sprite associated) which belongs to that sprites group. If the "oneDimension" parameter is set to true, it will return a numeric array whose values are the sound instance identifiers (if the "includeWithoutSpriteAssociated" parameter it set to true, it will also include the sound instances which are not associated to any sprite).

Returns an object with the sprites (and includes "_WITHOUT_SPRITE_ASSOCIATED" if we want to). Internally, uses the CB_AudioFileSprites#getSprites method.

Parameters:

Name

Type

Argument

Default

Description

includeWithoutSpriteAssociated

boolean

<optional>

false

If set to true, the returning object will also contain a property called "_WITHOUT_SPRITE_ASSOCIATED" whose value will be an empty object (unless the "orderBySpritesGroup" parameter is set to true and the property existed before in the object stored in the CB_AudioFileSprites#sprites property and had a value which is not an empty object). If set to false and the "orderBySpritesGroup" parameter is also set to false, the returning object will not contain the "_WITHOUT_SPRITE_ASSOCIATED" property. If set to false and the "orderBySpritesGroup" parameter is set to true, the returning object will not contain the "_WITHOUT_SPRITE_ASSOCIATED" property unless the property existed before in the object stored in the CB_AudioFileSprites#sprites property.

Returns:

Returns null if the "withoutChecking" parameter is set to true and the sprites group cannot be found. Otherwise, it will return what is stored internally by the given ID which can be a CB_AudioFileSprites object if found or undefined (or whatever is stored by the given ID) if not found.

getStatusString() → {string}

Returns:

Returns the current status of the audio file sprites pool object, as a string. Possible return values are "UNLOADED", "LOADING", "UNCHECKED", "CHECKING", "LOADED", "FAILED", "ABORTED" or "UNKNOWN (UNKNOWN_STATUS)" (where "UNKNOWN_STATUS" will be a returning value from the CB_AudioFileSpritesPool#getStatus method not recognized as any possible status).

If set to true, it will not check whether all sprites groups has been loaded after inserting the desired one. This is done internally by the CB_AudioFileSpritesPool#_checkSpritesGroupsLoaded method which will fire the CB_AudioFileSpritesPool#onLoad function (if any).

Returns:

Loads the audio file sprites pool with the desired data given. This method is called by the constructor automatically. Recommended to be called through a user-driven event (as onClick, onTouch, etc.), as some clients may need this at least the first time in order to be able to play the audio.

If the "destroy" parameter is set to false, this parameter will be ignored. Used as the "stopSound" parameter when calling internally the CB_AudioFileSprites#destructor method of the CB_AudioFileSprites object which belongs to the desired sprites group.

preventAbortedStatus

boolean

<optional>

false

If the "destroy" parameter is set to false, this parameter will be ignored. Used as the "preventAbortedStatus" parameter when calling internally the CB_AudioFileSprites#destructor method of the CB_AudioFileSprites object which belongs to the desired sprites group.

Tries to change the audio API for all the existing CB_AudioFile objects or the desired ones (if provided). This method is not allowed to be called if a previous call to it did not finish yet. The function defined in the "callbackError" parameter, if any, will be called immediately if the method was previously called and it is still running currently. Uses the CB_AudioFileSprites#setAudioAPIAll method internally.

Function that will be called when any error happened, being "this" the CB_AudioFileSpritesPool object. This function will be called immediately if the method was previously called and it is still running currently.

Type:

Properties:

Object with the desired sprites groups, containing the CB_AudioFileSprites.DATA_OBJECT objects which will be used to create the CB_AudioFileSprites objects internally. Each group will have a CB_AudioFileSprites object. It will be used as the first parameter to call the CB_AudioFileSpritesPool#insertSpritesGroups method internally. Some of the missing properties ("preferredAPIs", "preferredFormats", "minimumAudioFiles", "maximumAudioFiles", "minimumAudioFilesFree", "newAudioFilesWhenNeeded", "retries", "checkManually", "checkManuallyOnNeededCreated", "checkManuallyOnPlayingFailed", "checkManuallyOnCheckingFailed" and "disableAutoLoad") of the CB_AudioFileSprites.DATA_OBJECT objects given will use the value set on the other properties of this object (if any).

Array of strings with the preferred audio format or audio formats (they can include just the format as 'audio/ogg' or also the codec as for example 'audio/ogg; codecs="vorbis"'), in order of preference. It will try to calculate and use the best one for the current client. If a valid value is given, this will be added to the CB_AudioFileSpritesPool#preferredFormats property. If the CB_AudioFileSprites.DATA_OBJECT object (defined in the CB_AudioFileSpritesPool.SPRITES_GROUPS_OBJECT object set in the "spritesGroups") of a certain sprites group does not contain the "preferredFormats" property, it will use the value of this property instead when creating its CB_AudioFileSprites object internally.

Desired function to be called once the pool has been loaded. The first and unique parameter will be an integer with the CB_AudioFile objects that still need to be checked, if any, being "this" the current CB_AudioFileSpritesPool object. If a valid value is given, this will be added to the CB_AudioFileSpritesPool#onLoad property.

Type:

Properties:

Being the name of each property the unique identifier of a sprites group which will use a future internally-created CB_AudioFileSprites object, the value will always be the CB_AudioFileSprites.DATA_OBJECT that the CB_AudioFileSprites object will use to be created (received by its constructor). Some of the missing properties ("preferredAPIs", "preferredFormats", "minimumAudioFiles", "maximumAudioFiles", "minimumAudioFilesFree", "newAudioFilesWhenNeeded", "retries", "checkManually", "checkManuallyOnNeededCreated", "checkManuallyOnPlayingFailed", "checkManuallyOnCheckingFailed" and "disableAutoLoad") will use the value set on the properties of the main CB_AudioFileSpritesPool.DATA_OBJECT object (if any) used by the CB_AudioFileSpritesPool object. If a function in the "onError" parameter is given, it will always be wrapped so the main error function set on the CB_AudioFileSpritesPool#onError parameter will always be called (if any) through the CB_AudioFileSpritesPool#errorFunction method.