|
|
HowToUseEvents
Understanding events
BulkLoader events are divided into two categories:
- Events for all assets as a group.
- Events for individual items.
Events for all assets as a group
These events listeners are always added to the BulkLoader instance and relate to items added as a group.
Complete
An event of name "complete" (BulkLoader.COMPLETE or Event.COMPLETE) is fired when all items have finished loading. The event type is a BulkProgressEvent (which subclasses ProgressEvent), so your event handler can receive a Event, ProgressEvent or a BulkProgressEvent object. Example:
var bulkInstance = new BulkLoader("main");
bulkInstance.add("main.swf");
bulkInstance.add("config.xml");
bulkInstance.add("background.jpg");
bulkInstance.addEventListener(BulkLoader.COMPLETE, onAllLoaded);
function onAllLoaded(evt : BulkProgressEvent):void{
// all items have been loaded!
trace(evt.
trace(evt.loadedPercent) ; // percentage will be 1)
var bg : Bitmap = bulkInstance.getBitmap("background.jpg");
addChild(bg);
}A few observations about the complete event:
- If any item fails to load this event will never fire.
- If you add an item to the same BulkLoader instance after the complete event has fired, bulk loader will load the new item and when it's loaded will fire the complete event again.
- Before fireing the complete event, BulkLoader will always fire a progress event where all items are loaded.
Progress
When any asset fires a progress event, BulkLoader will fire the progress (BulkLoader.PROGRESS, ProgressEvent.PROGRESS) event. The event name is : "progress" (BulkLoader.PROGRESS, BulkLoader.PROGRESS). The event type is a BulkProgressEvent). See the ReportingLoadingStatus page for more information.
Error
If any of the assets fail to load, BulkLoader will fire an "error" event.
The event name is "error" (BulkErrorEvent.ERROR). The event type is BulkErrorEvent. This event has an "error" property that is an array with all the LoadingItem instances that have failed to load on this bulk loader instance.
Simple example:
bulkInstance.addEventListener(BulkLoader.ERROR,onError);
function onError(evt : BulkErrorEvent ) : void{
trace("an error ocurred when loading");
for each (var loadingItem in evt.errors){
trace(loadingItem, "has failed to load");
}
}The error event is only fired after the item has the number of retries especified on the maxRetries option (AvailableOptions#maxTries)
Events for individual items
Besides listening for events on all items as a whole, you can listen to event for each item.
To add an event for an item, first grab a reference to that item:
var bulkInstance = new BulkLoader("main");
bulkInstance.add("main.swf");
bulkInstance.add("background.jpg", {id:"bg"});
// add an event for the background item by the id:
bulkInstance.get("bg").addEventListener(...);
// or by the url:
bulkInstance.get("background.jpg").addEventListener(...);The folowing events are available:
Complete
An event of name "complete" (BulkLoader.COMPLETE or Event.COMPLETE) is fired when an item has finished loading (and succeeded). The event type is Event.
This code will attach a "background" jpeg as soon as that jpeg is loaded but before all items have been loaded:
var bulkInstance = new BulkLoader("main");
bulkInstance.add("main.swf");
bulkInstance.add("background.jpg", {id:"bg"});
// add an event for the background item by the id:
bulkInstance.get("bg").addEventListener(...);
// or by the url:
bulkInstance.get("background.jpg").addEventListener(Event.COMPLETE, onBackgroundLoaded);
function onBackgroundLoaded(evt : Event) : void{
// the background is loaded, you can get now attach it:
var bgBitmap : Bitmap = bulkInstance.getBitmap("background.jpg");
addChild(bgBitmap);
}Error
An event of name "error" (BulkLoader.ERROR ) is fired when an item has failed to load. The event type is BulkErrorEvent.
Progress
An event of name "progress" (ProgressEvent.PROGRESS ) is fired when the player has received more content for that item. The event type is ProgressEvent.
HttpStatus
You can also listen for HTTPStatusEvent for each item. Although the player is not very reliable on informing this, it can be useful.
An event of name "httpStatus" (BulkLoader.HTTP_STATUS ) is fired when an item has failed to load. The event type is HTTPStatusEvent.
Open
An event of name "open"(BulkLoader.OPEN) is fired when a connection has been opened. In streaming items (sound and video) the content can be used right away.
CAN_BEGIN_PLAYING
An event of name "canBeginPlaying" (BulkLoader.CAN_BEGIN_PLAYING) is fired for video objects when the download speed is enough that it should be possible for video playback to begin without any interruptions. This event will only fire once.
Hi. Thanks for the great library. Just a note: the trace statement in the first example should read
not
Is that right?
- Daniel M
Hi Daniel.
Nice catch! Just fixed it, thanks for the heads up.
Arthur
Hey Arthur, I think there's still a typo on the first example. Take a look. Outstanding library!
@Gabriel: thanks mate, hope la is treating you good. ;-)
Hej Arthur,
amazing package.
One Questions: Why do I get the "BulkLoader?.COMPLETE"-Event before I get the single Complete-Event for the latest item?
Thanks Jens
@Jens: Bug fixed on revision 85.
Why use get() method for retrieving a the "loader"? Personally I would call the method getLoader() But I see u already use this for retrieving a kind of bulkloader instance. Why did you make that system? You can always make more instances of the BulkLoader?? right? Otherwise it should be singleton.
@flashWiz:
Yes, you can make as many references as you'd like, this (BulkLoader?.getLoader("loaderName") is just a shortcut, so you don't have to keep passing references around.
Note that the "get()" method, doens't return a loader at all, it returns the loading item for some key.
As a side note, we've created a discussion list:
http://groups.google.com/group/bulkloader-users
It's probably easier to keep tabs of general discussions over there.
Cheers Arthur
Whilst there is a way to write a workaround for this it would still be nice to have the possibility to add an ERROR event listener to individual LoadingItems?.
I also think that there is a typo in the Event tag inside LoadingItem?.as which currently says:
[Event(name="complete", type="flash.events.ProgressEvent?.COMPLETE")]
Thanks for this great class BTW!
AFAIK there is no ProgressEvent?.COMPLETE - I think it should say br.com.stimuli.loading.BulkLoader?.COMPLETE instead.
@quasimondo:
Thanks for the heads up on the typo.
Regarding individual errors for each item, the standard procedure would be to add an error handler to the bulk loader instance. From that handler, you can access the items that have thrown an error with the "errors" array of the BulkLoaderErrorEvent?, which has an array of items that failed to load.
Cheers Arthur
Somehow I had overlooked that it is actually possible to add a listener to the error event also to individual LoadingItems? - I'm a happy camper now!