UNPKG

116 kBHTMLView Raw
1<!DOCTYPE html>
2
3<html lang="en">
4<head>
5 <meta charset="utf-8">
6 <meta name="viewport" content="width=device-width">
7 <title>CrossBrowdy API documentation Source: CrossBase/audiovisual/audio/CB_AudioFileSprites.js</title>
8
9 <!--[if lt IE 9]>
10 <script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
11 <![endif]-->
12 <link type="text/css" rel="stylesheet" href="styles/sunlight.default.css">
13
14 <link type="text/css" rel="stylesheet" href="styles/site.cosmo.css">
15
16</head>
17
18<body style="min-width:800px; overflow-wrap:break-word; word-wrap:break-word; word-break:break-word; line-break:strict; hyphens:none; -webkit-hyphens:none; -moz-hyphens:none;">
19
20<div class="navbar navbar-default navbar-fixed-top ">
21<div class="container">
22 <div class="navbar-header">
23 <a class="navbar-brand" href="index.html">CrossBrowdy API documentation</a>
24 <button class="navbar-toggle" type="button" data-toggle="collapse" data-target="#topNavigation">
25 <span class="icon-bar"></span>
26 <span class="icon-bar"></span>
27 <span class="icon-bar"></span>
28 </button>
29 </div>
30 <div class="navbar-collapse collapse" id="topNavigation">
31 <ul class="nav navbar-nav">
32
33 <li class="dropdown">
34 <a href="namespaces.list.html" class="dropdown-toggle" data-toggle="dropdown">Namespaces<b class="caret"></b></a>
35 <ul class="dropdown-menu inline">
36 <li><a href="CB_Arrays.html">CB_Arrays</a></li><li><a href="CB_AudioDetector.html">CB_AudioDetector</a></li><li><a href="CB_Client.html">CB_Client</a></li><li><a href="CB_Collisions.html">CB_Collisions</a></li><li><a href="CB_Configuration.html">CB_Configuration</a></li><li><a href="CB_Configuration.CrossBase.html">CB_Configuration.CrossBase</a></li><li><a href="CB_Configuration.CrossBrowdy.html">CB_Configuration.CrossBrowdy</a></li><li><a href="CB_Controllers.html">CB_Controllers</a></li><li><a href="CB_Controllers_Proprietary.html">CB_Controllers_Proprietary</a></li><li><a href="CB_Controllers_Proprietary.WII.html">CB_Controllers_Proprietary.WII</a></li><li><a href="CB_Controllers_Proprietary.WII_U.html">CB_Controllers_Proprietary.WII_U</a></li><li><a href="CB_Device.html">CB_Device</a></li><li><a href="CB_Device.AmbientLight.html">CB_Device.AmbientLight</a></li><li><a href="CB_Device.Battery.html">CB_Device.Battery</a></li><li><a href="CB_Device.Location.html">CB_Device.Location</a></li><li><a href="CB_Device.Motion.html">CB_Device.Motion</a></li><li><a href="CB_Device.Orientation.html">CB_Device.Orientation</a></li><li><a href="CB_Device.Proximity.html">CB_Device.Proximity</a></li><li><a href="CB_Device.Vibration.html">CB_Device.Vibration</a></li><li><a href="CB_Elements.html">CB_Elements</a></li><li><a href="CB_Events.html">CB_Events</a></li><li><a href="CB_Keyboard.html">CB_Keyboard</a></li><li><a href="CB_Keyboard.chars.html">CB_Keyboard.chars</a></li><li><a href="CB_Keyboard.extended.html">CB_Keyboard.extended</a></li><li><a href="CB_Keyboard.keys.html">CB_Keyboard.keys</a></li><li><a href="CB_Modules.html">CB_Modules</a></li><li><a href="CB_Mouse.html">CB_Mouse</a></li><li><a href="CB_Mouse.CursorImage.html">CB_Mouse.CursorImage</a></li><li><a href="CB_Net.html">CB_Net</a></li><li><a href="CB_Net.Fetch.html">CB_Net.Fetch</a></li><li><a href="CB_Net.REST.html">CB_Net.REST</a></li><li><a href="CB_Net.Sockets.html">CB_Net.Sockets</a></li><li><a href="CB_Net.Sockets.SockJS.html">CB_Net.Sockets.SockJS</a></li><li><a href="CB_Net.XHR.html">CB_Net.XHR</a></li><li><a href="CB_Pointer.html">CB_Pointer</a></li><li><a href="CB_Screen.html">CB_Screen</a></li><li><a href="CB_Speaker.html">CB_Speaker</a></li><li><a href="CB_Touch.html">CB_Touch</a></li><li><a href="CB_baseSymbols.html">CB_baseSymbols</a></li>
37 </ul>
38 </li>
39
40 <li class="dropdown">
41 <a href="classes.list.html" class="dropdown-toggle" data-toggle="dropdown">Classes<b class="caret"></b></a>
42 <ul class="dropdown-menu inline">
43 <li><a href="CB_AudioFile.html">CB_AudioFile</a></li><li><a href="CB_AudioFileCache.html">CB_AudioFileCache</a></li><li><a href="CB_AudioFileSprites.html">CB_AudioFileSprites</a></li><li><a href="CB_AudioFileSpritesPool.html">CB_AudioFileSpritesPool</a></li><li><a href="CB_AudioFile_API.AAPI.html">CB_AudioFile_API.AAPI</a></li><li><a href="CB_AudioFile_API.ACMP.html">CB_AudioFile_API.ACMP</a></li><li><a href="CB_AudioFile_API.SM2.html">CB_AudioFile_API.SM2</a></li><li><a href="CB_AudioFile_API.WAAPI.html">CB_AudioFile_API.WAAPI</a></li><li><a href="CB_Canvas.html">CB_Canvas</a></li><li><a href="CB_GraphicSprites.html">CB_GraphicSprites</a></li><li><a href="CB_GraphicSpritesScene.html">CB_GraphicSpritesScene</a></li>
44 </ul>
45 </li>
46
47 <li class="dropdown">
48 <a href="global.html" class="dropdown-toggle" data-toggle="dropdown">Global<b class="caret"></b></a>
49 <ul class="dropdown-menu inline">
50 <li><a href="global.html#CB_BASE_NAME">CB_BASE_NAME</a></li><li><a href="global.html#CB_CREDITS_DEFAULT">CB_CREDITS_DEFAULT</a></li><li><a href="global.html#CB_NAME">CB_NAME</a></li><li><a href="global.html#CB_OPTIONS">CB_OPTIONS</a></li><li><a href="global.html#CB_VERSION">CB_VERSION</a></li><li><a href="global.html#CB_addCredits">CB_addCredits</a></li><li><a href="global.html#CB_baseToBase">CB_baseToBase</a></li><li><a href="global.html#CB_baseToInt">CB_baseToInt</a></li><li><a href="global.html#CB_br2nl">CB_br2nl</a></li><li><a href="global.html#CB_brToNl">CB_brToNl</a></li><li><a href="global.html#CB_combineArraysOrObjects">CB_combineArraysOrObjects</a></li><li><a href="global.html#CB_combineAutomatically">CB_combineAutomatically</a></li><li><a href="global.html#CB_combineJSON">CB_combineJSON</a></li><li><a href="global.html#CB_combineURIParameters">CB_combineURIParameters</a></li><li><a href="global.html#CB_combineURLParameters">CB_combineURLParameters</a></li><li><a href="global.html#CB_console">CB_console</a></li><li><a href="global.html#CB_copyObject">CB_copyObject</a></li><li><a href="global.html#CB_countDecimalDigits">CB_countDecimalDigits</a></li><li><a href="global.html#CB_countDecimalPart">CB_countDecimalPart</a></li><li><a href="global.html#CB_countDecimals">CB_countDecimals</a></li><li><a href="global.html#CB_countIntegerDigits">CB_countIntegerDigits</a></li><li><a href="global.html#CB_countIntegerPart">CB_countIntegerPart</a></li><li><a href="global.html#CB_credits">CB_credits</a></li><li><a href="global.html#CB_forEach">CB_forEach</a></li><li><a href="global.html#CB_forceString">CB_forceString</a></li><li><a href="global.html#CB_getBase64StringObject">CB_getBase64StringObject</a></li><li><a href="global.html#CB_getCookie">CB_getCookie</a></li><li><a href="global.html#CB_getDatum">CB_getDatum</a></li><li><a href="global.html#CB_getJSONPropertyValue">CB_getJSONPropertyValue</a></li><li><a href="global.html#CB_getLZStringObject">CB_getLZStringObject</a></li><li><a href="global.html#CB_getValueIndex">CB_getValueIndex</a></li><li><a href="global.html#CB_getValuePath">CB_getValuePath</a></li><li><a href="global.html#CB_includeJSFile">CB_includeJSFile</a></li><li><a href="global.html#CB_indexOf">CB_indexOf</a></li><li><a href="global.html#CB_init">CB_init</a></li><li><a href="global.html#CB_intToBase">CB_intToBase</a></li><li><a href="global.html#CB_isArray">CB_isArray</a></li><li><a href="global.html#CB_isEmail">CB_isEmail</a></li><li><a href="global.html#CB_isFileLocal">CB_isFileLocal</a></li><li><a href="global.html#CB_isString">CB_isString</a></li><li><a href="global.html#CB_lastIndexOf">CB_lastIndexOf</a></li><li><a href="global.html#CB_ltrim">CB_ltrim</a></li><li><a href="global.html#CB_nl2br">CB_nl2br</a></li><li><a href="global.html#CB_nlToBr">CB_nlToBr</a></li><li><a href="global.html#CB_numberFormat">CB_numberFormat</a></li><li><a href="global.html#CB_numberOfDecimalDigits">CB_numberOfDecimalDigits</a></li><li><a href="global.html#CB_numberOfDecimals">CB_numberOfDecimals</a></li><li><a href="global.html#CB_numberOfIntegerDigits">CB_numberOfIntegerDigits</a></li><li><a href="global.html#CB_parseJSON">CB_parseJSON</a></li><li><a href="global.html#CB_parseString">CB_parseString</a></li><li><a href="global.html#CB_regularExpressionString">CB_regularExpressionString</a></li><li><a href="global.html#CB_renderString">CB_renderString</a></li><li><a href="global.html#CB_replaceAll">CB_replaceAll</a></li><li><a href="global.html#CB_rtrim">CB_rtrim</a></li><li><a href="global.html#CB_scriptPath">CB_scriptPath</a></li><li><a href="global.html#CB_scriptPathCalculate">CB_scriptPathCalculate</a></li><li><a href="global.html#CB_setCookie">CB_setCookie</a></li><li><a href="global.html#CB_setDatum">CB_setDatum</a></li><li><a href="global.html#CB_sizeOf">CB_sizeOf</a></li><li><a href="global.html#CB_sizeof">CB_sizeof</a></li><li><a href="global.html#CB_stringifyJSON">CB_stringifyJSON</a></li><li><a href="global.html#CB_symmetricCall">CB_symmetricCall</a></li><li><a href="global.html#CB_symmetricCallClear">CB_symmetricCallClear</a></li><li><a href="global.html#CB_this">CB_this</a></li><li><a href="global.html#CB_trim">CB_trim</a></li>
51 </ul>
52 </li>
53
54 </ul>
55
56 <div class="col-sm-3 col-md-3">
57 <form class="navbar-form" role="search">
58 <div class="input-group">
59 <input type="text" class="form-control" placeholder="Search" name="q" id="search-input">
60 <div class="input-group-btn">
61 <button class="btn btn-default" id="search-submit"><i class="glyphicon glyphicon-search"></i></button>
62 </div>
63 </div>
64 </form>
65 </div>
66
67 </div>
68
69</div>
70</div>
71
72
73<div class="container" id="toc-content" style="width:100%;">
74<div class="row" style="width:100%;">
75
76
77 <div class="col-md-12">
78
79 <div id="main">
80
81
82 <h1 class="page-title">Source: CrossBase/audiovisual/audio/CB_AudioFileSprites.js</h1>
83
84<section>
85 <article>
86 <pre
87 class="sunlight-highlight-javascript linenums">/**
88 * @file Audio sprites management. Contains the {@link CB_AudioFileSprites} class.
89 * @author Joan Alba Maldonado &lt;workindalian@gmail.com>
90 * @license Creative Commons Attribution 4.0 International. See more at {@link https://crossbrowdy.com/about#what_is_the_crossbrowdy_copyright_and_license}.
91 */
92
93
94/**
95 * An object representing an audio sprite which can contain, optionally, the "startAt" and "stopAt" properties with a numeric value (representing when the audio sprite starts and when it stops, respectively). If not set, the default "startAt" value will be 0 (zero) and the default "stopAt" value will be null (which means it will not stop until the end of the audio is reached unless it is paused or stopped before). The "fake" property should never be used as it is used internally to distinguish real sprites from fake ones (generated and returned by the {@link CB_AudioFileSprites#getSprite} method when a requested sprite is not found).
96 * @example { startAt: 10, stopAt: 20 }
97 * @memberof CB_AudioFileSprites
98 * @typedef {Object} CB_AudioFileSprites.SPRITE_OBJECT
99 * @property {number} [startAt=0] - The time (in milliseconds) of the audio file where the audio sprite starts. If not provided, it will use the value of 0 (zero) which means that it will start from the beginning.
100 * @property {number} [stopAt={@link CB_AudioFile_API.WAAPI#getDuration}() | {@link CB_AudioFile_API.SM2#getDuration}() | {@link CB_AudioFile_API.ACMP#getDuration}() | {@link CB_AudioFile_API.AAPI#getDuration}()] - The time (in milliseconds) of the audio file where the audio sprite stops. If not provided (not recommended), it will use the whole duration of the file (which means until it reaches its end). NOTE: Due to some possible problems between clients with different audio APIs calculating the duration of an audio file, it is recommended to always set the "stopAt" property even when we want it to stop at the end of the audio.
101 */
102
103
104/**
105 * Object whose property names the identifiers of each sprite (a case-sensitive string) and their value is a {@link CB_AudioFileSprites.SPRITE_OBJECT} object.
106 * @example
107 * {
108 * "whole_audio" : {},
109 * "first_sprite" : { stopAt: 10 },
110 * "second_sprite" : { startAt: 10, stopAt: 20 },
111 * "third_sprite" : { startAt: 20 },
112 * ...
113 * }
114 * @memberof CB_AudioFileSprites
115 * @typedef {Object} CB_AudioFileSprites.SPRITES_OBJECT
116 * @property {CB_AudioFileSprites.SPRITE_OBJECT} spriteInformation - Being the name of each property the identifier of a sprite (a string which cannot be "_WITHOUT_SPRITE_ASSOCIATED" as it is a reserved name), the value will always be a {@link CB_AudioFileSprites.SPRITE_OBJECT} object.
117 */
118
119
120/**
121 * Object with the desired data and options for the audio sprites. It is almost identical to the {@link CB_AudioFileCache.DATA_OBJECT} but adding a "sprites" property.
122 * @memberof CB_AudioFileSprites
123 * @typedef {Object} CB_AudioFileSprites.DATA_OBJECT
124 * @property {CB_AudioFileCache.URIS_OBJECT} URIs - Object whose property names audio formats and their value is an array of strings with the URIs (audio file paths or audio data URIs) of the audio files in order of preference. The best audio format for the current client will be tried to be calculated and it will use the first working URI (audio file path or data URI). The more audio formats and URIs provided the better, as it will help to maximize the compatibility with as many clients as possible (as some audio APIs and client just support some formats, or use absolute paths instead of relative ones, etc.). Even with different formats, all provided URIs should belong to the same audio (this means same sound or same music, with same length, etc.). NOTE: Only some clients with some audio APIs will support data URIs. If a valid value is given, this will be added to the {@link CB_AudioFileCache#URIs} property.
125 * @property {CB_AudioFileSprites.SPRITES_OBJECT} [sprites] Object with the desired sprites. It will be used as the first parameter to call the {@link CB_AudioFileSprites#insertSprites} method internally. It will be added (after being processed) to the {@link CB_AudioFileCache#sprites} property.
126 * @property {string} [id=""] - Desired identifier for the audio file sprites object. Internal usage only recommended. If a valid value is given, this will be added to the {@link CB_AudioFileSprites#id} property as well as to the {@link CB_AudioFileCache#id} property of the internally-created {@link CB_AudioFileCache} object.
127 * @property {array} [preferredAPIs={@link CB_Configuration.CrossBase.CB_AudioFileCache_PREFERRED_AUDIO_APIS}] - Array of strings with the preferred audio API or audio APIs, in order of preference. Possible audio APIs are "WAAPI" ([HTML5 Web Audio API]{@link https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API}), "SM2" ([SoundManager 2]{@link http://schillmania.com/projects/soundmanager2/}), "ACMP" ([Apache Cordova Media Plugin]{@link https://github.com/apache/cordova-plugin-media}) or "AAPI" ([HTML5 Audio API]{@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/audio}). 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 {@link CB_AudioFileCache#preferredAPIs} property.
128 * @property {array} [preferredFormats={@link CB_Configuration.CrossBase.CB_AudioFileCache_PREFERRED_AUDIO_FORMATS}] - 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 {@link CB_AudioFileCache#preferredFormats} property.
129 * @property {integer} [minimumAudioFiles={@link CB_AudioFileCache.minimumAudioFiles_DEFAULT}] - Minimum {@link CB_AudioFile} objects to create internally. It must be an integer being 1 the minimum. If a valid value is given, this will be added to the {@link CB_AudioFileCache#minimumAudioFiles} property.
130 * @property {integer} [maximumAudioFiles={@link CB_AudioFileCache.maximumAudioFiles_DEFAULT}] - Maximum {@link CB_AudioFile} objects that are to be created internally. 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 {@link CB_AudioFileCache#minimumAudioFiles} property (also provided by the "minimumAudioFiles" of this object), allowing 1 minimum. If a valid value is given, this will be added to the {@link CB_AudioFileCache#maximumAudioFiles} property.
131 * @property {integer} [minimumAudioFilesFree=parseInt({@link CB_AudioFileCache#minimumAudioFiles} * 0.25 + 0.5)] - New {@link CB_AudioFile} objects will be created internally when the number of free {@link CB_AudioFile} objects reaches this limit. If provided, it must be an integer being 0 (zero) the minimum. It will end using a 25% of the {@link CB_AudioFileCache#minimumAudioFiles} by default, rounded to ceil, allowing 0 (zero) minimum. If a valid value is given, this will be added to the {@link CB_AudioFileCache#minimumAudioFilesFree} property.
132 * @property {integer} [newAudioFilesWhenNeeded=Math.min(parseInt({@link CB_AudioFileCache#minimumAudioFiles} * 0.1 + 0.5), 1)] - Number of new {@link CB_AudioFile} objects to create internally when the minimum limit of free {@link CB_AudioFile} objects ({@link CB_AudioFileCache#minimumAudioFilesFree}) is reached. If provided, it must be an integer being 0 (zero) the minimum. It will end using a 10% of the {@link CB_AudioFileCache#minimumAudioFiles} by default, rounded to ceil, allowing 1 minimum. If a valid value is given, this will be added to the {@link CB_AudioFileCache#newAudioFilesWhenNeeded} property.
133 * @property {integer} [retries={@link CB_AudioFileCache.retries_DEFAULT}] - Number of retries to try to load a {@link CB_AudioFile} object internally before trying to load the next possible one internally (if any). It must be an integer being 0 the minimum. If a valid value is given, this will be added to the {@link CB_AudioFileCache#retries} property.
134 * @property {boolean} [checkManually={@link CB_AudioFileCache.checkManually_DEFAULT}] - Tells whether the {@link CB_AudioFile} objects must be checked automatically or not (manually) by default. If a valid value is given, this will be added to the {@link CB_AudioFileCache#checkManually} property.
135 * @property {boolean} [checkManuallyOnNeededCreated={@link CB_AudioFileCache.checkManuallyOnNeededCreated_DEFAULT}] - Tells whether the {@link CB_AudioFile} objects must be checked automatically or not (manually) when creates a new {@link CB_AudioFile} object needed. If a valid value is given, this will be added to the {@link CB_AudioFileCache#checkManuallyOnNeededCreated} property.
136 * @property {boolean} [checkManuallyOnPlayingFailed={@link CB_AudioFileCache.checkManuallyOnPlayingFailed_DEFAULT}] - Tells whether the {@link CB_AudioFile} objects must be checked automatically or not (manually) when playing one has failed and tries to reload it. If a valid value is given, this will be added to the {@link CB_AudioFileCache#checkManuallyOnPlayingFailed} property.
137 * @property {boolean} [checkManuallyOnCheckingFailed={@link CB_AudioFileCache.checkManuallyOnCheckingFailed_DEFAULT}] - Tells whether the {@link CB_AudioFile} objects must be checked automatically or not (manually) when checking one has failed and tries to reload it. If a valid value is given, this will be added to the {@link CB_AudioFileCache#checkManuallyOnCheckingFailed} property.
138 * @property {function} [onLoad] - Desired function to be called once the cache has been loaded. The first and unique parameter will be an integer with the {@link CB_AudioFile} objects that still need to be checked, if any, being "this" the current {@link CB_AudioFileCache} object. If a valid value is given, this will be added to the {@link CB_AudioFileCache#onLoad} property.
139 * @property {function} [onError] - 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 {@link CB_AudioFileCache} object. If a valid value is given, this will be added to the {@link CB_AudioFileCache#onError} property.
140 * @property {boolean} [disableAutoLoad=false] - If set to true, it will not create automatically the {@link CB_AudioFile} objects by calling the {@link CB_AudioFileCache#createAudioFiles} method internally. Internal usage only recommended.
141 */
142
143
144/**
145 * The constructor is 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.
146 * @class
147 * @classdesc Class to manage audio sprites of a {@link CB_AudioFileCache} object (used internally).
148 * @param {CB_AudioFileSprites.DATA_OBJECT} [dataObject] - Object with the desired data and options for the audio sprites. Although it can contain a "sprites" property, it will also be used as the first and unique parameter when calling the constructor of the {@link CB_AudioFileCache} object internally.
149 * @returns {CB_AudioFileSprites} Returns a new {@link CB_AudioFileSprites} object.
150 * @todo Do not allow to create one object with an "id" which has already been used (unless the value is undefined, null...).
151 * @todo Think about using wrapper to replace "this" in callbacks (callbackOk, callbackError) to point to the {@link CB_AudioFileSprites} object itself.
152 * @todo Method getCopy and static method filterProperties (similar to the ones from {@link CB_GraphicSprites} and {@link CB_GraphicSpritesScene}).
153 */
154var CB_AudioFileSprites = function(dataObject)
155{
156 //Creates an instance of this object and returns it in the case that it is being called from an unexpected context:
157 if (this === window || !(this instanceof CB_AudioFileSprites)) { return new CB_AudioFileSprites(dataObject); }
158
159 //Properties and variables:
160 /**
161 * Stores the identifier for the audio file sprites object.
162 * @var
163 * @readonly
164 * @type {string}
165 * @default
166 */
167 this.id = "";
168
169 /**
170 * Object with information about the sprites.
171 * @var
172 * @readonly
173 * @type {CB_AudioFileSprites.SPRITES_OBJECT}
174 * @default
175 */
176 this.sprites = {};
177
178 /**
179 * Object whose property names are the sprite identifiers (strings), including one called "_WITHOUT_SPRITE_ASSOCIATED" for sound instances without a sprite associated, and their values are an array containing the sound instance identifiers (created by the {@link CB_AudioFileSprites#play} method). Internal usage only recommended.
180 * @var
181 * @readonly
182 * @type {Object}
183 * @default { "_WITHOUT_SPRITE_ASSOCIATED" : [] }
184 */
185 this.spriteSoundInstances = { "_WITHOUT_SPRITE_ASSOCIATED" : [] }; //Object with the sound instances associated to each sprite ID.
186
187
188 //If not defined, defines a fake prototype object:
189 CB_AudioFileSprites._audioFileCachePrototype = CB_AudioFileSprites._audioFileCachePrototype ||
190 {
191 DEFAULT_ERROR_MESSAGE : "CB_AudioFileCache object not loaded (using prototype).",
192 usingPrototype : true,
193 status : CB_AudioFileCache.UNLOADED,
194 audioFiles : [],
195 audioFilesCreated : 0,
196 audioFilesFreePointer : 0,
197 soundInstancesQueued : {},
198 duration : 0,
199 destructor : function() {},
200 createAudioFiles : function() { return 0; },
201 createAudioFile : function(URIs, preferredAPIs, preferredFormats, audioObject, callbackOk, callbackError)
202 {
203 if (typeof(callbackError) === "function") { callbackError.call(CB_AudioFileSprites._audioFileCachePrototype, DEFAULT_ERROR_MESSAGE); }
204 return null;
205 },
206 clearAudioFiles : function() { return []; },
207 removeAudioFile : function() { return null; },
208 purge : function() { return 0; },
209 getFreeAudioFile : function() { return { "object" : null, "index" : -1 }; },
210 isAudioFileFree : function() { return false; },
211 clearSoundInstances : function() { return 0; },
212 cancelSoundInstances : function() { return false; },
213 cancelSoundInstance : function() { return false; },
214 getAudioFileBySoundInstanceId : function() { return null; },
215 play : function(startAt, stopAt, loop, volume, allowedRecursiveDelay, allowedRecursiveDelaySkipping, onPlayStart, onStop)
216 {
217 if (typeof(onStop) === "function") { onStop(); }
218 return null;
219 },
220 executeFunctionAll : function() { return 0; },
221 destroyAll : function() { return 0; },
222 checkPlayingAll : function(callbackOk, callbackError)
223 {
224 if (typeof(callbackError) === "function") { callbackError.call(CB_AudioFileSprites._audioFileCachePrototype, DEFAULT_ERROR_MESSAGE); }
225 return 0;
226 },
227 playAll : function(startAt, stopAt, loop, volume, avoidDelayedPlay, allowedRecursiveDelay, onPlayStart, onStop)
228 {
229 if (typeof(onStop) === "function") { onStop(); }
230 return 0;
231 },
232 stopAll : function() { return 0; },
233 playAndStopAll : function() { return 0; },
234 pauseAll : function() { return 0; },
235 resumeAll : function(loop, allowedRecursiveDelay, allowedRecursiveDelaySkipping, onPlayStart, onStop)
236 {
237 if (typeof(onStop) === "function") { onStop(); }
238 return 0;
239 },
240 muteAll : function() { return 0; },
241 unmuteAll : function() { return 0; },
242 setVolumeAll : function() { return 0; },
243 setAudioAPIAll : function(preferredAPIs, callbackOk, callbackError)
244 {
245 if (typeof(callbackError) === "function") { callbackError.call(CB_AudioFileSprites._audioFileCachePrototype, DEFAULT_ERROR_MESSAGE); }
246 return 0;
247 },
248 getStatus : function() { return CB_AudioFileCache.UNLOADED; },
249 getStatusString : function() { return "UNLOADED"; },
250 getAudioFilesFreeNumber : function() { return 0; },
251 getAudioFiles : function() { return []; },
252 getAudioFilesFree : function() { return []; },
253 getAudioFilesBusy : function() { return []; },
254 getAudioFilesNumber : function() { return 0; },
255 getDuration : function() { return 0; },
256 getProgress : function() { return 0; },
257 isPlaying : function() { return false; }
258 };
259
260
261 /**
262 * Contains the {@link CB_AudioFileCache} object. Internal usage only recommended.
263 * @var
264 * @readonly
265 * @type {CB_AudioFileCache}
266 * @default
267 */
268 this.audioFileCache = CB_AudioFileSprites._audioFileCachePrototype; //Keeps the CB_AudioFileCache object.
269
270
271 //Calls the constructor of the object when creates an instance:
272 return this._init(dataObject);
273}
274
275
276//Constructor:
277CB_AudioFileSprites.prototype._init = function(dataObject)
278{
279 /*
280 FORMAT:
281 dataObject =
282 {
283 [id : String,]
284 [preferredAPIs : Array&lt;String>,]
285 [preferredFormats : Array&lt;String>,]
286 URIs : Object,
287 [minimumAudioFiles : Integer,]
288 [maximumAudioFiles : Integer,]
289 [minimumAudioFilesFree : Integer,]
290 [newAudioFilesWhenNeeded : Integer,]
291 [retries : Integer,]
292 [checkManually : Boolean,]
293 [checkManuallyOnNeededCreated : Boolean,]
294 [checkManuallyOnPlayingFailed : Boolean,]
295 [checkManuallyOnCheckingFailed : Boolean,]
296 [disableAutoLoad : Boolean,]
297 [onLoad : Function,]
298 [onError : Function,]
299 sprites :
300 {
301 "sprite_id" :
302 {
303 [startAt : Integer,]
304 [stopAt : Integer,]
305 }
306 [, ...]
307 }
308 };
309 */
310
311 //Tries to load the data (if any):
312 this.load(dataObject);
313
314 //Returns the object:
315 return this;
316}
317
318
319/**
320 * Destroys the audio file sprites object (removing all sprites, etc.), including the internal audio file cache object, and frees memory. By default, unless the "preventAbortedStatus" is set to true, sets the current status of the {@link CB_AudioFileCache} object as ABORTED ({@link CB_AudioFileCache.ABORTED} value).
321 * @function
322 * @param {boolean} [stopSounds=false] - Used as the "stopSounds" parameter when calling internally the {@link CB_AudioFileCache#destructor} method of the {@link CB_AudioFileCache} object.
323 * @param {boolean} [preventAbortedStatus=false] - If set to true (not recommended), it will not assign the status of "ABORTED" (it will not assign the value of {@link CB_AudioFileCache.ABORTED} to the {@link CB_AudioFileCache#status} property).
324 */
325CB_AudioFileSprites.prototype.destructor = function(stopSounds, preventAbortedStatus)
326{
327 //Resets properties to their default value:
328 this.sprites = {};
329 this.spriteSoundInstances = { "_WITHOUT_SPRITE_ASSOCIATED" : [] };
330
331 //Destroys the CB_AudioFileCache object:
332 this.audioFileCache.destructor(stopSounds, preventAbortedStatus);
333 this.audioFileCache = CB_AudioFileSprites._audioFileCachePrototype;
334}
335
336
337/**
338 * Loads the audio file sprites 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.
339 * @function
340 * @param {CB_AudioFileSprites.DATA_OBJECT} dataObject - Object with the desired data and options for the audio file sprites.
341 * @returns {CB_AudioFileSprites|null} If a "dataObject" is given, it returns the current {@link CB_AudioFileSprites} object. Otherwise, it returns null.
342 */
343CB_AudioFileSprites.prototype.load = function(dataObject)
344{
345 if (typeof(dataObject) === "undefined" || dataObject === null) { return null; }
346
347 //Destroys all previous data (if any):
348 this.destructor(true, true); //Also stops all sounds.
349
350 //Sanitizes the given data:
351 dataObject.id = CB_trim(dataObject.id);
352
353 //Sets the new data:
354 if (dataObject.id !== "") { this.id = dataObject.id; }
355
356 //Inserts the sprites:
357 if (typeof(dataObject.sprites) !== "undefined" &amp;&amp; dataObject.sprites !== null)
358 {
359 this.removeSprites();
360 this.insertSprites(dataObject.sprites);
361 }
362
363 //Creates the audio file cache object:
364 this.audioFileCache = new CB_AudioFileCache(dataObject);
365
366 return this;
367}
368
369
370/**
371 * Alias for {@link CB_AudioFileSprites#removeSprites}.
372 * @function CB_AudioFileSprites#removeSpritesAll
373 * @see {@link CB_AudioFileSprites#removeSprites}
374 */
375/**
376 * Removes all the sprites by clearing the {@link CB_AudioFileSprites#sprites} property.
377 * @function
378 */
379CB_AudioFileSprites.prototype.removeSprites = CB_AudioFileSprites.prototype.removeSpritesAll = function()
380{
381 this.sprites = {};
382}
383
384
385/**
386 * Inserts the given sprites. It will keep the existing ones. If a sprite identifier already existed and it is given again (not recommended), it will be replaced by the new one (but keeping its current sound instances, if any).
387 * @function
388 * @param {CB_AudioFileSprites.SPRITES_OBJECT} sprites - Object with the desired sprites.
389 * @returns {integer} Returns the number of sprites inserted.
390 */
391CB_AudioFileSprites.prototype.insertSprites = function(sprites)
392{
393 var inserted = 0;
394 if (typeof(sprites) !== "undefined" &amp;&amp; sprites !== null)
395 {
396 for (var spriteId in sprites)
397 {
398 //Inserts the sprite:
399 if (this.insertSprite(sprites[spriteId], spriteId)) { inserted++; }
400 }
401 }
402 return inserted;
403}
404
405
406/**
407 * Inserts the given sprite. It will keep the existing ones. If a sprite identifier already existed and it is given again (not recommended), it will be replaced by the new one (but keeping its current sound instances, if any).
408 * @function
409 * @param {CB_AudioFileSprites.SPRITE_OBJECT} sprite - Object with the desired sprite.
410 * @param {string} spriteId - The identifier for the sprite.
411 * @returns {boolean} Returns true if the sprite has been inserted or false otherwise.
412 */
413CB_AudioFileSprites.prototype.insertSprite = function(sprite, spriteId)
414{
415 if (typeof(spriteId) === "undefined" || spriteId === null) { return false; }
416
417 this.sprites[spriteId] = {};
418
419 this.setStartAtSprite(spriteId, (typeof(sprite.startAt) === "undefined") ? undefined : sprite.startAt);
420 this.setStopAtSprite(spriteId, (typeof(sprite.stopAt) === "undefined") ? undefined : sprite.stopAt);
421
422 if (typeof(this.spriteSoundInstances[spriteId]) === "undefined" || this.spriteSoundInstances[spriteId] === null)
423 {
424 this.spriteSoundInstances[spriteId] = [];
425 }
426
427 return true;
428}
429
430
431/**
432 * Sets when a sprite begins (stored in its "startAt" property), by sprite identifier.
433 * @function
434 * @param {string} spriteId - The identifier for the sprite.
435 * @param {number} startAt - The time (in milliseconds) of the audio file where the audio sprite starts.
436 * @returns {boolean} Returns true if the sprite has been modified or false otherwise.
437 */
438CB_AudioFileSprites.prototype.setStartAtSprite = function(spriteId, startAt)
439{
440 if (typeof(this.sprites[spriteId]) === "undefined" || this.sprites[spriteId] === null) { return false; }
441
442 this.sprites[spriteId].startAt = 0;
443 if (typeof(startAt) !== "undefined" &amp;&amp; startAt !== null &amp;&amp; !isNaN(startAt) &amp;&amp; startAt >= 0 &amp;&amp; this.sprites[spriteId].startAt !== startAt)
444 {
445 this.sprites[spriteId].startAt = startAt;
446 return true;
447 }
448
449 return false;
450}
451
452
453/**
454 * Sets when a sprite ends (stored in its "stopAt" property), by sprite identifier.
455 * @function
456 * @param {string} spriteId - The identifier for the sprite.
457 * @param {number} stopAt - The time (in milliseconds) of the audio file where the audio sprite ends.
458 * @returns {boolean} Returns true if the sprite has been modified or false otherwise.
459 */
460CB_AudioFileSprites.prototype.setStopAtSprite = function(spriteId, stopAt)
461{
462 if (typeof(this.sprites[spriteId]) === "undefined" || this.sprites[spriteId] === null) { return false; }
463
464 this.sprites[spriteId].stopAt = null;
465 if (typeof(stopAt) !== "undefined" &amp;&amp; stopAt !== null &amp;&amp; !isNaN(stopAt) &amp;&amp; stopAt > this.sprites[spriteId].startAt &amp;&amp; this.sprites[spriteId].stopAt !== stopAt)
466 {
467 this.sprites[spriteId].stopAt = stopAt;
468 return true;
469 }
470
471 return false;
472}
473
474
475/**
476 * Removes a sprite by its ID.
477 * @function
478 * @param {string} spriteId - The identifier for the sprite.
479 * @returns {boolean} Returns true if the sprite has been deleted or false otherwise.
480 */
481CB_AudioFileSprites.prototype.removeSprite = function(spriteId)
482{
483 if (typeof(this.sprites[spriteId]) !== "undefined" &amp;&amp; this.sprites[spriteId] !== null)
484 {
485 this.sprites[spriteId] = null;
486 var sprites = {};
487 var deleted = false;
488 for (spriteId in this.sprites)
489 {
490 if (typeof(this.sprites[spriteId]) !== "undefined" &amp;&amp; this.sprites[spriteId] !== null)
491 {
492 sprites[spriteId] = this.sprites[spriteId];
493 deleted = true;
494 }
495 }
496 this.sprites = sprites;
497 return deleted;
498 }
499 return false;
500}
501
502
503/**
504 * Returns a sprite by its ID.
505 * @function
506 * @param {string} spriteId - The identifier for the sprite.
507 * @returns {CB_AudioFileSprites.SPRITE_OBJECT} Returns the desired sprite or a fake object if it was not found. The fake object will be this one: { "startAt" : 0, "stopAt" : null, "fake" : true }.
508 */
509CB_AudioFileSprites.prototype.getSprite = function(spriteId)
510{
511 if (typeof(this.sprites[spriteId]) !== "undefined")
512 {
513 return this.sprites[spriteId];
514 }
515 return { "startAt" : 0, "stopAt" : null, "fake" : true };
516}
517
518
519/**
520 * Returns an object with the sprites (and includes "_WITHOUT_SPRITE_ASSOCIATED" if we want to).
521 * @function
522 * @param {boolean} [includeWithoutSpriteAssociated=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 property existed before in the object stored in the {@link CB_AudioFileSprites#sprites} property and had a value which is not an empty object). If set to false, the returning object will not contain the "_WITHOUT_SPRITE_ASSOCIATED" property unless the property existed before in the object stored in the {@link CB_AudioFileSprites#sprites} property.
523 * @returns {CB_AudioFileSprites.SPRITES_OBJECT} Returns an object with the sprites (and includes "_WITHOUT_SPRITE_ASSOCIATED" if we want to).
524 */
525CB_AudioFileSprites.prototype.getSprites = function(includeWithoutSpriteAssociated)
526{
527 if (!includeWithoutSpriteAssociated) { return this.sprites; }
528 else
529 {
530 var sprites = {};
531 sprites["_WITHOUT_SPRITE_ASSOCIATED"] = {};
532 for (var spriteId in this.sprites)
533 {
534 sprites[spriteId] = this.sprites[spriteId];
535 }
536 return sprites;
537 }
538}
539
540
541/**
542 * Returns an array of the sound instance identifiers (created by the {@link CB_AudioFileSprites#play} method) used by the given sprite identifier.
543 * @function
544 * @param {string} spriteId - The identifier for the sprite.
545 * @returns {array} Returns a numeric array of the sound instances (created by the {@link CB_AudioFileSprites#play} method) used by the given sprite identifier.
546 */
547CB_AudioFileSprites.prototype.getSoundInstancesIdBySpriteId = function(spriteId)
548{
549 if (typeof(this.spriteSoundInstances[spriteId]) !== "undefined")
550 {
551 return this.spriteSoundInstances[spriteId];
552 }
553 return [];
554}
555
556
557/**
558 * Returns the sound instances (their ID) used (stored in the {@link CB_AudioFileSprites#spriteSoundInstances} property).
559 * @function
560 * @param {boolean} [oneDimension=false] - If set to true, it will return the {@link CB_AudioFileSprites#spriteSoundInstances} property directly (which includes the "_WITHOUT_SPRITE_ASSOCIATED" property for sound instances without a sprite associated). Otherwise, if it is set to true, it will return a numeric array whose values are the sound instance IDs.
561 * @param {boolean} [includeWithoutSpriteAssociated=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 {@link CB_AudioFileSprites#getSprites} method internally. Only used when the "oneDimension" parameter is set to true.
562 * @returns {Object|array} Returns the sound instances (their ID) used (stored in the {@link CB_AudioFileSprites#spriteSoundInstances} property). If the "oneDimension" parameter is set to false, the property names of the returning object are the sprite identifiers (strings), including one called "_WITHOUT_SPRITE_ASSOCIATED" for sound instances without a sprite associated, and their values are an array containing the sound instance IDs. 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).
563 */
564CB_AudioFileSprites.prototype.getSoundInstancesId = function(oneDimension, includeWithoutSpriteAssociated)
565{
566 if (!oneDimension)
567 {
568 return this.spriteSoundInstances;
569 }
570 else
571 {
572 var soundInstances = [];
573 var soundInstancesSprite;
574 var soundInstancesSpriteLength;
575 var y = 0;
576 var x = 0;
577 var sprites = this.getSprites(includeWithoutSpriteAssociated);
578 for (var spriteId in sprites)
579 {
580 soundInstancesSprite = this.getSoundInstancesIdBySpriteId(spriteId);
581 soundInstancesSpriteLength = soundInstancesSprite.length;
582 for (x = 0; x &lt; soundInstancesSpriteLength; x++)
583 {
584 soundInstances[y++] = soundInstancesSprite[x];
585 }
586 }
587 return soundInstances;
588 }
589}
590
591
592/**
593 * Returns an array of the {@link CB_AudioFile} objects used by the sound instances that belong to a given sprite identifier.
594 * @function
595 * @param {string} spriteId - The identifier for the sprite.
596 * @param {boolean} [avoidCancelled=false] - If set to true, it will not return the {@link CB_AudioFile} objects whose sound instance has been cancelled. Used as the "avoidCancelled" parameter when calling the {@link CB_AudioFileSprites#getAudioFileBySoundInstanceId} method internally.
597 * @returns {array} Returns an array of the {@link CB_AudioFile} objects used by the sound instances that belong to the given sprite identifier.
598 */
599CB_AudioFileSprites.prototype.getAudioFilesUsedBySpriteId = function(spriteId, avoidCancelled)
600{
601 var soundInstances = this.getSoundInstancesIdBySpriteId(spriteId);
602 var audioFiles = [];
603 var y = 0;
604
605 var soundInstancesLength = soundInstances.length;
606 var currentObject = null;
607 for (var x = 0; x &lt; soundInstancesLength; x++)
608 {
609 currentObject = this.getAudioFileBySoundInstanceId(soundInstances[x], avoidCancelled);
610 if (currentObject !== null) { audioFiles[y++] = currentObject; }
611 }
612
613 return audioFiles;
614}
615
616
617/**
618 * Object returned by the {@link CB_AudioFileSprites#getAudioFilesUsed} method. Each property names will be the sprites identifiers except the "_WITHOUT_SPRITE_ASSOCIATED" property for sound instances without a sprite associated (if we wanted to include them).
619 * @memberof CB_AudioFileSprites
620 * @typedef {Object} CB_AudioFileSprites.getAudioFilesUsed_OBJECT
621 * @property {CB_AudioFile} spriteId - Each property name will be a sprite identifier (it can be "_WITHOUT_SPRITE_ASSOCIATED" for sound instances without a sprite associated, if we wanted to include them). The value will be a numeric array with the {@link CB_AudioFile} objects used.
622 */
623
624/**
625 * Returns the {@link CB_AudioFile} objects used by all the sounds instances currently created.
626 * @function
627 * @param {boolean} [oneDimension=false] - If set to false, it will return 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 {@link CB_AudioFile} objects used. Otherwise, if set to true, it will return a numeric array with the {@link CB_AudioFile} objects used (if the "includeWithoutSpriteAssociated" parameter is set to true, it will also contain the {@link CB_AudioFile} objects whose sound instance ID is not associated to any sprite).
628 * @param {boolean} [includeWithoutSpriteAssociated=false] - If set to true, it will also return the {@link CB_AudioFile} objects whose sound instance ID is not associated to any sprite. Used as the "includeWithoutSpriteAssociated" parameter when calling the {@link CB_AudioFileSprites#getSprites} method internally.
629 * @param {boolean} [avoidCancelled=false] - If set to true, it will not return the {@link CB_AudioFile} objects whose sound instance has been cancelled. Used as the "avoidCancelled" parameter when calling the {@link CB_AudioFileSprites#getAudioFilesUsedBySpriteId} method internally.
630 * @returns {CB_AudioFileSprites.getAudioFilesUsed_OBJECT|array} Returns the {@link CB_AudioFile} objects used by all the sounds instances currently created. If the "oneDimension" parameter is set to false, it will return a {@link 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 {@link CB_AudioFile} objects used. Otherwise, if the "oneDimension" parameter set to true, it will return a numeric array with the {@link CB_AudioFile} objects used (if the "includeWithoutSpriteAssociated" parameter is set to true, it will also contain the {@link CB_AudioFile} objects whose sound instance ID is not associated to any sprite).
631 */
632CB_AudioFileSprites.prototype.getAudioFilesUsed = function(oneDimension, includeWithoutSpriteAssociated, avoidCancelled)
633{
634 var audioFiles;
635 var sprites = this.getSprites(includeWithoutSpriteAssociated);
636 if (!oneDimension)
637 {
638 audioFiles = {};
639 for (var spriteId in sprites)
640 {
641 audioFiles[spriteId] = this.getAudioFilesUsedBySpriteId(spriteId, avoidCancelled);
642 }
643 }
644 else
645 {
646 audioFiles = [];
647 var audioFilesSprite;
648 var audioFilesSpriteLength;
649 var y = 0;
650 var x = 0;
651 for (var spriteId in sprites)
652 {
653 audioFilesSprite = this.getAudioFilesUsedBySpriteId(spriteId, avoidCancelled);
654 audioFilesSpriteLength = audioFilesSprite.length;
655 for (x = 0; x &lt; audioFilesSpriteLength; x++)
656 {
657 audioFiles[y++] = audioFilesSprite[x];
658 }
659 }
660 }
661 return audioFiles;
662}
663
664
665/**
666 * Alias for {@link CB_AudioFileSprites#executeFunctionAllSprite}.
667 * @function CB_AudioFileSprites#executeAllSprite
668 * @see {@link CB_AudioFileSprites#executeFunctionAllSprite}
669 */
670 /**
671 * Alias for {@link CB_AudioFileSprites#executeFunctionAllSprite}.
672 * @function CB_AudioFileSprites#forEachSpriteById
673 * @see {@link CB_AudioFileSprites#executeFunctionAllSprite}
674 */
675/**
676 * Executes a desired function for all the {@link CB_AudioFile} objects used by the sound instances currently created that belong to a given sprite (by its ID). It calls the {@link CB_AudioFileSprites#executeFunctionAll} method internally and returns its returning value.
677 * @function
678 * @param {string} spriteId - The identifier for the sprite.
679 * @param {CB_Arrays.executeFunctionAll_ON_LOOP_CALLBACK} functionEach - Used as the "functionEach" parameter when calling the {@link CB_AudioFileSprites#executeFunctionAll} method internally.
680 * @param {number|CB_Arrays.executeFunctionAll_ON_LOOP_CALLBACK} [delayBetweenEach=0] - Used as the "delayBetweenEach" parameter when calling the {@link CB_AudioFileSprites#executeFunctionAll} method internally.
681 * @param {boolean} [avoidCancelled=false] - If set to true, it will not affect the {@link CB_AudioFile} objects whose sound instance has been cancelled. Used as the "avoidCancelled" parameter when calling the {@link CB_AudioFileSprites#getAudioFilesUsedBySpriteId} method internally.
682 * @param {boolean} [returnSetTimeoutsArray=false] - Used as the "returnSetTimeoutsArray" parameter when calling the {@link CB_AudioFileSprites#executeFunctionAll} method internally.
683 * @param {boolean} [delayBetweenEachAffectsFirst=false] - Used as the "delayBetweenEachAffectsFirst" parameter when calling the {@link CB_AudioFileSprites#executeFunctionAll} method internally.
684 * @param {CB_Arrays.executeFunctionAll_ON_FINISH_CALLBACK} [functionFinish] - Function that will be called for when it has finished looping all the items. The first parameter will be the array which was looped, the second parameter will be the number of times that the "functionEach" callback was called (the most likely, matches the number of elements unless they are undefined or null), and the third parameter will be the maximum "delay" used, being "this" the array itself.
685 * @returns {integer|array} If the "returnSetTimeoutsArray" parameter is set to false, it will return the number of calls to the "functionEach" function that were performed (which should be the same number as the {@link CB_AudioFile} objects used by the sound instances that belong to the given sprite identifier). Otherwise, if the "returnSetTimeoutsArray" is set to true, it will return a numeric array with a {@link CB_AudioFileCache.executeFunctionAll_OBJECT} object for each {@link CB_AudioFile} given. The length of this array will also be the number of calls to the "functionEach" function that were performed. Note that if a value greater than 0 (zero) for the "delayBetweenEach" parameter has been provided, perhaps not all calls of the "functionEach" function will have been performed yet when exiting this method because of the asynchronous nature of the [setTimeout]{@link https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/setTimeout} function.
686 */
687CB_AudioFileSprites.prototype.executeFunctionAllSprite = CB_AudioFileSprites.prototype.executeAllSprite = CB_AudioFileSprites.prototype.forEachSpriteById = function(spriteId, functionEach, delayBetweenEach, avoidCancelled, returnSetTimeoutsArray, delayBetweenEachAffectsFirst, finishFunction)
688{
689 return this.executeFunctionAll(functionEach, delayBetweenEach, this.getAudioFilesUsedBySpriteId(spriteId, avoidCancelled), returnSetTimeoutsArray, delayBetweenEachAffectsFirst, finishFunction);
690}
691
692
693/**
694 * Alias for {@link CB_AudioFileSprites#executeFunctionAllSprites}.
695 * @function CB_AudioFileSprites#executeAllSprites
696 * @see {@link CB_AudioFileSprites#executeFunctionAllSprites}
697 */
698 /**
699 * Alias for {@link CB_AudioFileSprites#executeFunctionAllSprites}.
700 * @function CB_AudioFileSprites#forEachSprite
701 * @see {@link CB_AudioFileSprites#executeFunctionAllSprites}
702 */
703/**
704 * Executes a desired function for all the {@link CB_AudioFile} objects used by all the sound instances currently created. It calls the {@link CB_AudioFileSprites#executeFunctionAll} method internally and returns its returning value.
705 * @function
706 * @param {CB_Arrays.executeFunctionAll_ON_LOOP_CALLBACK} functionEach - Used as the "functionEach" parameter when calling the {@link CB_AudioFileSprites#executeFunctionAll} method internally.
707 * @param {number|CB_Arrays.executeFunctionAll_ON_LOOP_CALLBACK} [delayBetweenEach=0] - Used as the "delayBetweenEach" parameter when calling the {@link CB_AudioFileSprites#executeFunctionAll} method internally.
708 * @param {boolean} [includeWithoutSpriteAssociated=false] - If set to true, it will also affect the {@link CB_AudioFile} objects whose sound instance ID is not associated to any sprite. Used as the "includeWithoutSpriteAssociated" parameter when calling the {@link CB_AudioFileSprites#getAudioFilesUsed} method internally.
709 * @param {boolean} [avoidCancelled=false] - If set to true, it will not affect the {@link CB_AudioFile} objects whose sound instance has been cancelled. Used as the "avoidCancelled" parameter when calling the {@link CB_AudioFileSprites#getAudioFilesUsed} method internally.
710 * @param {boolean} [returnSetTimeoutsArray=false] - Used as the "returnSetTimeoutsArray" parameter when calling the {@link CB_AudioFileSprites#executeFunctionAll} method internally.
711 * @param {boolean} [delayBetweenEachAffectsFirst=false] - Used as the "delayBetweenEachAffectsFirst" parameter when calling the {@link CB_AudioFileSprites#executeFunctionAll} method internally.
712 * @param {CB_Arrays.executeFunctionAll_ON_FINISH_CALLBACK} [functionFinish] - Function that will be called for when it has finished looping all the items. The first parameter will be the array which was looped, the second parameter will be the number of times that the "functionEach" callback was called (the most likely, matches the number of elements unless they are undefined or null), and the third parameter will be the maximum "delay" used, being "this" the array itself.
713 * @returns {integer|array} If the "returnSetTimeoutsArray" parameter is set to false, it will return the number of calls to the "functionEach" function that were performed (which should be the same number as the {@link CB_AudioFile} objects used by the sound instances that belong to the sprites). Otherwise, if the "returnSetTimeoutsArray" is set to true, it will return a numeric array with a {@link CB_AudioFileCache.executeFunctionAll_OBJECT} object for each {@link CB_AudioFile} given. The length of this array will also be the number of calls to the "functionEach" function that were performed. Note that if a value greater than 0 (zero) for the "delayBetweenEach" parameter has been provided, perhaps not all calls of the "functionEach" function will have been performed yet when exiting this method because of the asynchronous nature of the [setTimeout]{@link https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/setTimeout} function.
714 */
715CB_AudioFileSprites.prototype.executeFunctionAllSprites = CB_AudioFileSprites.prototype.executeAllSprites = CB_AudioFileSprites.prototype.forEachSprite = function(functionEach, delayBetweenEach, includeWithoutSpriteAssociated, avoidCancelled, returnSetTimeoutsArray, delayBetweenEachAffectsFirst, finishFunction)
716{
717 return this.executeFunctionAll(functionEach, delayBetweenEach, this.getAudioFilesUsed(true, includeWithoutSpriteAssociated, avoidCancelled), returnSetTimeoutsArray, delayBetweenEachAffectsFirst, finishFunction);
718}
719
720
721/**
722 * Tells whether a given sprite (by its ID) is playing or not. Note that there could be more than one sound instance (with a {@CB_AudioFile} object) by each sprite with different status (paused, stopped, etc.) and this method will return true if any of them is playing.
723 * @function
724 * @param {string} spriteId - The identifier for the sprite.
725 * @returns {boolean} Returns whether a given sprite (by its ID) is playing or not.
726 */
727CB_AudioFileSprites.prototype.isPlayingSprite = function(spriteId)
728{
729 var audioFiles = this.getAudioFilesUsedBySpriteId(spriteId);
730 var audioFilesLength = audioFiles.length;
731 for (var x = 0; x &lt; audioFilesLength; x++)
732 {
733 if (audioFiles[x].isPlaying()) { return true; }
734 }
735 return false;
736}
737
738
739/**
740 * Tells whether a given sprite (by its ID) is paused or not. Note that there could be more than one sound instance (with a {@CB_AudioFile} object) by each sprite with different status (paused, stopped, etc.) and this method will return true if any of them is paused.
741 * @function
742 * @param {string} spriteId - The identifier for the sprite.
743 * @returns {boolean} Returns whether a given sprite (by its ID) is paused or not.
744 */
745CB_AudioFileSprites.prototype.isPausedSprite = function(spriteId)
746{
747 var audioFiles = this.getAudioFilesUsedBySpriteId(spriteId);
748 var audioFilesLength = audioFiles.length;
749 for (var x = 0; x &lt; audioFilesLength; x++)
750 {
751 if (audioFiles[x].isPaused()) { return true; }
752 }
753 return false;
754}
755
756
757
758/**
759 * Tells whether a given sprite (by its ID) is stopped or not. Note that there could be more than one sound instance (with a {@CB_AudioFile} object) by each sprite with different status (paused, stopped, etc.) and this method will only return true if all of them are stopped.
760 * @function
761 * @param {string} spriteId - The identifier for the sprite.
762 * @param {boolean} [checkAudioFileObjects=false] - If set to true, it will check all the {@CB_AudioFile} objects associated to the sprite. Doing so, as internally all stopped {@CB_AudioFile} objects are disassociated from their sound instances, this method should return false normally (unless something went wrong).
763 * @returns {boolean} Returns whether a given sprite (by its ID) is stopped or not. As internally all stopped {@CB_AudioFile} objects are disassociated from their sound instances, this method should return false normally (unless something went wrong).
764 */
765CB_AudioFileSprites.prototype.isStoppedSprite = function(spriteId, checkAudioFileObjects)
766{
767 var audioFiles = this.getAudioFilesUsedBySpriteId(spriteId);
768 var audioFilesLength = audioFiles.length;
769 if (!checkAudioFileObjects)
770 {
771 return audioFilesLength === 0; //If no audio file is found, it should mean that the sound instances have been stopped.
772 }
773 else
774 {
775
776 for (var x = 0; x &lt; audioFilesLength; x++)
777 {
778 if (audioFiles[x].isStopped()) { return true; }
779 }
780 return false;
781 }
782}
783
784
785
786/**
787 * Plays a sprite by its ID. If the sprite is found, uses the {@link CB_AudioFileSprites#play} method internally and returns its returning value.
788 * @function
789 * @param {string} spriteId - The identifier for the sprite. Used as the "spriteId" parameter when calling the {@link CB_AudioFileSprites#play} method internally.
790 * @param {boolean} [loop={@link CB_AudioFile#loop}] - Used as the "loop" parameter when calling the {@link CB_AudioFileSprites#play} method internally.
791 * @param {number} [volume=CB_Configuration.CrossBase.CB_AudioFile_AudioFileCache_USE_SPEAKER_VOLUME_AS_DEFAULT ? CB_Speaker.getVolume() : CB_Configuration.CrossBase.CB_Speaker_DEFAULT_VOLUME] - Used as the "volume" parameter when calling the {@link CB_AudioFileSprites#play} method internally.
792 * @param {boolean} [allowedRecursiveDelay={@link CB_Configuration.CrossBase.CB_AudioFile_AudioFileCache_ALLOWED_RECURSIVE_DELAY_DEFAULT}] - Used as the "allowedRecursiveDelay" parameter when calling the {@link CB_AudioFileSprites#play} method internally.
793 * @param {boolean} [allowedRecursiveDelaySkipping=stopAt-startAt] - Used as the "allowedRecursiveDelaySkipping" parameter when calling the {@link CB_AudioFileSprites#play} method internally.
794 * @param {function} [onPlayStart] - Used as the "onPlayStart" parameter when calling the {@link CB_AudioFileSprites#play} method internally.
795 * @param {function} [onStop] - Used as the "onStop" parameter when calling the {@link CB_AudioFileSprites#play} method internally.
796 * @returns {integer|null} Returns null if the sprite was not found. Otherwise, returns the sound instance ID used if there was one free or null otherwise. To get a sound instance returned does not mean necessarily that the sound started playing so it is necessary to use a callback function as the "onPlayStart" parameter for checking this. The sound instance created (if any), will be cancelled automatically once the sound is stopped.
797 */
798CB_AudioFileSprites.prototype.playSprite = function(spriteId, loop, volume, allowedRecursiveDelay, allowedRecursiveDelaySkipping, onPlayStart, onStop)
799{
800 var sprite = this.getSprite(spriteId);
801 var soundInstance = this.play(sprite.startAt, sprite.stopAt, loop, volume, allowedRecursiveDelay, allowedRecursiveDelaySkipping, onPlayStart, onStop, spriteId);
802 return soundInstance;
803}
804
805
806/**
807 * Stops all the {@link CB_AudioFile} objects that belong to the sound instances (created by the {@link CB_AudioFileSprites#play} or the {@link CB_AudioFileSprites#playSprite} methods) which are playing used by a given sprite identifier. Uses the {@link CB_AudioFileSprites#stopAll} method internally and returns its returning value.
808 * @function
809 * @param {string} spriteId - The identifier for the sprite.
810 * @returns {integer} Returns the number of calls to the {@link CB_AudioFile#stop} method that were performed internally.
811 */
812CB_AudioFileSprites.prototype.stopSprite = function(spriteId)
813{
814 return this.stopAll(this.getAudioFilesUsedBySpriteId(spriteId));
815}
816
817
818/**
819 * Pauses all the {@link CB_AudioFile} objects that belong to the sound instances (created by the {@link CB_AudioFileSprites#play} or the {@link CB_AudioFileSprites#playSprite} methods) which are playing used by a given sprite identifier. Uses the {@link CB_AudioFileSprites#pauseAll} method internally and returns its returning value.
820 * @function
821 * @param {string} spriteId - The identifier for the sprite.
822 * @param {function} [onPause] - Function without parameters to be called when the audio is paused successfully, being "this" the {@link CB_AudioFile} object. Used internally as the "onPause" parameter to call the {@link CB_AudioFileSprites#pauseAll} method.
823 * @returns {integer} Returns the number of calls to the {@link CB_AudioFile#pause} method that were performed internally.
824 */
825CB_AudioFileSprites.prototype.pauseSprite = function(spriteId, onPause)
826{
827 return this.pauseAll(onPause, this.getAudioFilesUsedBySpriteId(spriteId));
828}
829
830
831/**
832 * Resumes all the {@link CB_AudioFile} objects that belong to the sound instances (created by the {@link CB_AudioFileSprites#play} or the {@link CB_AudioFileSprites#playSprite} methods) used by a given sprite identifier. Uses the {@link CB_AudioFileSprites#resumeAll} method internally and returns its returning value.
833 * @function
834 * @param {string} spriteId - Used as the "spriteId" parameter when calling the {@link CB_AudioFileSprites#resumeAll} method internally.
835 * @param {boolean} [loop={@link CB_AudioFile#loop}] - Used as the "loop" parameter when calling the {@link CB_AudioFileSprites#resumeAll} method internally.
836 * @param {boolean} [allowedRecursiveDelay={@link CB_Configuration.CrossBase.CB_AudioFile_AudioFileCache_ALLOWED_RECURSIVE_DELAY_DEFAULT}] - Used as the "allowedRecursiveDelay" parameter when calling the {@link CB_AudioFileSprites#resumeAll} method internally.
837 * @param {boolean} [allowedRecursiveDelaySkipping=stopAt-startAt] - Used as the "allowedRecursiveDelaySkipping" parameter when calling the {@link CB_AudioFileSprites#resumeAll} method internally.
838 * @param {function} [onPlayStart] - Used as the "onPlayStart" parameter when calling the {@link CB_AudioFileSprites#resumeAll} method internally.
839 * @param {function} [onStop] - Used as the "onStop" parameter when calling the {@link CB_AudioFileSprites#resumeAll} method internally.
840 * @returns {array} Returns null if the sprite identifier given could not be found. Otherwise, returns a numeric array containing all the return values of each internal call to the {@link CB_AudioFileCache#play} method (called through {@link CB_AudioFileSprites#resumeAll}).
841 */
842CB_AudioFileSprites.prototype.resumeSprite = function(spriteId, loop, allowedRecursiveDelay, allowedRecursiveDelaySkipping, onPlayStart, onStop)
843{
844 return this.resumeAll(loop, allowedRecursiveDelay, allowedRecursiveDelaySkipping, onPlayStart, onStop, this.getAudioFilesUsedBySpriteId(spriteId), spriteId);
845}
846
847
848/**
849 * Mutes all the {@link CB_AudioFile} objects that belong to the sound instances (created by the {@link CB_AudioFileSprites#play} or the {@link CB_AudioFileSprites#playSprite} methods) used by a given sprite identifier. Uses the {@link CB_AudioFileSprites#muteAll} method internally and returns its returning value.
850 * @function
851 * @param {string} spriteId - The identifier for the sprite.
852 * @param {function} [onMute] - Callback function which will be called for each audio file if it has been possible to mute it (or at least it was possible to try it), being "this" the {@link CB_AudioFile} object. Used internally as the "onMute" parameter to call the {@link CB_AudioFileSprites#muteAll} method.
853 * @returns {integer} Returns the number of calls to the {@link CB_AudioFile#mute} method that were performed internally.
854 */
855CB_AudioFileSprites.prototype.muteSprite = function(spriteId, onMute)
856{
857 return this.muteAll(onMute, this.getAudioFilesUsedBySpriteId(spriteId));
858}
859
860
861/**
862 * Unmutes all the {@link CB_AudioFile} objects that belong to the sound instances (created by the {@link CB_AudioFileSprites#play} or the {@link CB_AudioFileSprites#playSprite} methods) used by a given sprite identifier. Uses the {@link CB_AudioFileSprites#unmuteAll} method internally and returns its returning value.
863 * @function
864 * @param {string} spriteId - The identifier for the sprite.
865 * @param {function} [onUnmute] - Used internally as the "onUnmute" parameter to call the {@link CB_AudioFileSprites#unmuteAll} method.
866 * @returns {integer} Returns the number of calls to the {@link CB_AudioFile#unmute} method that were performed internally.
867 */
868CB_AudioFileSprites.prototype.unmuteSprite = function(spriteId, onUnmute)
869{
870 return this.unmuteAll(onUnmute, this.getAudioFilesUsedBySpriteId(spriteId));
871}
872
873
874/**
875 * Sets the same desired volume to all the {@link CB_AudioFile} objects that belong to the sound instances (created by the {@link CB_AudioFileSprites#play} or the {@link CB_AudioFileSprites#playSprite} methods) used by a given sprite identifier. Uses the {@link CB_AudioFileSprites#setVolumeAll} method internally and returns its returning value.
876 * @function
877 * @param {string} spriteId - The identifier for the sprite.
878 * @param {number} [volume={@link CB_Speaker.getVolume()} | {@link CB_Configuration.CrossBase.CB_Speaker_DEFAULT_VOLUME}] - Used as the "volume" parameter when calling the {@link CB_AudioFileSprites#setVolumeAll} method internally.
879 * @param {boolean} [forceSetVolumeProperty=false] - Used as the "forceSetVolumeProperty" parameter when calling the {@link CB_AudioFileSprites#setVolumeAll} method internally.
880 * @param {function} [onSetVolume] - Used as the "onSetVolume" parameter when calling the {@link CB_AudioFileSprites#setVolumeAll} method internally.
881 * @returns {integer} Returns the number of calls to the {@link CB_AudioFile#setVolume} method that were performed internally.
882 */
883CB_AudioFileSprites.prototype.setVolumeSprite = function(spriteId, volume, forceSetVolumeProperty, onSetVolume)
884{
885 return this.setVolumeAll(volume, forceSetVolumeProperty, onSetVolume, this.getAudioFilesUsedBySpriteId(spriteId));
886}
887
888
889/**
890 * Tries to change the desired audio API of the {@link CB_AudioFile} objects that belong to the sound instances (created by the {@link CB_AudioFileSprites#play} or the {@link CB_AudioFileSprites#playSprite} methods) used by a given sprite identifier. Uses the {@link CB_AudioFileSprites#setAudioAPIAll} method internally and returns its returning value.
891 * @function
892 * @param {string} spriteId - The identifier for the sprite.
893 * @param {array} preferredAPIs - Used as the "preferredAPIs" parameter when calling the {@link CB_AudioFileSprites#setAudioAPIAll} method internally.
894 * @param {CB_AudioFileCache.setAudioAPIAll_CALLBACK_OK} [callbackOk] - Used as the "callbackOk" parameter when calling the {@link CB_AudioFileSprites#setAudioAPIAll} method internally.
895 * @param {CB_AudioFileCache.setAudioAPIAll_CALLBACK_ERROR} [callbackError] - Used as the "callbackError" parameter when calling the {@link CB_AudioFileSprites#setAudioAPIAll} method internally.
896 * @param {boolean} [mandatory=false] - Used as the "mandatory" parameter when calling the {@link CB_AudioFileSprites#setAudioAPIAll} method internally.
897 * @param {string} [forceReload=false] - Used as the "forceReload" parameter when calling the {@link CB_AudioFileSprites#setAudioAPIAll} method internally.
898 * @returns {integer} Returns the number of calls to the {@link CB_AudioFile#setAudioAPI} method that were performed internally.
899 */
900CB_AudioFileSprites.prototype.setAudioAPISprite = function(spriteId, preferredAPIs, callbackOk, callbackError, mandatory, forceReload)
901{
902 return this.setAudioAPIAll(preferredAPIs, callbackOk, callbackError, mandatory, forceReload, this.getAudioFilesUsedBySpriteId(spriteId));
903}
904
905
906/**
907 * Creates the desired number of internal {@link CB_AudioFile} objects (inside the {@link CB_AudioFileCache#audioFiles} property). 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. Uses the {@link CB_AudioFileCache#createAudioFiles} method internally and returns its returning value.
908 * @function
909 * @param {integer} minimumAudioFiles - Used as the "minimumAudioFiles" parameter when calling the {@link CB_AudioFileCache#createAudioFiles} method internally.
910 * @returns {integer} Returns the number of {@link CB_AudioFile} objects which are intended to be created (they could fail).
911 */
912CB_AudioFileSprites.prototype.createAudioFiles = function(minimumAudioFiles)
913{
914 return this.audioFileCache.createAudioFiles(minimumAudioFiles);
915}
916
917
918/**
919 * Creates one internal {@link CB_AudioFile} object (inside the {@link CB_AudioFileCache#audioFiles} property). 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. Uses the {@link CB_AudioFileCache#createAudioFile} method internally and returns its returning value. Internal usage only recommended.
920 * @function
921 * @param {CB_AudioFileCache.URIS_OBJECT} [URIs={@link CB_AudioFileCache#URIs}] - Used as the "URIs" parameter when calling the {@link CB_AudioFileCache#createAudioFile} method internally.
922 * @param {array} [preferredAPIs={@link CB_AudioFileCache#preferredAPIs}] - Used as the "preferredAPIs" parameter when calling the {@link CB_AudioFileCache#createAudioFile} method internally.
923 * @param {array} [preferredFormats={@link CB_AudioFileCache#preferredFormats}] - Used as the "preferredFormats" parameter when calling the {@link CB_AudioFileCache#createAudioFile} method internally.
924 * @param {CB_AudioFile} [audioObject] - Used as the "audioObject" parameter when calling the {@link CB_AudioFileCache#createAudioFile} method internally.
925 * @param {function} [callbackOk] - Used as the "callbackOk" parameter when calling the {@link CB_AudioFileCache#createAudioFile} method internally.
926 * @param {function} [callbackError] - Used as the "callbackError" parameter when calling the {@link CB_AudioFileCache#createAudioFile} method internally.
927 * @param {boolean} [storeURIsList=false] - Used as the "storeURIsList" parameter when calling the {@link CB_AudioFileCache#createAudioFile} method internally.
928 * @param {boolean} [checkAutomatically=false] - Used as the "checkAutomatically" parameter when calling the {@link CB_AudioFileCache#createAudioFile} method internally.
929 * @returns {CB_AudioFile|null} If it fails, it returns null. Otherwise, returns the {@link CB_AudioFile} that has been created or reused.
930 */
931CB_AudioFileSprites.prototype.createAudioFile = function(URIs, preferredAPIs, preferredFormats, audioObject, callbackOk, callbackError, storeURIsList, checkAutomatically)
932{
933 return this.audioFileCache.createAudioFile(URIs, preferredAPIs, preferredFormats, audioObject, callbackOk, callbackError, storeURIsList, checkAutomatically);
934}
935
936
937/**
938 * Cleans the array of the {@link CB_AudioFile} objects (taking off the undefined or null ones) which is in the {@link CB_AudioFileCache#audioFiles} property, just keeping the valid ones and clearing (destroying and removing) the others. For performance purposes. Uses the {@link CB_AudioFileCache#clearAudioFiles} method internally and returns its returning value. Internal usage only recommended.
939 * @function
940 * @param {boolean} [avoidCallingCheckCacheLoaded=false] - Used as the "avoidCallingCheckCacheLoaded" parameter when calling the {@link CB_AudioFileCache#clearAudioFiles} method internally.
941 * @returns {array} Returns the value of the {@link CB_AudioFileCache#audioFiles} property.
942 */
943CB_AudioFileSprites.prototype.clearAudioFiles = function(avoidCallingCheckCacheLoaded)
944{
945 return this.audioFileCache.clearAudioFiles(avoidCallingCheckCacheLoaded);
946}
947
948
949/**
950 * If found, takes a given {@link CB_AudioFile} object off the {@link CB_AudioFileCache#audioFiles} property (and reloads it if we want to). NOTE: It does neither destroy nor remove the {@link CB_AudioFile} object so it can be used for other purposes (and if a {@link CB_AudioFile} object is given, it will be tried to be reused by the {@link CB_AudioFileCache#createAudioFile} method internally if it is called). Uses the {@link CB_AudioFileCache#removeAudioFile} method internally and returns its returning value. Internal usage only recommended.
951 * @function
952 * @param {CB_AudioFile|string} audioObjectOrId - Used as the "audioObjectOrId" parameter when calling the {@link CB_AudioFileCache#removeAudioFile} method internally.
953 * @param {boolean} [reload=false] - Used as the "reload" parameter when calling the {@link CB_AudioFileCache#removeAudioFile} method internally.
954 * @param {boolean} [checkManually=false] - Used as the "checkManually" parameter when calling the {@link CB_AudioFileCache#removeAudioFile} method internally.
955 * @returns {boolean|CB_AudioFile|null} Returns null if the given "audioObjectOrId" parameter is not a valid {@link CB_AudioFile} object or its {@link CB_AudioFile#id} property is not set or when the "audioObjectOrId" parameter is an empty string. Returns a {@link CB_AudioFile} object, the given one through the "audioObjectOrId" parameter of the first one removed (it should be the first and unique one removed as the ID must be unique), if the {@link CB_AudioFileCache#createAudioFile} method is called internally (it will reuse this {@link CB_AudioFile} object). Otherwise, returns true if all goes well.
956 */
957CB_AudioFileSprites.prototype.removeAudioFile = function(audioObjectOrId, reload, checkManually)
958{
959 return this.audioFileCache.removeAudioFile(audioObjectOrId, reload, checkManually);
960}
961
962
963/**
964 * Tries to purge the audio file cache until it reaches a desired number of {@link CB_AudioFile} objects internally (set in the {@link CB_AudioFileCache#audioFiles} property), by removing and destroying some of the current {@link CB_AudioFile} objects. For performance purposes. Uses the {@link CB_AudioFileCache#purge} method internally and returns its returning value.
965 * @function
966 * @param {integer} desiredNumber - Used as the "desiredNumber" parameter when calling the {@link CB_AudioFileCache#purge} method internally.
967 * @param {boolean} [setAsMinimumAudioFiles=false] - Used as the "setAsMinimumAudioFiles" parameter when calling the {@link CB_AudioFileCache#purge} method internally.
968 * @param {boolean} [includePlaying=false] - Used as the "includePlaying" parameter when calling the {@link CB_AudioFileCache#purge} method internally.
969 * @param {boolean} [stopSounds=false] - Used as the "stopSounds" parameter when calling the {@link CB_AudioFileCache#purge} method internally.
970 * @param {array} [statuses=Array({@link CB_AudioFile.LOADING}, {@link CB_AudioFile.UNCHECKED}, {@link CB_AudioFile.CHECKING}, {@link CB_AudioFile.LOADED})] - Used as the "statuses" parameter when calling the {@link CB_AudioFileCache#purge} method internally.
971 * @returns {integer} Returns the number of {@link CB_AudioFile} objects removed.
972 */
973CB_AudioFileSprites.prototype.purge = function(desiredNumber, setAsMinimumAudioFiles, includePlaying, stopSounds, statuses)
974{
975 return this.audioFileCache.purge(desiredNumber, setAsMinimumAudioFiles, includePlaying, stopSounds, statuses);
976}
977
978
979/**
980 * Returns a free {@link CB_AudioFile} object, if any (from the {@link CB_AudioFileCache#audioFilesFree} property). Note that this will call the internal {@link CB_AudioFileCache#_createNewAudioFilesIfNeeded} method that could end creating a new {@link CB_AudioFile} object if needed. Uses the {@link CB_AudioFileCache#getFreeAudioFile} method internally and returns its returning value.
981 * @function
982 * @param {boolean} [popIt=false] - Used as the "popIt" parameter when calling the {@link CB_AudioFileCache#getFreeAudioFile} method internally.
983 * @returns {CB_AudioFileCache.getFreeAudioFile_OBJECT} Returns a {@link CB_AudioFileCache.getFreeAudioFile_OBJECT} object.
984 */
985CB_AudioFileSprites.prototype.getFreeAudioFile = function(popIt)
986{
987 return this.audioFileCache.getFreeAudioFile(popIt);
988}
989
990
991/**
992 * Tells whether a desired {@link CB_AudioFile} object is free (it is in the {@link CB_AudioFileCache#audioFilesFree} property) or not, by its identifier. A free {@link CB_AudioFile} object is an object which is not being used and it is available to be used. Uses the {@link CB_AudioFileCache#isAudioFileFree} method internally and returns its returning value.
993 * @function
994 * @param {string} id - Used as the "id" parameter when calling the {@link CB_AudioFileCache#isAudioFileFree} method internally.
995 * @returns {boolean} Returns whether a desired {@link CB_AudioFile} object is free (it is in the {@link CB_AudioFileCache#audioFilesFree} property) or not, by its identifier. A free {@link CB_AudioFile} object is an object which is not being used and it is available to be used.
996 */
997CB_AudioFileSprites.prototype.isAudioFileFree = function(id)
998{
999 return this.audioFileCache.isAudioFileFree(id);
1000}
1001
1002
1003/**
1004 * Clears the sound instances (created by the {@link CB_AudioFileCache#play} method) which have been cancelled. Uses the {@link CB_AudioFileCache#clearSoundInstances} method internally and returns its returning value.
1005 * @function
1006 * @param {boolean} [clearWithObjectAssociated=false] - Used as the "clearWithObjectAssociated" parameter when calling the {@link CB_AudioFileCache#clearSoundInstances} method internally.
1007 * @returns {integer} Returns the number of cleared sound instances.
1008 */
1009CB_AudioFileSprites.prototype.clearSoundInstances = function(clearWithObjectAssociated)
1010{
1011 //Clears the sound instances in the cache object:
1012 var cleared = this.audioFileCache.clearSoundInstances(clearWithObjectAssociated);
1013
1014 var soundInstances;
1015 var soundInstancesLength;
1016 var spriteSoundInstances = {};
1017 var sprites = this.getSprites(true);
1018 var y = 0;
1019 for (var spriteId in sprites)
1020 {
1021 spriteSoundInstances[spriteId] = [];
1022 y = 0;
1023 soundInstances = this.getSoundInstancesIdBySpriteId(spriteId);
1024 soundInstancesLength = soundInstances.length;
1025 for (var x = 0; x &lt; soundInstancesLength; x++)
1026 {
1027 if (typeof(this.audioFileCache.soundInstancesQueued[soundInstances[x]]) !== "undefined")
1028 {
1029 spriteSoundInstances[spriteId][y++] = soundInstances[x];
1030 }
1031 }
1032 }
1033
1034 this.spriteSoundInstances = spriteSoundInstances;
1035
1036 return cleared;
1037}
1038
1039
1040/**
1041 * Cancels (to prevent they start playing) or enables all sound instances (created by the {@link CB_AudioFileCache#play} method). Uses the {@link CB_AudioFileCache#cancelSoundInstances} method internally and returns its returning value.
1042 * @function
1043 * @param {boolean} [cancel=false] - Used as the "cancel" parameter when calling the {@link CB_AudioFileCache#cancelSoundInstances} method internally.
1044 * @param {boolean} [affectWithObjectAssociated=false] - Used as the "affectWithObjectAssociated" parameter when calling the {@link CB_AudioFileCache#cancelSoundInstances} method internally.
1045 * @returns {integer} Returns the number of sound instances modified.
1046 */
1047CB_AudioFileSprites.prototype.cancelSoundInstances = function(cancel, affectWithObjectAssociated)
1048{
1049 return this.audioFileCache.cancelSoundInstances(cancel, affectWithObjectAssociated);
1050}
1051
1052
1053/**
1054 * Cancels (to prevent it starts playing) or enables a sound instance (created by the {@link CB_AudioFileCache#play} method), by its identifier. Uses the {@link CB_AudioFileCache#cancelSoundInstance} method internally and returns its returning value.
1055 * @function
1056 * @param {integer} soundInstanceId - Used as the "soundInstanceId" parameter when calling the {@link CB_AudioFileCache#cancelSoundInstance} method internally.
1057 * @param {boolean} [cancel=false] - Used as the "cancel" parameter when calling the {@link CB_AudioFileCache#cancelSoundInstance} method internally.
1058 * @param {boolean} [affectWithObjectAssociated=false] - Used as the "affectWithObjectAssociated" parameter when calling the {@link CB_AudioFileCache#cancelSoundInstance} method internally.
1059 * @returns {boolean} Returns true if the sound instance has been modified or false otherwise.
1060 */
1061CB_AudioFileSprites.prototype.cancelSoundInstance = function(soundInstanceId, cancel, affectWithObjectAssociated)
1062{
1063 return this.audioFileCache.cancelSoundInstance(soundInstanceId, cancel, affectWithObjectAssociated);
1064}
1065
1066
1067/**
1068 * Gets the {@link CB_AudioFile} object associated to a given sound instance ID (created by the {@link CB_AudioFileCache#play} method), if any, or null otherwise. Uses the {@link CB_AudioFileCache#getAudioFileBySoundInstanceId} method internally and returns its returning value.
1069 * @function
1070 * @param {integer} soundInstanceId - Used as the "soundInstanceId" parameter when calling the {@link CB_AudioFileCache#getAudioFileBySoundInstanceId} method internally.
1071 * @param {boolean} [avoidCancelled=false] - Used as the "avoidCancelled" parameter when calling the {@link CB_AudioFileCache#getAudioFileBySoundInstanceId} method internally.
1072 * @returns {CB_AudioFile|null} Returns the {@link CB_AudioFile} object associated to a given sound instance ID, if any, or null otherwise.
1073 */
1074CB_AudioFileSprites.prototype.getAudioFileBySoundInstanceId = function(soundInstanceId, avoidCancelled)
1075{
1076 return this.audioFileCache.getAudioFileBySoundInstanceId(soundInstanceId, avoidCancelled);
1077}
1078
1079
1080/**
1081 * Plays a sound of the cache (if there is any free), using a sprite if desired. If a sound cannot be played, this method can call itself internally again and again (with most of the given parameters being the same, depending on the circumstances) to try to play the sound until a desired time limit is reached. If a {@link CB_AudioFile} object cannot be played and it is determined necessary, it will try to reload it internally (by calling the {@link CB_AudioFileCache#removeAudioFile} method). Uses the {@link CB_AudioFileCache#play} method internally and returns its returning value. Internal usage only recommended. To play a sprite, better use the {@link CB_AudioFileSprites#playSprite} method instead.
1082 * @function
1083 * @param {number} [startAt=0 | {@link CB_AudioFile_API.WAAPI#lastStartAt} | {@link CB_AudioFile_API.SM2#lastStartAt} | {@link CB_AudioFile_API.ACMP#lastStartAt} | {@link CB_AudioFile_API.AAPI#lastStartAt} | stopAt] - Used as the "startAt" parameter when calling the {@link CB_AudioFileCache#play} method internally.
1084 * @param {number} [stopAt={@link CB_AudioFile_API.WAAPI#getDuration}() | {@link CB_AudioFile_API.SM2#getDuration}() | {@link CB_AudioFile_API.ACMP#getDuration}() | {@link CB_AudioFile_API.AAPI#getDuration}()] - Used as the "stopAt" parameter when calling the {@link CB_AudioFileCache#play} method internally.
1085 * @param {boolean} [loop={@link CB_AudioFile#loop}] - Used as the "loop" parameter when calling the {@link CB_AudioFileCache#play} method internally.
1086 * @param {number} [volume=CB_Configuration.CrossBase.CB_AudioFile_AudioFileCache_USE_SPEAKER_VOLUME_AS_DEFAULT ? CB_Speaker.getVolume() : CB_Configuration.CrossBase.CB_Speaker_DEFAULT_VOLUME] - Used as the "volume" parameter when calling the {@link CB_AudioFileCache#play} method internally.
1087 * @param {boolean} [allowedRecursiveDelay={@link CB_Configuration.CrossBase.CB_AudioFile_AudioFileCache_ALLOWED_RECURSIVE_DELAY_DEFAULT}] - Used as the "allowedRecursiveDelay" parameter when calling the {@link CB_AudioFileCache#play} method internally.
1088 * @param {boolean} [allowedRecursiveDelaySkipping=stopAt-startAt] - Used as the "allowedRecursiveDelaySkipping" parameter when calling the {@link CB_AudioFileCache#play} method internally.
1089 * @param {function} [onPlayStart] - Used as the "onPlayStart" parameter when calling the {@link CB_AudioFileCache#play} method internally.
1090 * @param {function} [onStop] - Used as the "onStop" parameter when calling the {@link CB_AudioFileCache#play} method internally.
1091 * @param {string} [spriteId='_WITHOUT_SPRITE_ASSOCIATED'] - The identifier for the sprite. Internal usage only recommended.
1092 * @returns {integer|null} Returns null if a sprite identifier was given but it could not be found. Otherwise, returns the sound instance ID used if there was one free or null otherwise. To get a sound instance returned does not mean necessarily that the sound started playing so it is necessary to use a callback function as the "onPlayStart" parameter for checking this. The sound instance created (if any), will be cancelled automatically once the sound is stopped.
1093 */
1094CB_AudioFileSprites.prototype.play = function(startAt, stopAt, loop, volume, allowedRecursiveDelay, allowedRecursiveDelaySkipping, onPlayStart, onStop, spriteId)
1095{
1096 if (typeof(spriteId) === "undefined" || spriteId === null) { spriteId = "_WITHOUT_SPRITE_ASSOCIATED"; }
1097 else if (typeof(this.sprites[spriteId]) === "undefined" || this.sprites[spriteId] === null) { return null; }
1098 //if (typeof(this.sprites[spriteId]) === "undefined" || this.sprites[spriteId] === null) { return null; }
1099
1100 var soundInstance = this.audioFileCache.play(startAt, stopAt, loop, volume, allowedRecursiveDelay, allowedRecursiveDelaySkipping, onPlayStart, onStop);
1101
1102 if (typeof(this.spriteSoundInstances[spriteId]) !== "undefined")
1103 {
1104 this.spriteSoundInstances[spriteId][this.spriteSoundInstances[spriteId].length] = soundInstance;
1105 }
1106
1107 return soundInstance;
1108}
1109
1110
1111/**
1112 * Alias for {@link CB_AudioFileSprites#executeFunctionAll}.
1113 * @function CB_AudioFileSprites#executeAll
1114 * @see {@link CB_AudioFileSprites#executeFunctionAll}
1115 */
1116 /**
1117 * Alias for {@link CB_AudioFileSprites#executeFunctionAll}.
1118 * @function CB_AudioFileSprites#forEach
1119 * @see {@link CB_AudioFileSprites#executeFunctionAll}
1120 */
1121/**
1122 * Performs a desired action, using the provided function, on all the existing {@link CB_AudioFile} objects or on the desired ones (if provided). Uses the {@link CB_AudioFileCache#executeFunctionAll} method internally and returns its returning value.
1123 * @function
1124 * @param {CB_Arrays.executeFunctionAll_ON_LOOP_CALLBACK} functionEach - Used as the "functionEach" parameter when calling the {@link CB_AudioFileSprites#executeFunctionAll} method internally.
1125 * @param {number|CB_Arrays.executeFunctionAll_ON_LOOP_CALLBACK} [delayBetweenEach=0] - Used as the "delayBetweenEach" parameter when calling the {@link CB_AudioFileCache#executeFunctionAll} method internally.
1126 * @param {array} [audioFiles={@link CB_AudioFileCache#audioFiles}] - Used as the "audioFiles" parameter when calling the {@link CB_AudioFileCache#executeFunctionAll} method internally.
1127 * @param {boolean} [returnSetTimeoutsArray=false] - Used as the "returnSetTimeoutsArray" parameter when calling the {@link CB_AudioFileCache#executeFunctionAll} method internally.
1128 * @param {boolean} [delayBetweenEachAffectsFirst=false] - Used as the "delayBetweenEachAffectsFirst" parameter when calling the {@link CB_AudioFileCache#executeFunctionAll} method internally.
1129 * @param {CB_Arrays.executeFunctionAll_ON_FINISH_CALLBACK} [functionFinish] - Function that will be called for when it has finished looping all the items. The first parameter will be the array which was looped, the second parameter will be the number of times that the "functionEach" callback was called (the most likely, matches the number of elements unless they are undefined or null), and the third parameter will be the maximum "delay" used, being "this" the array itself.
1130 * @returns {integer|array} If the "returnSetTimeoutsArray" parameter is set to false, it will return the number of calls to the "functionEach" function that were performed (which should be the same number as the {@link CB_AudioFile} objects given in the "audioFiles" parameter). Otherwise, if the "returnSetTimeoutsArray" is set to true, it will return a numeric array with a {@link CB_AudioFileCache.executeFunctionAll_OBJECT} object for each {@link CB_AudioFile} given. The length of this array will also be the number of calls to the "functionEach" function that were performed. Note that if a value greater than 0 (zero) for the "delayBetweenEach" parameter has been provided, perhaps not all calls of the "functionEach" function will have been performed yet when exiting this method because of the asynchronous nature of the [setTimeout]{@link https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/setTimeout} function.
1131 */
1132CB_AudioFileSprites.prototype.executeFunctionAll = CB_AudioFileSprites.prototype.executeAll = CB_AudioFileSprites.prototype.forEach = function(functionEach, delayBetweenEach, audioFiles, returnSetTimeoutsArray, delayBetweenEachAffectsFirst, finishFunction)
1133{
1134 return this.audioFileCache.executeFunctionAll(functionEach, delayBetweenEach, audioFiles, returnSetTimeoutsArray, delayBetweenEachAffectsFirst, finishFunction);
1135}
1136
1137
1138/**
1139 * Destroys all the {@link CB_AudioFile} objects and frees memory, by calling {@link CB_AudioFile#destructor}(stopSounds, false, true). Uses the {@link CB_AudioFileCache#destroyAll} method internally and returns its returning value.
1140 * @function
1141 * @param {boolean} [stopSounds=false] - Used as the "stopSounds" parameter when calling the {@link CB_AudioFileCache#destroyAll} method internally.
1142 * @returns {integer} Returns the number of {@link CB_AudioFile} objects whose {@link CB_AudioFile#destructor} has been called.
1143 */
1144CB_AudioFileSprites.prototype.destroyAll = function(stopSounds)
1145{
1146 return this.audioFileCache.destroyAll(stopSounds);
1147}
1148
1149
1150/**
1151 * Checks whether each {@link CB_AudioFile} object whose {@link CB_AudioFile#getStatus} method returns the "unchecked" value (which belongs to the value of the {@link CB_AudioFile#UNCHECKED} property) can be played or not. After checking, if the audio can be played, the status of the {@link CB_AudioFile} object will get the value of {@link CB_AudioFile.LOADED}. Otherwise, if it cannot be played, the status of the {@link CB_AudioFile} object will get the value of {@link CB_AudioFile.FAILED}. If a {@link CB_AudioFile} object cannot be played and it is determined necessary, it will try to reload it internally (by calling the {@link CB_AudioFileCache#removeAudioFile} method). It will call the {@link CB_AudioFileCache#clearAudioFiles} method internally after finishing. Uses the {@link CB_AudioFileCache#checkPlayingAll} method internally and returns its returning value. Recommended to be called through a user-driven event (as onClick, onTouch, etc.).
1152 * @function
1153 * @param {CB_AudioFileCache.checkPlayingAll_CALLBACK_OK} [callbackOk] - Used as the "callbackOk" parameter when calling the {@link CB_AudioFileCache#checkPlayingAll} method internally.
1154 * @param {CB_AudioFileCache.checkPlayingAll_CALLBACK_ERROR} [callbackError] - Used as the "callbackError" parameter when calling the {@link CB_AudioFileCache#checkPlayingAll} method internally.
1155 * @param {boolean} [ignoreQueue=false] - Used as the "ignoreQueue" parameter when calling the {@link CB_AudioFileCache#checkPlayingAll} method internally.
1156 * @returns {integer} Returns the number of {@link CB_AudioFile} objects whose status belonged to the "unchecked" value (the value of the {@link 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 the audio file cache is not loaded (the {@link CB_AudioFileCache#status} property does not belong to the value set in the {@link CB_AudioFileCache.LOADED} property).
1157 */
1158CB_AudioFileSprites.prototype.checkPlayingAll = function(callbackOk, callbackError, ignoreQueue)
1159{
1160 return this.audioFileCache.checkPlayingAll(callbackOk, callbackError, ignoreQueue);
1161}
1162
1163
1164/**
1165 * Tries to play all the {@link CB_AudioFile} objects by calling their {@link CB_AudioFile#play} method internally. If a {@link CB_AudioFile} object cannot be played and it is determined necessary, it will try to reload it internally (by calling the {@link CB_AudioFileCache#removeAudioFile} method). Uses the {@link CB_AudioFileCache#playAll} method internally and returns its returning value.
1166 * @function
1167 * @param {number} [startAt=0 | {@link CB_AudioFile_API.WAAPI#lastStartAt} | {@link CB_AudioFile_API.SM2#lastStartAt} | {@link CB_AudioFile_API.ACMP#lastStartAt} | {@link CB_AudioFile_API.AAPI#lastStartAt} | stopAt] - Used as the "startAt" parameter when calling the {@link CB_AudioFileCache#playAll} method internally.
1168 * @param {number} [stopAt={@link CB_AudioFile_API.WAAPI#getDuration}() | {@link CB_AudioFile_API.SM2#getDuration}() | {@link CB_AudioFile_API.ACMP#getDuration}() | {@link CB_AudioFile_API.AAPI#getDuration}()] - Used as the "stopAt" parameter when calling the {@link CB_AudioFileCache#playAll} method internally.
1169 * @param {boolean} [loop={@link CB_AudioFile#loop}] - Used as the "loop" parameter when calling the {@link CB_AudioFileCache#playAll} method internally.
1170 * @param {number} [volume=CB_Configuration.CrossBase.CB_AudioFile_AudioFileCache_USE_SPEAKER_VOLUME_AS_DEFAULT ? CB_Speaker.getVolume() : CB_Configuration.CrossBase.CB_Speaker_DEFAULT_VOLUME] - Used as the "volume" parameter when calling the {@link CB_AudioFileCache#playAll} method internally.
1171 * @param {boolean} [avoidDelayedPlay=false] - Used as the "avoidDelayedPlay" parameter when calling the {@link CB_AudioFileCache#playAll} method internally.
1172 * @param {boolean} [allowedRecursiveDelay={@link CB_Configuration.CrossBase.CB_AudioFile_AudioFileCache_ALLOWED_RECURSIVE_DELAY_DEFAULT}] - Used as the "allowedRecursiveDelay" parameter when calling the {@link CB_AudioFileCache#playAll} method internally.
1173 * @param {function} [onPlayStart] - Used as the "onPlayStart" parameter when calling the {@link CB_AudioFileCache#playAll} method internally.
1174 * @param {function} [onStop] - Used as the "onStop" parameter when calling the {@link CB_AudioFileCache#playAll} method internally.
1175 * @param {boolean} [includingPlaying=false] - Used as the "includingPlaying" parameter when calling the {@link CB_AudioFileCache#playAll} method internally.
1176 * @returns {integer} Returns the number of {@link CB_AudioFile} objects whose {@link CB_AudioFile#play} method did not return the value of "-1" (this does not mean necessarily that they could be played successfully).
1177 */
1178CB_AudioFileSprites.prototype.playAll = function(startAt, stopAt, loop, volume, avoidDelayedPlay, allowedRecursiveDelay, onPlayStart, onStop, includingPlaying)
1179{
1180 return this.audioFileCache.playAll(startAt, stopAt, loop, volume, avoidDelayedPlay, allowedRecursiveDelay, onPlayStart, onStop, includingPlaying);
1181}
1182
1183
1184/**
1185 * Tries to stops all the existing {@link CB_AudioFile} objects or the desired ones (if provided), which are being played, by calling their {@link CB_AudioFile#stop} method internally. Uses the {@link CB_AudioFileCache#stopAll} method internally and returns its returning value.
1186 * @function
1187 * @param {array} [audioFiles={@link CB_AudioFileCache#audioFiles}] - Used as the "audioFiles" parameter when calling the {@link CB_AudioFileCache#stopAll} method internally.
1188 * @returns {integer} Returns the number of calls to the {@link CB_AudioFile#stop} method that were performed (which should be the same number as the {@link CB_AudioFile} objects in the "audioFiles" parameter).
1189 */
1190CB_AudioFileSprites.prototype.stopAll = function(audioFiles)
1191{
1192 return this.audioFileCache.stopAll(audioFiles);
1193}
1194
1195
1196/**
1197 * Plays silently and stops all {@link CB_AudioFile} objects after a desired time. It can be useful for some clients which need the {@link CB_AudioFile#play} method to be called through a user-driven event (as onClick, onTouch, etc.). Internally, it calls {@link CB_AudioFileCache#playAll}(0, null, false, 0, true, null, null, null, includingPlaying) and, after a desired delay, calls the {@link CB_AudioFileCache#stopAll} method. Uses the {@link CB_AudioFileCache#playAndStopAll} method internally and returns its returning value.
1198 * @function
1199 * @param {boolean} [includingPlaying=false] - Used as the "includingPlaying" parameter when calling the {@link CB_AudioFileCache#playAndStopAll} method internally.
1200 * @param {number} [delayBeforeStop=100] - Used as the "delayBeforeStop" parameter when calling the {@link CB_AudioFileCache#playAndStopAll} method internally.
1201 * @returns {integer} Returns the number of {@link CB_AudioFile} objects whose {@link CB_AudioFile#play} method did not return the value of "-1" (this does not mean necessarily that they could be played successfully).
1202 */
1203CB_AudioFileSprites.prototype.playAndStopAll = function(includingPlaying, delayBeforeStop)
1204{
1205 return this.audioFileCache.playAndStopAll(includingPlaying, delayBeforeStop);
1206}
1207
1208
1209/**
1210 * Tries to pause all the existing {@link CB_AudioFile} objects or the desired ones (if provided), which are being played, by calling their {@link CB_AudioFile#pause} method internally. Uses the {@link CB_AudioFileCache#pauseAll} method internally and returns its returning value.
1211 * @function
1212 * @param {function} [onPause] - Used as the "onPause" parameter when calling the {@link CB_AudioFileCache#pauseAll} method internally.
1213 * @param {array} [audioFiles={@link CB_AudioFileCache#audioFiles}] - Used as the "audioFiles" parameter when calling the {@link CB_AudioFileCache#pauseAll} method internally.
1214 * @returns {integer} Returns the number of calls to the {@link CB_AudioFile#pause} method that were performed (which should be the same number as the {@link CB_AudioFile} objects in the "audioFiles" parameter).
1215 */
1216CB_AudioFileSprites.prototype.pauseAll = function(onPause, audioFiles)
1217{
1218 return this.audioFileCache.pauseAll(onPause, audioFiles);
1219}
1220
1221
1222/**
1223 * Resumes all the existing {@link CB_AudioFile} objects or the desired ones (if provided), which are paused (and not stopped). Can be focused on just one sprite identifier if desired. Uses the {@link CB_AudioFileCache#resumeAll} method internally and returns its returning value. Internal usage only recommended. To resume a sprite, better use the {@link CB_AudioFileSprites#resumeSprite} method instead.
1224 * @function
1225 * @param {boolean} [loop={@link CB_AudioFile#loop}] - Used as the "loop" parameter when calling the {@link CB_AudioFileCache#resumeAll} method internally.
1226 * @param {boolean} [allowedRecursiveDelay={@link CB_Configuration.CrossBase.CB_AudioFile_AudioFileCache_ALLOWED_RECURSIVE_DELAY_DEFAULT}] - Used as the "allowedRecursiveDelay" parameter when calling the {@link CB_AudioFileCache#resumeAll} method internally.
1227 * @param {boolean} [allowedRecursiveDelaySkipping=CB_AudioFile#lastStopAt-CB_AudioFile#lastStartAt] - Used as the "allowedRecursiveDelaySkipping" parameter when calling the {@link CB_AudioFileCache#resumeAll} method internally.
1228 * @param {function} [onPlayStart] - Used as the "onPlayStart" parameter when calling the {@link CB_AudioFileCache#resumeAll} method internally.
1229 * @param {function} [onStop] - Used as the "onStop" parameter when calling the {@link CB_AudioFileCache#resumeAll} method internally.
1230 * @param {array} [audioFiles={@link CB_AudioFileCache#audioFiles}] - Used as the "audioFiles" parameter when calling the {@link CB_AudioFileCache#resumeAll} method internally.
1231 * @param {string} [spriteId='_WITHOUT_SPRITE_ASSOCIATED'] - The identifier for the sprite. Internal usage only recommended.
1232 * @returns {array} Returns null if a sprite identifier was given but it could not be found. Otherwise, returns a numeric array containing all the return values of each internal call to the {@link CB_AudioFileCache#play} method.
1233 */
1234CB_AudioFileSprites.prototype.resumeAll = function(loop, allowedRecursiveDelay, allowedRecursiveDelaySkipping, onPlayStart, onStop, audioFiles, spriteId)
1235{
1236 if (typeof(spriteId) === "undefined" || spriteId === null) { spriteId = "_WITHOUT_SPRITE_ASSOCIATED"; }
1237 else if (typeof(this.sprites[spriteId]) === "undefined" || this.sprites[spriteId] === null) { return null; }
1238 //if (typeof(this.sprites[spriteId]) === "undefined" || this.sprites[spriteId] === null) { return null; }
1239
1240 var soundInstances = this.audioFileCache.resumeAll(loop, allowedRecursiveDelay, allowedRecursiveDelaySkipping, onPlayStart, onStop, audioFiles);
1241
1242 if (typeof(this.spriteSoundInstances[spriteId]) !== "undefined")
1243 {
1244 //Stores the sound instances used by the resume (if any):
1245 var soundInstancesLength = soundInstances.length;
1246 for (var x = 0; x &lt; soundInstancesLength; x++)
1247 {
1248 this.spriteSoundInstances[spriteId][this.spriteSoundInstances[spriteId].length] = soundInstances[x];
1249 }
1250 }
1251
1252 return soundInstances;
1253}
1254
1255
1256/**
1257 * Mutes all the existing {@link CB_AudioFile} objects or the desired ones (if provided). Uses the {@link CB_AudioFileCache#muteAll} method internally and returns its returning value.
1258 * @function
1259 * @param {function} [onMute] - Used as the "onMute" parameter when calling the {@link CB_AudioFileCache#muteAll} method internally.
1260 * @param {array} [audioFiles={@link CB_AudioFileCache#audioFiles}] - Used as the "audioFiles" parameter when calling the {@link CB_AudioFileCache#muteAll} method internally.
1261 * @returns {integer} Returns the number of calls to the {@link CB_AudioFile#mute} method that were performed (which should be the same number as the {@link CB_AudioFile} objects in the "audioFiles" parameter).
1262 */
1263CB_AudioFileSprites.prototype.muteAll = function(onMute, audioFiles)
1264{
1265 return this.audioFileCache.muteAll(onMute, audioFiles);
1266}
1267
1268
1269/**
1270 * Unmutes all the existing {@link CB_AudioFile} objects or the desired ones (if provided). Uses the {@link CB_AudioFileCache#unmuteAll} method internally and returns its returning value.
1271 * @function
1272 * @param {function} [onUnmute] - Used as the "onUnmute" parameter when calling the {@link CB_AudioFileCache#unmuteAll} method internally.
1273 * @param {array} [audioFiles={@link CB_AudioFileCache#audioFiles}] - Used as the "audioFiles" parameter when calling the {@link CB_AudioFileCache#unmuteAll} method internally.
1274 * @returns {integer} Returns the number of calls to the {@link CB_AudioFile#unmute} method that were performed (which should be the same number as the {@link CB_AudioFile} objects in the "audioFiles" parameter).
1275 */
1276CB_AudioFileSprites.prototype.unmuteAll = function(onUnmute, audioFiles)
1277{
1278 return this.audioFileCache.unmuteAll(onUnmute, audioFiles);
1279}
1280
1281
1282/**
1283 * Sets the same volume for all the existing {@link CB_AudioFile} objects or the desired ones (if provided). Uses the {@link CB_AudioFileCache#setVolumeAll} method internally and returns its returning value.
1284 * @function
1285 * @param {number} [volume={@link CB_Speaker.getVolume()} | {@link CB_Configuration.CrossBase.CB_Speaker_DEFAULT_VOLUME}] - Used as the "volume" parameter when calling the {@link CB_AudioFileCache#setVolumeAll} method internally.
1286 * @param {boolean} [forceSetVolumeProperty=false] - Used as the "forceSetVolumeProperty" parameter when calling the {@link CB_AudioFileCache#setVolumeAll} method internally.
1287 * @param {function} [onSetVolume] - Used as the "onSetVolume" parameter when calling the {@link CB_AudioFileCache#setVolumeAll} method internally.
1288 * @param {array} [audioFiles={@link CB_AudioFileCache#audioFiles}] - Used as the "audioFiles" parameter when calling the {@link CB_AudioFileCache#setVolumeAll} method internally.
1289 * @returns {integer} Returns the number of calls to the {@link CB_AudioFile#setVolume} method that were performed (which should be the same number as the {@link CB_AudioFile} objects in the "audioFiles" parameter).
1290 */
1291CB_AudioFileSprites.prototype.setVolumeAll = function(volume, forceSetVolumeProperty, onSetVolume, audioFiles)
1292{
1293 return this.audioFileCache.setVolumeAll(volume, forceSetVolumeProperty, onSetVolume, audioFiles);
1294}
1295
1296
1297/**
1298 * Tries to change the audio API for all the existing {@link 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 {@link CB_AudioFileCache#setAudioAPIAll} method internally and returns its returning value.
1299 * @function
1300 * @param {array|string} preferredAPIs - Used as the "preferredAPIs" parameter when calling the {@link CB_AudioFileCache#setAudioAPIAll} method internally.
1301 * @param {CB_AudioFileCache.setAudioAPIAll_CALLBACK_OK} [callbackOk] - Used as the "callbackOk" parameter when calling the {@link CB_AudioFileCache#setAudioAPIAll} method internally.
1302 * @param {CB_AudioFileCache.setAudioAPIAll_CALLBACK_ERROR} [callbackError] - Used as the "callbackError" parameter when calling the {@link CB_AudioFileCache#setAudioAPIAll} method internally.
1303 * @param {boolean} [mandatory=false] - Used as the "mandatory" parameter when calling the {@link CB_AudioFileCache#setAudioAPIAll} method internally.
1304 * @param {string} [forceReload=false] - Used as the "forceReload" parameter when calling the {@link CB_AudioFileCache#setAudioAPIAll} method internally.
1305 * @param {array} [audioFiles={@link CB_AudioFileCache#audioFiles}] - Used as the "audioFiles" parameter when calling the {@link CB_AudioFileCache#setAudioAPIAll} method internally.
1306 * @returns {integer} Returns the number of calls to the {@link CB_AudioFile#setAudioAPI} method that were performed (which should be the same number as the {@link CB_AudioFile} objects in the "audioFiles" parameter).
1307 */
1308CB_AudioFileSprites.prototype.setAudioAPIAll = function(preferredAPIs, callbackOk, callbackError, mandatory, forceReload, audioFiles)
1309{
1310 return this.audioFileCache.setAudioAPIAll(preferredAPIs, callbackOk, callbackError, mandatory, forceReload, audioFiles);
1311}
1312
1313
1314/**
1315 * Tells whether any of the {@link CB_AudioFile} objects is playing or not. Uses the {@link CB_AudioFileCache#isPlaying} method internally and returns its returning value.
1316 * @function
1317 * @returns {boolean} Returns whether any of the {@link CB_AudioFile} objects is playing or not.
1318 */
1319CB_AudioFileSprites.prototype.isPlaying = function()
1320{
1321 return this.audioFileCache.isPlaying();
1322}
1323
1324
1325/**
1326 * Tells the current number of free {@link CB_AudioFile} objects (the number of objects which are available and ready to use). Uses the {@link CB_AudioFileCache#getAudioFilesFreeNumber} method internally and returns its returning value.
1327 * @function
1328 * @returns {integer} Returns the current number of free {@link CB_AudioFile} objects (the number of objects which are available and ready to use).
1329 */
1330CB_AudioFileSprites.prototype.getAudioFilesFreeNumber = function()
1331{
1332 return this.audioFileCache.getAudioFilesFreeNumber();
1333}
1334
1335
1336/**
1337 * Gets an array with all the {@link CB_AudioFile} objects. Uses the {@link CB_AudioFileCache#getAudioFiles} method internally and returns its returning value.
1338 * @function
1339 * @param {boolean} [copy=false] - Used as the "copy" parameter when calling the {@link CB_AudioFileCache#getAudioFiles} method internally.
1340 * @returns {array} Returns an array with all the {@link CB_AudioFile} objects.
1341 */
1342CB_AudioFileSprites.prototype.getAudioFiles = function(copy)
1343{
1344 return this.audioFileCache.getAudioFiles(copy);
1345}
1346
1347
1348/**
1349 * Gets an array with the free {@link CB_AudioFile} objects (the objects which are available and ready to use). Uses the {@link CB_AudioFileCache#getAudioFilesFree} method internally and returns its returning value.
1350 * @function
1351 * @returns {array} Returns an array with the free {@link CB_AudioFile} objects (the objects which are available and ready to use).
1352 */
1353CB_AudioFileSprites.prototype.getAudioFilesFree = function()
1354{
1355 return this.audioFileCache.getAudioFilesFree();
1356}
1357
1358
1359/**
1360 * Gets an array with the busy {@link CB_AudioFile} objects (the objects which are not available and ready to use). Uses the {@link CB_AudioFileCache#getAudioFilesBusy} method internally and returns its returning value.
1361 * @function
1362 * @returns {array} Returns an array with the busy {@link CB_AudioFile} objects (the objects which are not available and ready to use).
1363 */
1364CB_AudioFileSprites.prototype.getAudioFilesBusy = function()
1365{
1366 return this.audioFileCache.getAudioFilesBusy();
1367}
1368
1369
1370/**
1371 * Tells the number of {@link CB_AudioFile} objects created. Uses the {@link CB_AudioFileCache#getAudioFilesNumber} method internally and returns its returning value.
1372 * @function
1373 * @param {boolean} [real=false] - Used as the "real" parameter when calling the {@link CB_AudioFileCache#getAudioFilesNumber} method internally.
1374 * @returns {integer} Returns the number of {@link CB_AudioFile} objects created.
1375 */
1376CB_AudioFileSprites.prototype.getAudioFilesNumber = function(real)
1377{
1378 return this.audioFileCache.getAudioFilesNumber(real);
1379}
1380
1381
1382/**
1383 * Tells the duration (minimum or maximum) of the sound stored (in milliseconds). Although the audio file cache should always be used to cache the same sound only, the duration might not always be the same due the usage of different formats, file paths, etc. So this method returns either the minimum or the maximum duration found among all the {@link CB_AudioFile} objects. Uses the {@link CB_AudioFileCache#getDuration} method internally and returns its returning value.
1384 * @function
1385 * @param {boolean} [maximum=false] - Used as the "maximum" parameter when calling the {@link CB_AudioFileCache#getDuration} method internally.
1386 * @returns {number} Returns the duration (minimum or maximum) of the sound stored (in milliseconds). Although the audio file cache should always be used to cache the same sound only, the duration might not always be the same due the usage of different formats, file paths, etc. So this method returns either the minimum or the maximum duration found among all the {@link CB_AudioFile} objects.
1387 */
1388CB_AudioFileSprites.prototype.getDuration = function(maximum)
1389{
1390 return this.audioFileCache.getDuration(maximum);
1391}
1392
1393
1394/**
1395 * Returns a number representing the percentage of the loading progress for the audio file sprites 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 {@link CB_AudioFileCache#getProgress} method internally and returns its returning value.
1396 * @function
1397 * @param {boolean} [countLoadedObjects=false] - Used as the "countLoadedObjects" parameter when calling the {@link CB_AudioFileCache#getProgress} method internally.
1398 * @param {boolean} [alsoUncheckedAndCheckingObjects=false] - Used as the "alsoUncheckedAndCheckingObjects" parameter when calling the {@link CB_AudioFileCache#getProgress} method internally.
1399 * @returns {number} Returns a number representing the percentage of the loading progress for the audio file sprites 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.
1400 */
1401CB_AudioFileSprites.prototype.getProgress = function(countLoadedObjects, alsoUncheckedAndCheckingObjects)
1402{
1403 return this.audioFileCache.getProgress(countLoadedObjects, alsoUncheckedAndCheckingObjects);
1404}
1405
1406
1407/**
1408 * Gets the current status of the audio file sprites object. Uses the {@link CB_AudioFileCache#getStatus} method internally and returns its returning value.
1409 * @function
1410 * @returns {number} Returns the current status of the audio file sprites object. It is a number, which should match the value of the {@link CB_AudioFileCache.UNLOADED} (still unloaded), {@link CB_AudioFileCache.LOADING} (loading), {@link CB_AudioFileCache.UNCHECKED} (not checked by calling the {@link CB_AudioFileCache#checkPlayingAll} method yet), {@link CB_AudioFileCache.CHECKING} (being checked by the {@link CB_AudioFileCache#checkPlayingAll} method), {@link CB_AudioFileCache.LOADED} (loaded), {@link CB_AudioFileCache.FAILED} (failed loading or failed to play or by any other reason) or {@link CB_AudioFileCache.ABORTED} (aborted because it was destroyed with the "destructor" method) property.
1411 */
1412CB_AudioFileSprites.prototype.getStatus = function()
1413{
1414 return this.audioFileCache.getStatus();
1415}
1416
1417
1418/**
1419 * Gets the current status of the audio file sprites, as a string. Uses the {@link CB_AudioFileCache#getStatusString} method internally and returns its returning value.
1420 * @function
1421 * @returns {string} Returns the current status of the audio file sprites, as a string. Possible return values are "UNLOADED", "LOADING", "UNCHECKED", "CHECKING", "LOADED", "FAILED", "ABORTED" or "UNKNOWN (UNKNOWN_STATUS)" (where "UNKNOWN_STATUS" will be a value from the {@link CB_AudioFileCache#status} property not recognized as any possible status).
1422 */
1423CB_AudioFileSprites.prototype.getStatusString = function()
1424{
1425 return this.audioFileCache.getStatusString();
1426}</pre>
1427 </article>
1428</section>
1429
1430
1431
1432
1433
1434 </div>
1435 </div>
1436
1437 <div class="clearfix"></div>
1438
1439
1440
1441</div>
1442</div>
1443
1444
1445 <div class="modal fade" id="searchResults">
1446 <div class="modal-dialog">
1447 <div class="modal-content">
1448 <div class="modal-header">
1449 <button type="button" class="close" data-dismiss="modal" aria-label="Close"><span aria-hidden="true">&times;</span></button>
1450 <h4 class="modal-title">Search results</h4>
1451 </div>
1452 <div class="modal-body"></div>
1453 <div class="modal-footer">
1454 <button type="button" class="btn btn-default" data-dismiss="modal">Close</button>
1455 </div>
1456 </div><!-- /.modal-content -->
1457 </div><!-- /.modal-dialog -->
1458 </div>
1459
1460
1461<footer>
1462
1463
1464 <span class="copyright">
1465 <a href="printable/" target="_blank">See a more printer-friendly version</a><hr /><span style="color:#000000">© <address style="display:inline; font-style:normal;"><a href="https://crossbrowdy.com/" target="_blank">CrossBrowdy</a> API documentation</address> by <a href="https://joanalbamaldonado.com/" target="_blank">Joan Alba Maldonado</a> - <a href="https://creativecommons.org/licenses/by/4.0/" target="_blank">Creative Commons Attribution 4.0 International</a><br />DocStrap Copyright © 2012-2015 The contributors to the JSDoc3 and DocStrap projects.</span>
1466 </span>
1467
1468<span class="jsdoc-message">
1469 Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.2</a>
1470
1471 on Wed Mar 22nd 2023
1472
1473 using the <a href="https://github.com/docstrap/docstrap">DocStrap template</a>.
1474</span>
1475</footer>
1476
1477<script src="scripts/docstrap.lib.js"></script>
1478<script src="scripts/toc.js"></script>
1479
1480 <script type="text/javascript" src="scripts/fulltext-search-ui.js"></script>
1481
1482
1483<script>
1484$( function () {
1485 $( "[id*='$']" ).each( function () {
1486 var $this = $( this );
1487
1488 $this.attr( "id", $this.attr( "id" ).replace( "$", "__" ) );
1489 } );
1490
1491 $( ".tutorial-section pre, .readme-section pre, pre.prettyprint.source" ).each( function () {
1492 var $this = $( this );
1493
1494 var example = $this.find( "code" );
1495 exampleText = example.html();
1496 var lang = /{@lang (.*?)}/.exec( exampleText );
1497 if ( lang && lang[1] ) {
1498 exampleText = exampleText.replace( lang[0], "" );
1499 example.html( exampleText );
1500 lang = lang[1];
1501 } else {
1502 var langClassMatch = example.parent()[0].className.match(/lang\-(\S+)/);
1503 lang = langClassMatch ? langClassMatch[1] : "javascript";
1504 }
1505
1506 if ( lang ) {
1507
1508 $this
1509 .addClass( "sunlight-highlight-" + lang )
1510 .addClass( "linenums" )
1511 .html( example.html() );
1512
1513 }
1514 } );
1515
1516 Sunlight.highlightAll( {
1517 lineNumbers : true,
1518 showMenu : true,
1519 enableDoclinks : true
1520 } );
1521
1522 $.catchAnchorLinks( {
1523 navbarOffset: 10
1524 } );
1525 $( "#toc" ).toc( {
1526 anchorName : function ( i, heading, prefix ) {
1527 return $( heading ).attr( "id" ) || ( prefix + i );
1528 },
1529 selectors : "#toc-content h1,#toc-content h2,#toc-content h3,#toc-content h4",
1530 showAndHide : false,
1531 smoothScrolling: true
1532 } );
1533
1534 $( "#main span[id^='toc']" ).addClass( "toc-shim" );
1535 $( '.dropdown-toggle' ).dropdown();
1536
1537 $( "table" ).each( function () {
1538 var $this = $( this );
1539 $this.addClass('table');
1540 } );
1541
1542} );
1543</script>
1544
1545
1546
1547<!--Navigation and Symbol Display-->
1548
1549<script>
1550 $( function () {
1551 $( '#main' ).localScroll( {
1552 offset : { top : 60 } //offset by the height of your header (give or take a few px, see what works for you)
1553 } );
1554 $( "dt.name" ).each( function () {
1555 var $this = $( this ).find("h4");
1556 var icon = $( "<i/>" ).addClass( "icon-plus-sign" ).addClass( "pull-right" ).addClass( "icon-white" );
1557 var dt = $(this);
1558 var children = dt.next( "dd" );
1559
1560 dt.prepend( icon ).css( {cursor : "pointer"} );
1561 dt.addClass( "member-collapsed" ).addClass( "member" );
1562
1563
1564 children.hide();
1565
1566 dt.children().on( "click", function () {
1567 children = dt.next( "dd" );
1568 children.slideToggle( "fast", function () {
1569
1570 if ( children.is( ":visible" ) ) {
1571 icon.addClass( "icon-minus-sign" ).removeClass( "icon-plus-sign" ).removeClass( "icon-white" );
1572 dt.addClass( "member-open" ).animate( "member-collapsed" );
1573 } else {
1574 icon.addClass( "icon-plus-sign" ).removeClass( "icon-minus-sign" ).addClass( "icon-white" );
1575 dt.addClass( "member-collapsed" ).removeClass( "member-open" );
1576 }
1577 } );
1578 } );
1579
1580 } );
1581 } );
1582</script>
1583
1584
1585<!--Google Analytics-->
1586
1587
1588
1589 <script type="text/javascript">
1590 $(document).ready(function() {
1591 SearcherDisplay.init();
1592 });
1593 </script>
1594
1595
1596</body>
1597</html>