|
HowToUseEvents
Understanding events
BulkLoader events are divided into two categories:
Events for all assets as a groupThese events listeners are always added to the BulkLoader instance and relate to items added as a group. CompleteAn 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:
ProgressWhen 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. ErrorIf any of the assets fail to load, BulkLoader will fire an "error" event. The event name is "error" (BulkErrorEvent.ERROR). The event type is ErrorEvent for both SecurityError and IOError instances. Error events can be listened to for each item in separate, or full the entire BulkLoader instance. From whithin your error handling method you can obtain more information about the event. Simple example: bulkInstance.addEventListener(BulkLoader.ERROR,onError);
function onError(evt :ErrorEvent ) : void{
var item : LoadingItem = evt.target;
trace (item.errorEvent is SecurityErrorEvent);
trace (item.errorEvent is IOError);
trace (evt); // outputs more information
}The error event is only fired after the item has the number of retries especified on the maxRetries option (AvailableOptions#maxTries) Error events will fire as soon as they happen. Events for individual itemsBesides 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: CompleteAn 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);
}ErrorAn event of name "error" (BulkLoader.ERROR ) is fired when an item has failed to load. The event type is BulkErrorEvent. ProgressAn event of name "progress" (ProgressEvent.PROGRESS ) is fired when the player has received more content for that item. The event type is ProgressEvent. HttpStatusYou 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. OpenAn 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_PLAYINGAn 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. SecurityErrorBulkLoader can handle SecurityErrorEvents. By listening to BulkLoader.SECURITY_ERROR("securityError"), client code can gracefully handle security error events. Listeners can be added to each LoadingItem subtype or to the entire BulkLoader object. Please note that if you add an event listener for a LoadingItem but not for BulkLoader, in case the event fires, it will bubble up and result in a unhandled security error. In order to make sure the error never goes unhandled, add a securityError handler to the BulkLoader instance. This mechanism will catch events thrown on <someloader>.load operations. Event thrown when trying to access content (such as getBitmapData) is still left to client code to handle. When using type=image or type=movieclip (which are loaded using a Loader instance), if, when the asset is loaded, accessing it's loader.content throws an error, then BulkLoader will gracefully recover and use a simple Loader instance. This way, you can still add a Loader object to the stage, but won't be able to run code inside of it (for MovieClip instances) or load it as data (transforming to BitmapData instances). In this case, you can get the Loader instance either using getContent or getDisplayObjecLoader . |
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!