AS3: SequentialLoader

Posted on
1/28/2008 in AS3 • My Classes

View Example 1
View Example 2
View Documentation
Download Class & Example Files

UPDATE 10/14/08: Added a new parameter that checks policy files for downloading assets from a different server.

The SequentialLoader loads a series of SWFs and/or images in an ordered sequence. This is a conversion of the AS2 SequentialLoader class originally written by Tom Stanley with some additional methods added for more control.

The first example shows the simplest usage of SequentialLoader. The second example shows how to use SequentialLoader with the optional pauseAfterEachLoad property which allows you to run a set of actions after each item has loaded before you resume loading the rest of the sequence. The example loads a small image and then its corresponding large image below it before it goes on to load the next thumb/large image combo.

The class dispatches a custom SequentialLoaderEvent depending on what happens. The events are as follows:

Here is the code:

PLAIN TEXT
Actionscript:
  1. /**
  2. * The SequentialLoader loads a series of SWFs and/or images in an ordered sequence.  This is a conversion of the AS2 SequentialLoader class
  3. * originally written by Tom Stanley [http://www.staticmethods.com] with some additional methods added for more control.
  4. *
  5. * <p>The class dispatches a custom SequentialLoaderEvent depending on what happens.  The events are as follows:</p>
  6. *
  7. * <ul>
  8. * <li>SequentialLoaderEvent.ON_ITEM_START: Dispatched when an item starts to load (params object contains index)</li>
  9. * <li>SequentialLoaderEvent.ON_ITEM_PROGRESS: Dispatched while an item is loading (params object contains index, percent loaded, bytesLoaded, bytesTotal)</li>
  10. * <li>SequentialLoaderEvent.ON_ITEM_INIT: Dispatched when an item is loaded (params object contains index, asset)</li>
  11. * <li>SequentialLoaderEvent.ON_ITEM_SKIPPED: Dispatched when an item fails to load (params object contains index)</li>
  12. * <li>SequentialLoaderEvent.ON_SEQUENCE_COMPLETE: Dispatched when every item in the sequence has finished loading</li>
  13. * </ul>
  14. *
  15. * @usage
  16. * <code>
  17. * <pre>
  18. import com.reintroducing.loaders.SequentialLoader;
  19. import com.reintroducing.events.SequentialLoaderEvent;
  21. var assets:Array = new Array("1.jpg", "2.jpg", "3.jpg", "4.jpg", "5.jpg");
  23. var sl:SequentialLoader = new SequentialLoader(assets, false);
  25. sl.addEventListener(SequentialLoaderEvent.ON_ITEM_START, handleItemStart);
  26. sl.addEventListener(SequentialLoaderEvent.ON_ITEM_PROGRESS, handleItemProgress);
  27. sl.addEventListener(SequentialLoaderEvent.ON_ITEM_INIT, handleItemInit);
  28. sl.addEventListener(SequentialLoaderEvent.ON_ITEM_SKIPPED, handleItemSkipped);
  29. sl.addEventListener(SequentialLoaderEvent.ON_SEQUENCE_COMPLETE, handleSequenceComplete);
  31. function handleItemStart($evt:SequentialLoaderEvent):void
  32. {
  33.     trace("Item " + $evt.params.index + " has started loading.");
  34. }
  36. function handleItemProgress($evt:SequentialLoaderEvent):void
  37. {
  38.     trace("Item " + $evt.params.index + " is " + $evt.params.percent + "% loaded");
  39. }
  41. function handleItemInit($evt:SequentialLoaderEvent):void
  42. {
  43.     var asset:Loader = $evt.params.asset;
  44.     asset.x = ($evt.params.index * 160);
  45.     addChild(asset);
  46. }
  48. function handleItemSkipped($evt:SequentialLoaderEvent):void
  49. {
  50.     trace("Item " + $evt.params.index + " skipped.");
  51. }
  53. function handleSequenceComplete($evt:SequentialLoaderEvent):void
  54. {
  55.     trace("Sequence completed.");
  56. }
  58. sl.start();
  59. * </pre>
  60. * </code>
  61. *
  62. * @author Matt Przybylski [http://www.reintroducing.com]
  63. * @version 1.0
  64. */
  65.  
  66. package com.reintroducing.loaders
  67. {
  68.     import flash.display.Loader;
  69.     import flash.events.Event;
  70.     import flash.events.EventDispatcher;
  71.     import flash.events.IOErrorEvent;
  72.     import flash.events.ProgressEvent;
  73.     import flash.net.URLRequest;
  74.    
  75.     import com.reintroducing.events.SequentialLoaderEvent; 
  76.  
  77.     public class SequentialLoader extends EventDispatcher
  78.     {
  79. //- PRIVATE & PROTECTED VARIABLES -------------------------------------------------------------------------
  80.  
  81.         private var _assets:Array;
  82.         private var _pauseAfterEachLoad:Boolean;
  83.         private var _isPaused:Boolean;
  84.         private var _totalLoads:uint;
  85.         private var _loader:Loader;
  86.         private var _currentIndex:uint;
  87.         private var _currentAsset:String;
  88.        
  89. //- PUBLIC & INTERNAL VARIABLES ---------------------------------------------------------------------------
  90.        
  91.         public static const DEFAULT_NAME:String = "com.reintroducing.loaders.SequentialLoader";
  92.        
  93. //- CONSTRUCTOR -------------------------------------------------------------------------------------------
  94.    
  95.         /**
  96.          * Creates a new instance of the SequentialLoader class and passes in the assets to load.  You can set the optional pauseAfterEachLoad boolean which allows you to
  97.          * pause after each item is loaded to do another action and then resume the SequentialLoader using the resume() method.
  98.          *
  99.          * @usage <pre><code>var sl:SequentialLoader = new SequentialLoader($assets, $pauseAfterEachLoad);</code></pre>
  100.          *
  101.          * @param $assets An array that holds the paths to the SWFs/images to be loaded
  102.          * @param $pauseAfterEachLoad A boolean that allows you to pause the SequentialLoader after each item is loaded
  103.          */
  104.        
  105.         public function SequentialLoader($assets:Array, $pauseAfterEachLoad:Boolean = false):void
  106.         {
  107.             this._assets = new Array();
  108.            
  109.             this._assets = $assets;
  110.             this._pauseAfterEachLoad = $pauseAfterEachLoad;
  111.             this._totalLoads = this._assets.length;
  112.         }
  113.        
  114. //- PRIVATE & PROTECTED METHODS ---------------------------------------------------------------------------
  115.        
  116.         private function loadItem($index:uint):void
  117.         {
  118.             this._currentIndex = $index;
  119.             this._currentAsset = this._assets[this._currentIndex];
  120.            
  121.             var l:Loader = new Loader();
  122.             l.contentLoaderInfo.addEventListener(Event.INIT, doLoadInit);
  123.             l.contentLoaderInfo.addEventListener(ProgressEvent.PROGRESS, doProgress);
  124.             l.contentLoaderInfo.addEventListener(IOErrorEvent.IO_ERROR, doError);
  125.            
  126.             l.load(new URLRequest(this._currentAsset));
  127.            
  128.             this._loader = l;
  129.            
  130.             var evt:SequentialLoaderEvent = new SequentialLoaderEvent(SequentialLoaderEvent.ON_ITEM_START, {index: this._currentIndex});
  131.             this.dispatchEvent(evt);
  132.         }
  133.        
  134.         private function completeSequence():void
  135.         {
  136.             var evt:SequentialLoaderEvent = new SequentialLoaderEvent(SequentialLoaderEvent.ON_SEQUENCE_COMPLETE, {});
  137.             this.dispatchEvent(evt);
  138.         }
  139.        
  140.         private function killEvents():void
  141.         {
  142.             this._loader.contentLoaderInfo.removeEventListener(Event.INIT, doLoadInit);
  143.             this._loader.contentLoaderInfo.removeEventListener(ProgressEvent.PROGRESS, doProgress);
  144.             this._loader.contentLoaderInfo.removeEventListener(IOErrorEvent.IO_ERROR, doError);
  145.             this._loader = null;
  146.         }
  147.        
  148. //- PUBLIC & INTERNAL METHODS -----------------------------------------------------------------------------
  149.    
  150.         /**
  151.          * Starts the loading of the specified assets.
  152.          *
  153.          * @usage <pre><code>sl.start();</code></pre>
  154.          *
  155.          * @return Nothing
  156.          */
  157.        
  158.         public function start():void
  159.         {
  160.             this.loadItem(0);
  161.         }
  162.        
  163.         /**
  164.          * Pauses the SequentialLoader at its current loading position.
  165.          *
  166.          * @usage <pre><code>sl.pause();</code></pre>
  167.          *
  168.          * @return Nothing
  169.          */
  170.        
  171.         public function pause():void
  172.         {
  173.             this._isPaused = true;
  174.         }
  175.        
  176.         /**
  177.          * Resume the SequentialLoader and load the next asset in the loading sequence.
  178.          *
  179.          * @usage <pre><code>sl.resume();</code></pre>
  180.          *
  181.          * @return Nothing
  182.          */
  183.        
  184.         public function resume():void
  185.         {
  186.             this._isPaused = false;
  187.             this._currentIndex++;
  188.             this.loadItem(this._currentIndex);
  189.         }
  190.        
  191.         /**
  192.          * Cleans up the listeners used by the current Loader.
  193.          *
  194.          * @usage <pre><code>sl.destroy();</code></pre>
  195.          *
  196.          * @return Nothing
  197.          */
  198.        
  199.         public function destroy():void
  200.         {
  201.             this.killEvents();
  202.         }
  203.  
  204. //- EVENT HANDLERS ----------------------------------------------------------------------------------------
  205.    
  206.         private function doProgress($evt:ProgressEvent):void
  207.         {
  208.             var percent:Number = Math.ceil(($evt.bytesLoaded / $evt.bytesTotal) * 100);
  209.            
  210.             var params:Object = new Object();
  211.             params.index = this._currentIndex;
  212.             params.percent = percent;
  213.             params.bytesLoaded = $evt.bytesLoaded;
  214.             params.bytesTotal = $evt.bytesTotal;
  215.            
  216.             var evt:SequentialLoaderEvent = new SequentialLoaderEvent(SequentialLoaderEvent.ON_ITEM_PROGRESS, params);
  217.             this.dispatchEvent(evt);
  218.         }
  219.        
  220.         private function doLoadInit($evt:Event):void
  221.         {
  222.             var params:Object = new Object();
  223.             params.index = this._currentIndex;
  224.             params.asset = $evt.target.loader;
  225.            
  226.             var evt:SequentialLoaderEvent = new SequentialLoaderEvent(SequentialLoaderEvent.ON_ITEM_INIT, params);
  227.             this.dispatchEvent(evt);
  228.            
  229.             this.killEvents();
  230.            
  231.             if (this._currentIndex <(this._totalLoads - 1))
  232.             {
  233.                 if (this._isPaused)
  234.                 {
  235.                     return;
  236.                 }
  237.                 else if (this._pauseAfterEachLoad != true)
  238.                 {
  239.                     this._currentIndex++;
  240.                     this.loadItem(this._currentIndex);
  241.                 }
  242.             }
  243.             else
  244.             {
  245.                 this.completeSequence();
  246.             }
  247.         }
  248.        
  249.         private function doError($evt:IOErrorEvent):void
  250.         {
  251.             var params:Object = new Object();
  252.             params.index = this._currentIndex;
  253.            
  254.             var evt:SequentialLoaderEvent = new SequentialLoaderEvent(SequentialLoaderEvent.ON_ITEM_SKIPPED, params);
  255.             this.dispatchEvent(evt);
  256.            
  257.             this.killEvents();
  258.            
  259.             if (this._currentIndex <this._totalLoads - 1)
  260.             {
  261.                 if (this._isPaused)
  262.                 {
  263.                     return;
  264.                 }
  265.                 else if (this._pauseAfterEachLoad != true)
  266.                 {
  267.                     this._currentIndex++;
  268.                     this.loadItem(this._currentIndex);
  269.                 }
  270.             }
  271.             else
  272.             {
  273.                 this.completeSequence();
  274.             }
  275.         }
  276.    
  277. //- GETTERS & SETTERS -------------------------------------------------------------------------------------
  278.    
  279.         /**
  280.          * Returns the value of isPaused.
  281.          *
  282.          * @usage <pre><code>trace(sl.isPaused);</code></pre>
  283.          *
  284.          * @return Boolean
  285.          */
  286.        
  287.         public function get isPaused():Boolean
  288.         {
  289.             return this._isPaused;
  290.         }
  291.        
  292.         /**
  293.          * Sets the value of isPaused.
  294.          *
  295.          * @usage <pre><code>sl.isPaused = true;</code></pre>
  296.          *
  297.          * @return Nothing
  298.          */
  299.        
  300.         public function set isPaused($val:Boolean):void
  301.         {
  302.             this._isPaused = $val;
  303.         }
  304.        
  305.         /**
  306.          * Returns the value of pauseAfterEachLoad.
  307.          *
  308.          * @usage <pre><code>trace(sl.pauseAfterEachLoad);</code></pre>
  309.          *
  310.          * @return Boolean
  311.          */
  312.        
  313.         public function get pauseAfterEachLoad():Boolean
  314.         {
  315.             return this._pauseAfterEachLoad;
  316.         }
  317.  
  318.         /**
  319.          * Sets the value of pauseAfterEachLoad.
  320.          *
  321.          * @usage <pre><code>sl.pauseAfterEachLoad = true;</code></pre>
  322.          *
  323.          * @return Nothing
  324.          */
  325.        
  326.         public function set pauseAfterEachLoad($val:Boolean):void
  327.         {
  328.             this._pauseAfterEachLoad = $val;
  329.         }
  330.  
  331. //- HELPERS -----------------------------------------------------------------------------------------------
  332.    
  333.         public override function toString():String
  334.         {
  335.             return "com.reintroducing.loaders.SequentialLoader";
  336.         }
  337.    
  338. //- END CLASS ---------------------------------------------------------------------------------------------
  339.     }
  340. }

, , ,

If you found this post useful, please consider leaving a comment, subscribing to the feed, or making a small donation.

19 Comments
Comment by Lawrence on February 1, 2008 @ 11:43 AM

Hello. Just had a brief look and its looking very cool. It's a great contribution to the community. Appreciated.

(PS What plugin is that - can you email it because the one at my blog died..) Thanks

Comment by Matt Przybylski on February 2, 2008 @ 6:32 AM

Thanks Lawrence.

Which plugin are you talking about? The code hilighter? If that's the case, its iG:Syntax Hiliter.

Pingback by AS3: SequentialLoader v1.1 on October 14, 2008 @ 3:14 PM

[...] made a very small update to the SequentialLoader which allows you to pass in an optional parameter to check for policy files when loading content [...]

Comment by Joe on October 15, 2008 @ 11:35 AM

This is awesome. Haven't looked into the code yet, but is it possible to make this load images from an XML file?

Comment by Matt Przybylski on October 15, 2008 @ 12:26 PM

Joe,
Sure! You just have to parse the paths of the images into an array so that you could pass that array in as the asset array before initializing the SequentialLoader.

Comment by Joe on October 15, 2008 @ 2:13 PM

Matt, that's awesome. Thanks!

Comment by Joe on October 17, 2008 @ 11:31 AM

Matt,

I got the SequentialLoader to pull images from an XML file.
It works great but I'm also adding movieclip buttons on the stage, one for each image. I want the buttons to correspond to an image. It's simple to associate a button with an image in a standard XML gallery, but not sure how to do that here.
Basically I just want to add one button for each image, then have that image move to the front and alpha tween to 100%.

Comment by Matt Przybylski on October 17, 2008 @ 12:18 PM

Joe,
It's hard to say because I don't know how your files are set up, but if you take a look at the Image Slider on this blog you could see how I used the SequentialLoader and then had images corresponding to an xml file as well as being clickable. Hope that helps

Comment by Joe on October 17, 2008 @ 2:52 PM

Thanks- I'll check out the image slider.

Comment by ukasz on September 30, 2009 @ 7:57 AM

Just using your class in project and gotta say - it's a really nice time saver! Big tkank YOU Matt! Best regards!

Comment by metaisaak on December 2, 2009 @ 5:21 PM

Hey, great work,i've used it, but, it can be used to download video alongside with swf or images?

cheers
have a nice day

Comment by Matt Przybylski on December 3, 2009 @ 10:19 AM

@metaisaak: Unfortunately no, it only works for images/swfs.

Comment by metaisaak on December 3, 2009 @ 12:44 PM

Thanksanyway.. great job,!

Comment by Eric on May 9, 2010 @ 10:24 AM

What happens to the params object that is stored in the SequentialLoaderEvent. Does this stay in memory because i don't see anywhere its getting removed. Other than that I think this is a great class and well done in its setup.

Comment by Matt Przybylski on May 10, 2010 @ 10:16 AM

@Eric: Unfortunately there is nothing to clear that object, though I'd presume it'd be pretty easy to write something to either clear it or just set it to null when done with it. Either way I don't think the footprint of it is very large at all unless you have hundreds of them. And thanks for the kind words, I've actually built a newer system of managing image loading since this but have yet to release it, probably because you will find out shortly that there is something even better thats going to become available :P

Comment by Eric on May 10, 2010 @ 10:22 AM

What if you set your public params to private and used a getter and setter to retrieve it. Would you still need to use a destroy method to clean up the private params property.

"I've actually built a newer system of managing image loading since this but have yet to release it, probably because you will find out shortly that there is something even better thats going to become available"

Please let us know when you release the new version. Do you mean you are releasing something better or someone else is releasing something better?

Thanks,
Eric

Comment by Matt Przybylski on May 10, 2010 @ 10:36 AM

@Eric: If you set them to private and use get/set you'll have to create a method to destroy them, yes.

And while I do have something better, someone else has something that is going to "revolutionize" loading of external assets :P

Comment by Eric on May 10, 2010 @ 12:35 PM

Great keep us posted when it comes out.

Comment by krazl on June 22, 2010 @ 9:32 PM

I've added "params.MCasset = $evt.target.loader.content;" on your SequentialLoader.as file to enable casting into MovieClip.

Btw very good class!! two thumbs up!!

"
private function doLoadInit($evt:Event):void
{
var params:Object = new Object();
params.index = this._currentIndex;
params.asset = $evt.target.loader;
params.MCasset = $evt.target.loader.content;

"

Leave a comment

(required)

(required)