MassLoad
MassLoad is a library that enables you to manage the loading of extern files in Flash (currently, only flash 9 is supported). MassLoad is usefull in big websites that need to often load files when navigate on them. The library supports text files, images and SWF files, sound files and can group them to load them simultaneously.
Install
In order to install MassLoad, you need to run the following command :
haxelib install massload
Then you can use the library by adding -lib massload
to haxe commandline parameters.
Tutorial
How to get the massloader instance
The massloader is developped following the singleton pattern. So to get its instance you must do :
var loader = fas.massload.MassLoader.getInstance();
How to defined a file to download
File downloads are divised into 4 means of downloading called LoadFiles:
- Loader (for images, SWFs,...) : LLoadFile,
- UrlLoader (for text and XML files) : ULoadFile,
- SoundLoader (for sound files...) : SLoadFile,
- GroupLoader (for group of whatever kinds of file) : GLoadFile.
In fact the massloader manages a list of these LoadFiles, so you need to create an instance of a LoadFile before add it in the massloader.
To do that you can instanciate them manually but it's easier to use the LoadFileCreator
tool. This tool is in the fas.massload.file
package.
// You can let the massloader find the better way to download the specified file var myFile = fas.massload.file.LoadFileCreator.create({file: "my_file.swf", name: "my flash file"}); // The massloader gets the way to download the file by checking the file extension // So if the file extension isn't known you can register it like this : fas.massload.file.LoadFileCreator.addExtension(UrlLoader, "ini"); // Now the extension is directly detected var myIniFile = fas.massload.file.LoadFileCreator.create("my_file.ini", "my ini file"); // You can manually indicate the type of download you want the loader uses. var mySoundFile = new fas.massload.file.SLoadFile(new flash.net.URLRequest("my_file.mp3"), "my sound file");
How to create a group of download
Group creation is a little different.
// To create a group you can do like this : var myGroupFile = new fas.massload.file.GLoadFile([ new fas.massload.file.ULoadFile(flash.net.URLRequest("my_file.php"),"my php file"), fas.massload.file.LoadFileCreator.create("sound.wav","my wav file"), //... ], "my group file"); // But it's easier to do like this var myGroupFile = fas.massload.file.LoadFileCreator.create({files: [ {file: "my_file.php", name: "my php file"}, {file: "sound.wav", name: "my wav file"}, //... ], name: "my group file"});
How to listen events
It's good to download but we need to know when is downloaded... So the massloader and each LoadFile dispatch some events.
There is error events (fas.massload.events.MassLoaderErrorEvent
):
- IO_ERROR
- SECURITY_ERROR
- ERROR
(this error is dispatched for each kind of error)
And information events (fas.massload.events.MassLoaderEvent
):
- INIT
, COMPLETE
, PROGRESS
, OPEN
events are the flash events redispatched,
- COMPLETE_ALL
is dispatched by the massloader when it just finishes to download all the file list,
- COMPLETE_ELEM
is dispatched by groups of files when an element is finished (when all are finished it dispatches the COMPLETE
event)
- CLOSE
is dispatched when a LoadFile is closed.
How to 'really' download
OK, we have instantied some LoadFiles. Now we must add them to the massloader and start it.
The method to use is addFile
. This method takes a mandatory argument and 2 optionals.
The first is only the file to add...
The second is a priority. There is 3 kinds of priority:
- High: if the massloader is started, the currently downloading file is stopped and the added one is started. If it's not started the file is only placed at the head of the list,
- Medium: in this case
the added file is placed in second position,
- Low: in this case the file is added at the end of the list.
And the last one is a boolean indicate if you want to remove all the homonyms of the file to avoid useless multiple downloads.
// To add a file to the load list we just have to do this for each file to download loader.addFile(myFile); loader.addFile(myIniFile, Medium); loader.addFile(mySoundFile, High, true); //... // Now we can launch the massloader loader.start(); // To stop it, it'is : loader.stop(); (Incredible isn't it? ^^)
You must notice that you can start the massloader before adding LoadFiles. If the massloader is started before you add a LoadFile and the file list is empty, the file will automaticaly start.
How to use events
Error events have the following fields:
- file
: which contains a reference to the ILoadFile which gets the error,
- text
: the error message
- id
: ...hem...not used.
Information events have the followinf fields:
- the same file
field than error events,
- in the case of a ProgressEvent the fields bytesLoaded
and bytesTotal
contains informations about the progression, otherwise they are set at zero.
- in the case of an information event dispatch by an element of a GroupFile, the element is referenced into the element
field.
To access to the content of a loaded file you must use its content
field. In fact the content
field contains the instance of the flash loader used. For instance in ULoadFile, the content
field contains an instance of an UrlLoader...
This is an example to show how to get the content of a loaded file
//... function onMyFileComplete(ev:fas.massload.events.MassLoaderEvent) : Void { // We have load a swf file so we can do some actions like flash.Lib.current.addChild(ev.file.content); } function onMyGroupFileComplete(ev:fas.massload.events.MassLoaderEvent) : Void { // In a group of files the 'content' field is different. It contains a Hash of LoadFiles // So with our example we can access to content like this: trace(ev.file.content.get("my php file").content.data); // or this ev.file.content.get("my wav file").content.play(); } //...
Example
The code below is an example of a little website.
Main.hx
import fas.massload.MassLoader; import fas.massload.file.LoadFileCreator; import fas.massload.events.MassLoaderEvent; import fas.massload.events.MassLoaderErrorEvent; class Main { static function main() { new Main(); } function new() { var loader = MassLoader.getInstance(); // Before showing the page we need to get the text content // and the website logo... var page = LoadFileCreator.create({name: "page", files: [ {file: "news.php", name: "news"}, {file: "img/logo.png", name: "logo"} ]}); page.addEventListener(MassLoaderEvent.PROGRESS, onPageProgress); page.addEventListener(MassLoaderEvent.COMPLETE, onPageComplete); page.addEventListener(MassLoaderErrorEvent.ERROR, onError); loader.addFile(page, High); // The ambiance sound isn't the most important thing so // we set it in low priority var sound = LoadFileCreator.create({file: "music.mp3", name: "ambiance"}); sound.addEventListener(MassLoaderEvent.COMPLETE, onSoundComplete); sound.addEventListener(MassLoaderErrorEvent.ERROR, onError); loader.addFile(sound, Low); loader.addEventListener(MassLoaderEvent.COMPLETE_ALL,onCompleteAll); loader.start(); } function onCompleteAll(ev:MassLoaderEvent) : Void { trace("The download list is empty!"); } function onError(ev:MassLoaderErrorEvent) : Void { trace("Error #" + ev.text); } function onPageProgress(ev:MassLoaderEvent) : Void { trace("Page progression: " + Math.round( ev.bytesLoaded / ev.bytesTotal * 100 )); } function onPageComplete(ev:MassLoaderEvent) : Void { trace("Page complete"); // Show the logo flash.Lib.current.addChild(ev.file.content.get("logo").content); // Trace the text trace(ev.file.content.get("news").content.data); } function onSoundComplete(ev:MassLoaderEvent) : Void { trace("Sound complete"); // Start the music ev.file.content.play(); } }
Additional features
The massloader contains other features to help you to manage your files list.
Methods
Remove the LoadFile called sName
from the list.
function removeFile( sName:String ):Void
If bAll
is false: Replace the first LoadFile called sName
from the list by the specified file
.
If bAll
is true: Replace all LoadFile called sName
from the list by the specified file
.
function replaceFile( file:ILoadFile, sName:String, bAll:Bool )
Return true if a LoadFile called sName
is in the list.
function exists( sName:String ):Bool
Return the index of the first LoadFile called sName
in the list and -1 if it's not present.
function indexOf( sName:String ):Int
Return the index of the last LoadFile called sName
in the list and -1 if it's not present.
function lastIndexOf( sName:String ):Int
Properties
Indicate if the massloader is started.
var loading( default, null ):Bool;
Contains the list of non loaded files.
var files( default, null ):Array<ILoadFile>;
Contains the number of elements in the files list.
var filesCount( default, null ):Int;
Indicate the number of simultaneaous download available.
var parallelFiles( default, setParallelFiles ):Int;
Number of files downloading currently simulatenously.
var loadingFiles( default, null ):Int;