Packagecom.greensock.loading
Classpublic class LoaderMax
InheritanceLoaderMax Inheritance LoaderCore Inheritance flash.events.EventDispatcher

In its simplest form, a LoaderMax provides a way to group a sequence of loaders together and report their progress as a whole. It is essentially a queue of loaders. But there are many other conveniences that the LoaderMax system delivers: Example AS3 code:
import com.greensock.*;
import com.greensock.loading.*;
import com.greensock.events.LoaderEvent;
import com.greensock.loading.display.*;
 
//create a LoaderMax named "mainQueue" and set up onProgress, onComplete and onError listeners
var queue:LoaderMax = new LoaderMax({name:"mainQueue", onProgress:progressHandler, onComplete:completeHandler, onError:errorHandler});
//append several loaders
queue.append( new XMLLoader("xml/data.xml", {name:"xmlDoc", alternateURL:"http://otherserver.com/data.xml"}) );
queue.append( new ImageLoader("img/photo1.jpg", {name:"photo1", estimatedBytes:2400, container:this, alpha:0, width:250, height:150, scaleMode:"proportionalInside"}) );
queue.append( new SWFLoader("swf/main.swf", {name:"mainClip", estimatedBytes:3000, container:this, x:250, autoPlay:false}) );
//add a loader to the top of the queue using prepend()
queue.prepend( new MP3Loader("mp3/audio.mp3", {name:"audio", repeat:100, autoPlay:true}) );
//prioritize the loader named "photo1"
LoaderMax.prioritize("photo1");  //same as LoaderMax.getLoader("photo1").prioritize();
//start loading
queue.load();
function progressHandler(event:LoaderEvent):void {
    trace("progress: " + event.target.progress);
}
function completeHandler(event:LoaderEvent):void {
     var image:ContentDisplay = LoaderMax.getContent("photo1");
     TweenLite.to(image, 1, {alpha:1, y:100});
     trace(event.target + " is complete!");
}
 
function errorHandler(event:LoaderEvent):void {
    trace("error occured with " + event.target + ": " + event.text);
}
 

LoaderMax will automatically skip over any child loaders in the queue that are already complete. By default it will also skip any that have failed or are paused (you can change this behavior with the skipFailed and skipPaused special properties). To flush the content and force a full reload, simply unload() first or use the flushContent parameter in load() like load(true).

OPTIONAL VARS PROPERTIES

The following special properties can be passed into the LoaderMax constructor via the vars parameter which can be either a generic object or a LoaderMaxVars object:

Note: Using a LoaderMaxVars instance instead of a generic object to define your vars is a bit more verbose but provides code hinting and improved debugging because it enforces strict data typing. Use whichever one you prefer.

Copyright 2010-2013, GreenSock. All rights reserved. This work is subject to the terms in http://www.greensock.com/terms_of_use.html or for Club GreenSock members, the software agreement that was issued with the membership.

See also

com.greensock.loading.data.LoaderMaxVars


Public Properties
 PropertyDefined By
  auditedSize : Boolean
[override] [read-only] Indicates whether or not the loader's bytesTotal value has been set by any of the following: Defining an estimatedBytes in the vars object passed to the constructor Calling auditSize() and getting a response (an error is also considered a response) When a LoaderMax instance begins loading, it will automatically force a call to auditSize() for any of its children that don't have an estimatedBytes defined.
LoaderMax
 InheritedautoDispose : Boolean
When autoDispose is true, the loader will be disposed immediately after it completes (it calls the dispose() method internally after dispatching its COMPLETE event).
LoaderCore
  autoLoad : Boolean
If true, the LoaderMax instance will automatically call load() whenever you insert()/append()/prepend() a new loader whose status is LoaderStatus.READY.
LoaderMax
 InheritedbytesLoaded : uint
[read-only] Bytes loaded
LoaderCore
 InheritedbytesTotal : uint
[read-only] Total bytes that are to be loaded by the loader.
LoaderCore
  content : *
[override] [read-only] An array containing the content of each loader inside the LoaderMax
LoaderMax
  contentDisplayClass : Class
[static] The class used by ImageLoaders, SWFLoaders, and VideoLoaders to create the containers into which they'll dump their rawContent - by default it is the com.greensock.loading.display.ContentDisplay class but if you're using Flex, it is typically best to change this to com.greensock.loading.display.FlexContentDisplay.
LoaderMax
  defaultAuditSize : Boolean = true
[static] Controls the default value of auditSize in LoaderMax instances (normally true).
LoaderMax
  defaultContext : LoaderContext
[static] Optionally define a default LoaderContext to use with SWFLoaders and ImageLoaders.
LoaderMax
  defaultEstimatedBytes : uint = 20000
[static] The default value that will be used for the estimatedBytes on loaders that don't declare one in the vars parameter of the constructor.
LoaderMax
 InheritedloadTime : Number
[read-only] The number of seconds that elapsed between when the loader began and when it either completed, failed, or was canceled.
LoaderCore
  maxConnections : uint
Maximum number of simultaneous connections that should be used while loading the LoaderMax queue.
LoaderMax
 Inheritedname : String
A name that you use to identify the loader instance.
LoaderCore
  numChildren : uint
[read-only] Number of child loaders currently contained in the LoaderMax instance (does not include deeply nested loaders - only children).
LoaderMax
 Inheritedpaused : Boolean
If a loader is paused, its progress will halt and any LoaderMax instances to which it belongs will either skip over it or stop when its position is reached in the queue (depending on whether or not the LoaderMax's skipPaused property is true).
LoaderCore
 Inheritedprogress : Number
[read-only] A value between 0 and 1 indicating the overall progress of the loader.
LoaderCore
  rawProgress : Number
[read-only] An unweighted value between 0 and 1 indicating the overall loading progress of the LoaderMax - this calculation does not concern itself whatsoever with bytesLoaded and bytesTotal but rather the ratio of the children that are loaded (all having equal weight).
LoaderMax
  skipFailed : Boolean
If skipFailed is true (the default), any failed loaders in the queue will be skipped.
LoaderMax
  skipPaused : Boolean
If skipPaused is true (the default), any paused loaders in the queue will be skipped.
LoaderMax
  status : int
[override] [read-only] Integer code indicating the loader's status; options are LoaderStatus.READY, LoaderStatus.LOADING, LoaderStatus.COMPLETED, LoaderStatus.PAUSED, and LoaderStatus.DISPOSED.
LoaderMax
 Inheritedvars : Object
An object containing optional configuration details, typically passed through a constructor parameter.
LoaderCore
Public Methods
 MethodDefined By
  
LoaderMax(vars:Object = null)
Constructor
LoaderMax
  
activate(loaderClasses:Array):void
[static] Activates particular loader classes (like ImageLoader, SWFLoader, etc.) so that they can be recognized inside the parse() method and XMLLoader.
LoaderMax
 Inherited
addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void
[override]
LoaderCore
  
Appends a loader to the end of the queue.
LoaderMax
  
auditSize():void
[override] Attempts loading just enough of the content to accurately determine the bytesTotal in order to improve the accuracy of the progress property.
LoaderMax
 Inherited
cancel():void
If the loader is currently loading (status is LoaderStatus.LOADING), it will be canceled immediately and its status will change to LoaderStatus.READY.
LoaderCore
 Inherited
dispose(flushContent:Boolean = false):void
Disposes of the loader and releases it internally for garbage collection.
LoaderCore
  
empty(disposeChildren:Boolean = true, unloadAllContent:Boolean = false):void
Empties the LoaderMax of all its loaders and optionally disposes/unloads them.
LoaderMax
  
getChildAt(index:int):*
Returns the child that is at a particular position (zero-based index) in the queue.
LoaderMax
  
Finds the index position of a particular loader in the LoaderMax.
LoaderMax
  
getChildren(includeNested:Boolean = false, omitLoaderMaxes:Boolean = false):Array
Returns and array of all child loaders inside the LoaderMax, optionally exposing more deeply nested instances as well (like loaders inside a child LoaderMax instance).
LoaderMax
  
getChildrenByStatus(status:int, includeNested:Boolean = false, omitLoaderMaxes:Boolean = false):Array
Returns and array of child loaders that currently have a particular status.
LoaderMax
  
getContent(nameOrURL:String):*
Finds the content of a loader based on its name or url.
LoaderMax
  
getContent(nameOrURL:String):*
[static] Searches ALL loaders to find content based on its name or url.
LoaderMax
  
getLoader(nameOrURL:String):*
Finds a loader based on its name or url.
LoaderMax
  
getLoader(nameOrURL:String):*
[static] Searches ALL loaders to find one based on its name or url.
LoaderMax
  
insert(loader:LoaderCore, index:uint = 999999999):LoaderCore
Inserts a loader at a particular position in the queue.
LoaderMax
 Inherited
load(flushContent:Boolean = false):void
Loads the loader's content, optionally flushing any previously loaded content first.
LoaderCore
  
parse(data:*, vars:Object = null, childrenVars:Object = null):*
[static] Analyzes a url or array of urls and attempts to automatically create the appropriate loader(s) based on file extension(s) in the url(s), returning either an individual loader like an ImageLoader, SWFLoader, XMLLoader, etc or if an array is passed in, a LoaderMax will be returned containing a child for each parsed url (or URLRequest) in the array.
LoaderMax
 Inherited
pause():void
Pauses the loader immediately.
LoaderCore
  
Prepends a loader at the beginning of the queue (append() adds the loader to the end whereas prepend() adds it to the beginning).
LoaderMax
  
prependURLs(prependText:String, includeNested:Boolean = false):void
Immediately prepends a value to the beginning of each child loader's url.
LoaderMax
  
prioritize(nameOrURL:String, loadNow:Boolean = true):LoaderCore
[static] Immediately prioritizes a loader inside any LoaderMax instances that contain it, forcing it to the top position in their queue and optionally calls load() immediately as well.
LoaderMax
  
registerFileType(extensions:String, loaderClass:Class):void
[static] By default, LoaderMax associates certain file extensions with certain types of loaders, like "jpg", "png", and "gif" are associated with ImageLoader and "swf" is associated with SWFLoader so that the LoaderMax.parse() method can recognize and create the appropriate loaders for each URL passed in.
LoaderMax
  
remove(loader:LoaderCore):void
Removes a loader from the LoaderMax.
LoaderMax
  
replaceURLText(fromText:String, toText:String, includeNested:Boolean = false):void
Immediately replaces a certain substring in each child loader's url with another string, making it simple to do something like change "{imageDirectory}image1.jpg" to "http://www.greensock.com/images/image1.jpg".
LoaderMax
 Inherited
resume():void
Unpauses the loader and resumes loading immediately.
LoaderCore
 Inherited
toString():String
[override] Returns information about the loader, like its type, its name, and its url (if it has one).
LoaderCore
 Inherited
unload():void
Removes any content that was loaded and sets bytesLoaded back to zero.
LoaderCore
Protected Methods
 MethodDefined By
  
_passThroughEvent(event:Event):void
[override]
LoaderMax
Events
 Event Summary Defined By
 InheritedDispatched when the loader is canceled while loading which can occur either because of a failure or when a sibling loader is prioritized in a LoaderMax queue.LoaderCore
  Dispatched when any child of the LoaderMax instance dispatches a CANCEL event which could occur when another child is prioritized in the queue or when the LoaderMax is canceled while loading the child.LoaderMax
  Dispatched when any child of the LoaderMax instance completes.LoaderMax
  Dispatched when any child of the LoaderMax instance fails to load.LoaderMax
  Dispatched when any child of the LoaderMax instance starts loading.LoaderMax
  Dispatched when any child of the LoaderMax instance dispatches a PROGRESS event.LoaderMax
 InheritedDispatched when the loader completes.LoaderCore
 InheritedDispatched when the loader experiences some type of error, like a SECURITY_ERROR or IO_ERROR.LoaderCore
 InheritedDispatched when the loader fails.LoaderCore
  Dispatched when any child of the LoaderMax instance dispatches an HTTP_STATUS event.LoaderMax
  Dispatched when any child of the LoaderMax instance dispatches an IO_ERROR event.LoaderMax
 InheritedDispatched when the loader starts loading.LoaderCore
 InheritedDispatched each time the bytesLoaded value changes while loading (indicating progress).LoaderCore
  Dispatched when any child of the LoaderMax instance dispatches a SCRIPT_ACCESS_DENIED event.LoaderMax
  Dispatched when any child of the LoaderMax instance dispatches a SECURITY_ERROR event.LoaderMax
 InheritedDispatched when the loader unloads (which happens when either unload() or dispose(true) is called or if a loader is canceled while in the process of loading).LoaderCore
Property Detail
auditedSizeproperty
auditedSize:Boolean  [read-only] [override]

Indicates whether or not the loader's bytesTotal value has been set by any of the following:


Implementation
    public function get auditedSize():Boolean
autoLoadproperty 
public var autoLoad:Boolean

If true, the LoaderMax instance will automatically call load() whenever you insert()/append()/prepend() a new loader whose status is LoaderStatus.READY. This basically makes it easy to create a LoaderMax queue and dump stuff into it whenever you want something to load without having to check the LoaderMax's status and call load() manually if it's not already loading.

contentproperty 
content:*  [read-only] [override]

An array containing the content of each loader inside the LoaderMax


Implementation
    public function get content():*
contentDisplayClassproperty 
public static var contentDisplayClass:Class

The class used by ImageLoaders, SWFLoaders, and VideoLoaders to create the containers into which they'll dump their rawContent - by default it is the com.greensock.loading.display.ContentDisplay class but if you're using Flex, it is typically best to change this to com.greensock.loading.display.FlexContentDisplay. You only need to do this once, like

import com.greensock.loading.LoaderMax;
import com.greensock.loading.display.FlexContentDisplay;
LoaderMax.contentDisplayClass = FlexContentDisplay;

defaultAuditSizeproperty 
public static var defaultAuditSize:Boolean = true

Controls the default value of auditSize in LoaderMax instances (normally true). For most situations, the auditSize feature is very convenient for ensuring that the overall progress of LoaderMax instances is reported accurately, but when working with very large quantities of files that have no estimatedBytes defined, some developers prefer to turn auditSize off by default. Of course you can always override the default for individual LoaderMax instances by defining an auditSize value in the vars parameter of the constructor.

defaultContextproperty 
public static var defaultContext:LoaderContext

Optionally define a default LoaderContext to use with SWFLoaders and ImageLoaders. This can be useful if you're loading a lot of swfs, for example, and don't want to pass a custom "context" in to each one. LoaderContexts are typically used to tell Flash which ApplicationDomain to load the code into and which SecurityDomain to use. See Adobe's docs for details.

defaultEstimatedBytesproperty 
public static var defaultEstimatedBytes:uint = 20000

The default value that will be used for the estimatedBytes on loaders that don't declare one in the vars parameter of the constructor.

maxConnectionsproperty 
public var maxConnections:uint

Maximum number of simultaneous connections that should be used while loading the LoaderMax queue. A higher number will generally result in faster overall load times for the group. The default is 2. This value is instance-based, not system-wide, so if you have two LoaderMax instances that both have a maxConnections value of 3 and they are both loading, there could be up to 6 connections at a time total.

numChildrenproperty 
numChildren:uint  [read-only]

Number of child loaders currently contained in the LoaderMax instance (does not include deeply nested loaders - only children). To get the quantity of all children including nested ones, use getChildren(true, true).length


Implementation
    public function get numChildren():uint

See also

rawProgressproperty 
rawProgress:Number  [read-only]

An unweighted value between 0 and 1 indicating the overall loading progress of the LoaderMax - this calculation does not concern itself whatsoever with bytesLoaded and bytesTotal but rather the ratio of the children that are loaded (all having equal weight). Therefore, rawProgress is a more crude way of measuring the overall loading progress and isn't weighted in terms of file size the way that progress is. The only benefit of using rawProgress instead of progress is that there is never a risk of the value moving backwards the way it can with progress when child loaders have inaccurately low estimatedByte values (before LoaderMax audits the file size values). The rate at which rawProgress increases may slow down or speed up depending on the file size of the asset currently loading. For example, if a LoaderMax contains two loaders, the first for a file that's 100k and the second for a file that's 10,000k, rawProgress will move quickly (while loading the 100k file) until it reaches 0.5 and then slow down significantly (while loading the 10,000k file) until it reaches 1.

Or let's say you have a LoaderMax that contains 3 ImageLoaders: the first two must load images that are 25k each and the 3rd one must load an image that's 450k. After the first two ImageLoaders finish, the LoaderMax's progress property would report 0.1 (50k loaded out of 500k total) whereas the rawProgress would report 0.66 (2 loaders out of 3 total have completed). However, if you set the estimatedBytes of all of the ImageLoaders in this example to 25600 (25k) and set the LoaderMax's auditSize to false, the progress would read about 0.66 after the first two ImageLoaders complete (it still thinks they're all 25k) and then when the 3rd one starts loading and LoaderMax finds out that it's 450k, the bytesTotal would automatically adjust and the progress would jump backwards to 0.1 (which correctly reflects the weighted progress). Of course a solution would be to more accurately set the estimatedBytes and/or leave auditSize true in the LoaderMax, but rawProgress can be useful if those solutions are undesirable in your scenario and you need to avoid any backwards adjustment of a preloader progress bar or some other interface element.


Implementation
    public function get rawProgress():Number

See also

skipFailedproperty 
public var skipFailed:Boolean

If skipFailed is true (the default), any failed loaders in the queue will be skipped. Otherwise, the LoaderMax will stop when it hits a failed loader and the LoaderMax's status will become LoaderStatus.FAILED. Skipped loaders are also ignored when the LoaderMax determines its bytesLoaded, bytesTotal, and progress values.

skipPausedproperty 
public var skipPaused:Boolean

If skipPaused is true (the default), any paused loaders in the queue will be skipped. Otherwise, the LoaderMax will stop when it hits a paused loader and the LoaderMax's status will become LoaderStatus.FAILED. Skipped loaders are also ignored when the LoaderMax determines its bytesLoaded, bytesTotal, and progress values.

statusproperty 
status:int  [read-only] [override]

Integer code indicating the loader's status; options are LoaderStatus.READY, LoaderStatus.LOADING, LoaderStatus.COMPLETED, LoaderStatus.PAUSED, and LoaderStatus.DISPOSED.


Implementation
    public function get status():int
Constructor Detail
LoaderMax()Constructor
public function LoaderMax(vars:Object = null)

Constructor

Parameters
vars:Object (default = null) — An object containing optional configuration details. For example: new LoaderMax({name:"queue", onComplete:completeHandler, onProgress:progressHandler, maxConnections:3}).

The following special properties can be passed into the LoaderMax constructor via the vars parameter which can be either a generic object or a LoaderMaxVars object:

  • name : String - A name that is used to identify the LoaderMax instance. This name can be fed to the LoaderMax.getLoader() or LoaderMax.getContent() methods or traced at any time. Each loader's name should be unique. If you don't define one, a unique name will be created automatically, like "loader21".
  • auditSize : Boolean - By default, when the LoaderMax begins to load it quickly loops through its children and if it finds any that don't have an estimatedBytes defined, it will briefly open a URLStream in order to attempt to determine its bytesTotal, immediately closing the URLStream once the value has been determined. This causes a brief delay initially, but greatly improves the accuracy of the progress and bytesTotal values. Set auditSize to false to prevent the LoaderMax from auditing its childrens' size (it is true by default). For maximum performance, it is best to define an estimatedBytes value for as many loaders as possible to avoid the delay caused by audits. When the LoaderMax audits an XMLLoader, it cannot recognize loaders that will be created from the XML data nor can it recognize loaders inside subloaded swf files from a SWFLoader (it would take far too long to load sufficient data for that - audits should be as fast as possible). If you do not set an appropriate estimatedSize for XMLLoaders or SWFLoaders that contain LoaderMax loaders, you'll notice that the parent LoaderMax's progress and bytesTotal change when the nested loaders are recognized (this is normal). To control the default auditSize value, use the static LoaderMax.defaultAuditSize property.
  • maxConnections : uint - Maximum number of simultaneous connections that should be used while loading the LoaderMax queue. A higher number will generally result in faster overall load times for the group. The default is 2. This value is instance-based, not system-wide, so if you have two LoaderMax instances that both have a maxConnections value of 3 and they are both loading, there could be up to 6 connections at a time total. Sometimes there are limits imposed by the Flash Player itself or the browser or the user's system, but LoaderMax will do its best to honor the maxConnections you define.
  • skipFailed : Boolean - If skipFailed is true (the default), any failed loaders in the queue will be skipped. Otherwise, the LoaderMax will stop when it hits a failed loader and the LoaderMax's status will become LoaderStatus.FAILED.
  • skipPaused : Boolean - If skipPaused is true (the default), any paused loaders in the queue will be skipped. Otherwise, the LoaderMax will stop when it hits a paused loader and the LoaderMax's status will become LoaderStatus.FAILED.
  • autoLoad : Boolean - If true, the LoaderMax instance will automatically call load() whenever you insert()/append()/prepend() a new loader whose status is LoaderStatus.READY. This basically makes it easy to create a LoaderMax queue and dump stuff into it whenever you want it to load without having to check the LoaderMax's status and call load() manually if it's not already loading.
  • loaders : Array - An array of loaders (ImageLoaders, SWFLoaders, XMLLoaders, MP3Loaders, other LoaderMax instances, etc.) that should be immediately inserted into the LoaderMax.
  • requireWithRoot : DisplayObject - LoaderMax supports subloading, where an object can be factored into a parent's loading progress. If you want this LoaderMax to be required as part of its parent SWFLoader's progress, you must set the requireWithRoot property to your swf's root. For example, var loader:LoaderMax = new LoaderMax({name:"mainQueue", requireWithRoot:this.root});
  • autoDispose : Boolean - When autoDispose is true, the loader will be disposed immediately after it completes (it calls the dispose() method internally after dispatching its COMPLETE event). This will remove any listeners that were defined in the vars object (like onComplete, onProgress, onError, onInit). Once a loader is disposed, it can no longer be found with LoaderMax.getLoader() or LoaderMax.getContent() - it is essentially destroyed but its content is not unloaded (you must call unload() or dispose(true) to unload its content). The default autoDispose value is false.

    ----EVENT HANDLER SHORTCUTS----

  • onOpen : Function - A handler function for LoaderEvent.OPEN events which are dispatched when the loader begins loading. Make sure your onOpen function accepts a single parameter of type LoaderEvent (com.greensock.events.LoaderEvent).
  • onProgress : Function - A handler function for LoaderEvent.PROGRESS events which are dispatched whenever the bytesLoaded changes. Make sure your onProgress function accepts a single parameter of type LoaderEvent (com.greensock.events.LoaderEvent). You can use the LoaderEvent's target.progress to get the loader's progress value or use its target.bytesLoaded and target.bytesTotal.
  • onComplete : Function - A handler function for LoaderEvent.COMPLETE events which are dispatched when the loader has finished loading. Make sure your onComplete function accepts a single parameter of type LoaderEvent (com.greensock.events.LoaderEvent).
  • onCancel : Function - A handler function for LoaderEvent.CANCEL events which are dispatched when loading is aborted due to either an error or because another loader was prioritized or cancel() was manually called. Make sure your onCancel function accepts a single parameter of type LoaderEvent (com.greensock.events.LoaderEvent).
  • onError : Function - A handler function for LoaderEvent.ERROR events which are dispatched whenever the loader or any of its children fails (typically because of an IO_ERROR or SECURITY_ERROR). Make sure your onError function accepts a single parameter of type LoaderEvent (com.greensock.events.LoaderEvent).
  • onChildOpen : Function - A handler function for LoaderEvent.CHILD_OPEN events which are dispatched each time one of the loader's children (or any descendant) begins loading. Make sure your onChildOpen function accepts a single parameter of type LoaderEvent (com.greensock.events.LoaderEvent).
  • onChildProgress : Function - A handler function for LoaderEvent.CHILD_PROGRESS events which are dispatched each time one of the loader's children (or any descendant) dispatches a PROGRESS event. To listen for changes in the LoaderMax's overall progress, use the onProgress special property instead. You can use the LoaderEvent's target.progress to get the child loader's progress value or use its target.bytesLoaded and target.bytesTotal. The LoaderEvent's currentTarget refers to the LoaderMax, so you can check its overall progress with the LoaderEvent's currentTarget.progress. Make sure your onChildProgress function accepts a single parameter of type LoaderEvent (com.greensock.events.LoaderEvent).
  • onChildComplete : Function - A handler function for LoaderEvent.CHILD_COMPLETE events which are dispatched each time one of the loader's children (or any descendant) finishes loading successfully. Make sure your onChildComplete function accepts a single parameter of type LoaderEvent (com.greensock.events.LoaderEvent).
  • onChildCancel : Function - A handler function for LoaderEvent.CHILD_CANCEL events which are dispatched each time loading is aborted on one of the loader's children (or any descendant) due to either an error or because another loader was prioritized in the queue or because cancel() was manually called on the child loader. Make sure your onChildCancel function accepts a single parameter of type LoaderEvent (com.greensock.events.LoaderEvent).
  • onChildFail : Function - A handler function for LoaderEvent.CHILD_FAIL events which are dispatched each time one of the loader's children (or any descendant) fails (and its status chances to LoaderStatus.FAILED). Make sure your onChildFail function accepts a single parameter of type LoaderEvent (com.greensock.events.LoaderEvent).
  • onIOError : Function - A handler function for LoaderEvent.IO_ERROR events which will also call the onError handler, so you can use that as more of a catch-all whereas onIOError is specifically for LoaderEvent.IO_ERROR events. Make sure your onIOError function accepts a single parameter of type LoaderEvent (com.greensock.events.LoaderEvent).
  • onHTTPStatus : Function - A handler function for LoaderEvent.HTTP_STATUS events. Make sure your onHTTPStatus function accepts a single parameter of type LoaderEvent (com.greensock.events.LoaderEvent).
  • onScriptAccessDenied : Function - A handler function for LoaderEvent.SCRIPT_ACCESS_DENIED events which are dispatched when one of the LoaderMax's children (or any descendant) is loaded from another domain and no crossdomain.xml is in place to grant full script access for things like smoothing or BitmapData manipulation. Make sure your function accepts a single parameter of type LoaderEvent (com.greensock.events.LoaderEvent).

See also

Method Detail
_passThroughEvent()method
override protected function _passThroughEvent(event:Event):void

Parameters

event:Event

activate()method 
public static function activate(loaderClasses:Array):void

Activates particular loader classes (like ImageLoader, SWFLoader, etc.) so that they can be recognized inside the parse() method and XMLLoader. For example, if LoaderMax.parse("image.jpg") is called without first activating ImageLoader (like LoaderMax.activate([ImageLoader])), it wouldn't properly recognize the ".jpg" extension and return the necessary ImageLoader instance. Likewise, without activating ImageLoader first, XMLLoader wouldn't be able to recognize <ImageLoader> nodes nested inside an XML file. You only need to activate() the loader classes once in your swf. For example:

LoaderMax.activate([ImageLoader, SWFLoader, MP3Loader, DataLoader, CSSLoader]);

The reason all loaders aren't activated by default is to conserve file size.

Parameters

loaderClasses:Array — An array of loader classes, like [ImageLoader, SWFLoader, MP3Loader].

append()method 
public function append(loader:LoaderCore):LoaderCore

Appends a loader to the end of the queue.

Parameters

loader:LoaderCore — The loader to append to the queue. It can be any loader (ImageLoader, XMLLoader, SWFLoader, MP3Loader, another LoaderMax, etc.).

Returns
LoaderCore — The loader that was appended.

See also

auditSize()method 
override public function auditSize():void

Attempts loading just enough of the content to accurately determine the bytesTotal in order to improve the accuracy of the progress property. Once the bytesTotal has been determined or the auditSize() attempt fails due to an error (typically IO_ERROR or SECURITY_ERROR), the auditedSize property will be set to true. Auditing the size opens a URLStream that will be closed as soon as a response is received.

empty()method 
public function empty(disposeChildren:Boolean = true, unloadAllContent:Boolean = false):void

Empties the LoaderMax of all its loaders and optionally disposes/unloads them.

Parameters

disposeChildren:Boolean (default = true) — If true (the default), dispose() will be called on all loaders in the LoaderMax.
 
unloadAllContent:Boolean (default = false) — If true, the content of all child loaders will be unloaded.

See also

getChildAt()method 
public function getChildAt(index:int):*

Returns the child that is at a particular position (zero-based index) in the queue. For example, myLoaderMax.getChildAt(0) would get the first loader in the queue. myLoaderMax.getChildAt(2) would get the 3rd loader in the queue.

Parameters

index:int — The index of the child in the queue that should be returned. For example, myLoaderMax.getChildAt(0) would get the first loader in the queue. myLoaderMax.getChildAt(2) would get the 3rd loader.

Returns
* — The child loader that is located at the corresponding index

See also

getChildIndex()method 
public function getChildIndex(loader:LoaderCore):uint

Finds the index position of a particular loader in the LoaderMax. Index values are always zero-based, meaning the first position is 0, the second is 1, the third is 2, etc.

Parameters

loader:LoaderCore — The loader whose index position should be returned

Returns
uint — The index position of the loader

See also

getChildren()method 
public function getChildren(includeNested:Boolean = false, omitLoaderMaxes:Boolean = false):Array

Returns and array of all child loaders inside the LoaderMax, optionally exposing more deeply nested instances as well (like loaders inside a child LoaderMax instance).

Parameters

includeNested:Boolean (default = false) — If true, loaders that are nested inside child LoaderMax, XMLLoader, or SWFLoader instances will be included in the returned array as well. The default is false.
 
omitLoaderMaxes:Boolean (default = false) — If true, no LoaderMax instances will be returned in the array; only LoaderItems like ImageLoaders, XMLLoaders, SWFLoaders, MP3Loaders, etc. The default is false.

Returns
Array — An array of loaders.

See also

getChildrenByStatus()method 
public function getChildrenByStatus(status:int, includeNested:Boolean = false, omitLoaderMaxes:Boolean = false):Array

Returns and array of child loaders that currently have a particular status. For example, to find all loaders inside the LoaderMax instance that are actively in the process of loading:

loader.getChildrenByStatus(LoaderStatus.LOADING, false);

Parameters

status:int — Status code like LoaderStatus.READY, LoaderStatus.LOADING, LoaderStatus.COMPLETED, LoaderStatus.PAUSED, or LoaderStatus.FAILED.
 
includeNested:Boolean (default = false) — If true, loaders that are nested inside other loaders (like LoaderMax instances or XMLLoaders or SWFLoaders) will be returned in the array.
 
omitLoaderMaxes:Boolean (default = false) — If true, no LoaderMax instances will be returned in the array; only LoaderItems like ImageLoaders, XMLLoaders, SWFLoaders, MP3Loaders, etc. The default is false.

Returns
Array — An array of loaders that match the defined status.

See also

getContent()method 
public function getContent(nameOrURL:String):*

Finds the content of a loader based on its name or url. For example:

var image:Bitmap = queue.getContent("myPhoto1");

Feel free to use the static LoaderMax.getContent() method instead of the instance-based getContent() method because the static one will search ALL loaders (the only exception being loaders in a different security sandbox, like in subloaded swfs from a different domain that didn't have a crossdomain.xml file in place granting permission).

Parameters

nameOrURL:String — The name or url associated with the loader whose content should be found.

Returns
* — The content that was loaded by the loader which varies by the type of loader:
  • ImageLoader - A com.greensock.loading.display.ContentDisplay (a Sprite) which contains the ImageLoader's rawContent (a flash.display.Bitmap unless script access was denied in which case rawContent will be a flash.display.Loader to avoid security errors). For Flex users, you can set LoaderMax.defaultContentDisplay to FlexContentDisplay in which case ImageLoaders, SWFLoaders, and VideoLoaders will return a com.greensock.loading.display.FlexContentDisplay instance instead.
  • SWFLoader - A com.greensock.loading.display.ContentDisplay (a Sprite) which contains the SWFLoader's rawContent (the swf's root DisplayObject unless script access was denied in which case rawContent will be a flash.display.Loader to avoid security errors). For Flex users, you can set LoaderMax.defaultContentDisplay to FlexContentDisplay in which case ImageLoaders, SWFLoaders, and VideoLoaders will return a com.greensock.loading.display.FlexContentDisplay instance instead.
  • VideoLoader - A com.greensock.loading.display.ContentDisplay (a Sprite) which contains the VideoLoader's rawContent (a Video object to which the NetStream was attached). For Flex users, you can set LoaderMax.defaultContentDisplay to FlexContentDisplay in which case ImageLoaders, SWFLoaders, and VideoLoaders will return a com.greensock.loading.display.FlexContentDisplay instance instead.
  • XMLLoader - XML
  • DataLoader
    • String if the DataLoader's format vars property is "text" (the default).
    • flash.utils.ByteArray if the DataLoader's format vars property is "binary".
    • flash.net.URLVariables if the DataLoader's format vars property is "variables".
  • CSSLoader - flash.text.StyleSheet
  • MP3Loader - flash.media.Sound
  • LoaderMax - an array containing the content objects from each of its child loaders.

See also

getContent()method 
public static function getContent(nameOrURL:String):*

Searches ALL loaders to find content based on its name or url. For example:

var image:Bitmap = LoaderMax.getContent("myPhoto1");

Parameters

nameOrURL:String — The name or url associated with the loader whose content should be found.

Returns
* — The content that was loaded by the loader which varies by the type of loader:
  • ImageLoader - A com.greensock.loading.display.ContentDisplay (a Sprite) which contains the ImageLoader's rawContent (a flash.display.Bitmap unless script access was denied in which case rawContent will be a flash.display.Loader to avoid security errors).
  • SWFLoader - A com.greensock.loading.display.ContentDisplay (a Sprite) which contains the SWFLoader's rawContent (the swf's root DisplayObject unless script access was denied in which case rawContent will be a flash.display.Loader to avoid security errors).
  • VideoLoader - A com.greensock.loading.display.ContentDisplay (a Sprite) which contains the VideoLoader's rawContent (a Video object to which the NetStream was attached).
  • XMLLoader - XML
  • DataLoader
    • String if the DataLoader's format vars property is "text" (the default).
    • flash.utils.ByteArray if the DataLoader's format vars property is "binary".
    • flash.net.URLVariables if the DataLoader's format vars property is "variables".
  • CSSLoader - flash.text.StyleSheet
  • MP3Loader - flash.media.Sound
  • LoaderMax - an array containing the content objects from each of its child loaders.
getLoader()method 
public function getLoader(nameOrURL:String):*

Finds a loader based on its name or url. For example:

var loader:ImageLoader = queue.getLoader("myPhoto1");

Feel free to use the static LoaderMax.getLoader() method instead of the instance-based getLoader() method because the static one will search ALL loaders (the only exception being loaders in a different security sandbox, like in subloaded swfs from a different domain that didn't have a crossdomain.xml file in place granting permission).

Parameters

nameOrURL:String — The name or url associated with the loader that should be found.

Returns
* — The loader associated with the name or url.

See also

getLoader()method 
public static function getLoader(nameOrURL:String):*

Searches ALL loaders to find one based on its name or url. For example:

var loader:ImageLoader = LoaderMax.getLoader("myPhoto1") as ImageLoader;

Parameters

nameOrURL:String — The name or url associated with the loader that should be found.

Returns
* — The loader associated with the name or url.
insert()method 
public function insert(loader:LoaderCore, index:uint = 999999999):LoaderCore

Inserts a loader at a particular position in the queue. Index values are zero-based just like arrays. For example, if the LoaderMax has 10 loaders in it already and you want to insert a loader at the 3rd position (index: 2) while moving the others back in the queue (like the way splice() works in arrays), you'd do:

queue.insert( new ImageLoader("img/photo.jpg"), 2);

When a new loader is added to the LoaderMax, the LoaderMax's status changes to LoaderStatus.READY unless it is paused or disposed. If the loader is already in the queue, it will be removed first.

Parameters

loader:LoaderCore — The loader to insert into the queue. It can be any loader (ImageLoader, XMLLoader, SWFLoader, MP3Loader, DataLoader, CSSLoader, another LoaderMax, etc.).
 
index:uint (default = 999999999) — The index position at which the loader should be inserted, exactly like the way splice() works for arrays. Index values are 0-based, so the first position is 0, the second is 1, the third is 2, etc.

Returns
LoaderCore — The loader that was inserted

See also

parse()method 
public static function parse(data:*, vars:Object = null, childrenVars:Object = null):*

Analyzes a url or array of urls and attempts to automatically create the appropriate loader(s) based on file extension(s) in the url(s), returning either an individual loader like an ImageLoader, SWFLoader, XMLLoader, etc or if an array is passed in, a LoaderMax will be returned containing a child for each parsed url (or URLRequest) in the array. Arrays may also contain LoaderCore instances (not just url Strings).

Single loader example:

import com.greensock.loading.*;
import com.greensock.loading.core.*;
import com.greensock.events.LoaderEvent;
 
//activate the necessary loaders so that their file extensions can be recognized (do this once)
LoaderMax.activate([ImageLoader, SWFLoader, XMLLoader]);
//now parse a url and create the correct type of loader (an ImageLoader in this case because the file extension is ".jpg")
var loader:LoaderCore = LoaderMax.parse("../img/photo1.jpg", {name:"parsedLoader", onComplete:completeHandler});
 
//begin loading
loader.load();
 
function completeHandler(event:LoaderEvent):void {
    trace("finished loading " + event.target);
}
 

If an array is passed to the LoaderMax.parse() method, it will create a LoaderMax instance and add the necessary children based on the contents of the array:

Array example:
import com.greensock.loading.*;
import com.greensock.events.LoaderEvent;
 
//activate the necessary loaders so that their file extensions can be recognized (do this once)
LoaderMax.activate([ImageLoader, SWFLoader, XMLLoader, MP3Loader]);
 
var urls:Array = ["img/photo1.jpg","../../xml/data.xml","swf/main.swf","http://www.greensock.com/audio/music.mp3"];
//now parse all of the urls, creating a LoaderMax that contains the correct type of loaders (an ImageLoader, XMLLoader, SWFLoader, and MP3Loader respectively)
var loader:LoaderMax = LoaderMax.parse(urls, {name:"mainQueue", onComplete:completeHandler}) as LoaderMax;
 
//begin loading
loader.load();
 
function completeHandler(event:LoaderEvent):void {
    trace("finished loading " + loader.numChildren + " loaders.");
}
 

Parameters

data:* — A String or an array of Strings (and/or LoaderCore instances and/or URLRequest instances) to parse.
 
vars:Object (default = null) — The vars object to pass the loader's constructor. If data is an array, this vars will be passed to the LoaderMax instance that gets created, and no vars object will be passed to the child loaders that get created.
 
childrenVars:Object (default = null) — The vars object that will be passed to each child loader's constructor (only applicable when the data parameter is an array which means parse() will return a LoaderMax). For example, if you parse() and array of video urls and want autoPlay set to false for all of them, you'd do LoaderMax.parse(["1.flv","2.f4v","3.mp4"], null, {autoPlay:false});.

Returns
* — If data is an array, parse() will return a LoaderMax. Otherwise, it will return the appropriate loader based on the file extension found in the URL. In any case, the object returned will be a LoaderCore object (all LoaderMax loaders extend LoaderCore, so if you need to datatype your object use com.greensock.loading.core.LoaderCore). The return value is typed as " in order to avoid compiler errors when developers forget to cast ther objects like var image:ImageLoader = LoaderMax.parse("photo.jpg") as ImageLoader
prepend()method 
public function prepend(loader:LoaderCore):LoaderCore

Prepends a loader at the beginning of the queue (append() adds the loader to the end whereas prepend() adds it to the beginning).

Parameters

loader:LoaderCore — The loader to prepend to the queue. It can be any loader (ImageLoader, XMLLoader, SWFLoader, MP3Loader, another LoaderMax, etc.).

Returns
LoaderCore — The loader that was prepended.

See also

prependURLs()method 
public function prependURLs(prependText:String, includeNested:Boolean = false):void

Immediately prepends a value to the beginning of each child loader's url. For example, if the "myLoaderMax" instance contains 3 ImageLoaders with the urls "image1.jpg", "image2.jpg", and "image3.jpg" and you'd like to add "http://www.greensock.com/images/" to the beginning of them all, you'd do:

myLoaderMax.prependURLs("http://www.greensock.com/images/", false);

Now the ImageLoader urls would be "http://www.greensock.com/images/image1.jpg", "http://www.greensock.com/images/image2.jpg", and "http://www.greensock.com/images/image3.jpg" respectively.

prependURLs() permanently affects each child loader's url meaning that LoaderMax.getContent("image1.jpg") would not find the loader whose url is now "http://www.greensock.com/images/image1.jpg" (although you could simply use its name instead of its url to find it). It also means that if a single loader has been inserted into multiple LoaderMax instances, its url change affects them all.

prependURLs() only affects loaders that are children of the LoaderMax when the method is called - it does not affect loaders that are inserted later.

prependURLs() does NOT affect any alternateURL values that are defined for each child loader.

Parameters

prependText:String — The String that should be prepended to each child loader
 
includeNested:Boolean (default = false) — If true, loaders nested inside child LoaderMax instances will also be affected. It is false by default.

See also

prioritize()method 
public static function prioritize(nameOrURL:String, loadNow:Boolean = true):LoaderCore

Immediately prioritizes a loader inside any LoaderMax instances that contain it, forcing it to the top position in their queue and optionally calls load() immediately as well. If one of its parent LoaderMax instances is currently loading a different loader, that one will be temporarily cancelled.

By contrast, when load() is called, it doesn't change the loader's position/index in any LoaderMax queues. For example, if a LoaderMax is working on loading the first object in its queue, you can call load() on the 20th item and it will honor your request without changing its index in the queue. prioritize(), however, affects the position in the queue and optionally loads it immediately as well.

So even if your LoaderMax hasn't begun loading yet, you could prioritize(false) a loader and it will rise to the top of all LoaderMax instances to which it belongs, but not start loading yet. If the goal is to load something immediately, you can just use the load() method.

For example, to immediately prioritize the loader named "myPhoto1":

LoaderMax.prioritize("myPhoto1");

Parameters

nameOrURL:String — The name or url associated with the loader that should be prioritized
 
loadNow:Boolean (default = true) — If true (the default), the loader will start loading immediately (otherwise it is simply placed at the top the queue in any LoaderMax instances to which it belongs).

Returns
LoaderCore — The loader that was prioritized. If no loader was found, null is returned.
registerFileType()method 
public static function registerFileType(extensions:String, loaderClass:Class):void

By default, LoaderMax associates certain file extensions with certain types of loaders, like "jpg", "png", and "gif" are associated with ImageLoader and "swf" is associated with SWFLoader so that the LoaderMax.parse() method can recognize and create the appropriate loaders for each URL passed in. If you'd like to associate additional file extensions with certain loader types, you may do so with registerFileType(). For example, to associate "pdf" with BinaryDataLoader, you would do this:

LoaderMax.registerFileType("pdf", BinaryDataLoader);

Then, if you call LoaderMax.parse("file/myFile.pdf"), it would recognize the "pdf" file extension as being associated with BinaryDataLoader and would return a BinaryDataLoader instance accordingly.

There is no reason to use registerFileType() unless you plan on utilizing the parse() method and need it to recognize a extensions that LoaderMax doesn't already recognize by default.

NOTE: Make sure you activate() the various loader types you want LoaderMax to recognize before calling parse() - see the documentation for LoaderMax.activate())

Parameters

extensions:String — The extension (or comma-delimited list of extensions) that should be associated with the loader class, like "zip" or "zip,pdf". Do not include the dot in the extension.
 
loaderClass:Class — The loader class that should be associated with the extension(s), like BinaryDataLoader.

See also

remove()method 
public function remove(loader:LoaderCore):void

Removes a loader from the LoaderMax.

Parameters

loader:LoaderCore — The loader to remove from the LoaderMax

See also

replaceURLText()method 
public function replaceURLText(fromText:String, toText:String, includeNested:Boolean = false):void

Immediately replaces a certain substring in each child loader's url with another string, making it simple to do something like change "{imageDirectory}image1.jpg" to "http://www.greensock.com/images/image1.jpg". For example, if the "myLoaderMax" instance contains 3 ImageLoaders with the urls "{imageDirectory}image1.jpg", "{imageDirectory}image2.jpg", and "{imageDirectory}image3.jpg" and you'd like to replace {imageDirectory} with http://www.greensock.com/images/ you'd do:

myLoaderMax.replaceURLText("{imageDirectory}", "http://www.greensock.com/images/", false);

Now the ImageLoader urls would be "http://www.greensock.com/images/image1.jpg", "http://www.greensock.com/images/image2.jpg", and "http://www.greensock.com/images/image3.jpg" respectively.

replaceURLText() permanently affects each child loader's url meaning that LoaderMax.getContent("image1.jpg") would not find the loader whose url is now "http://www.greensock.com/images/image1.jpg" (although you could simply use its name instead of its url to find it). It also means that if a single loader has been inserted into multiple LoaderMax instances, its url change affects them all.

replaceURLText() only affects loaders that are children of the LoaderMax when the method is called - it does not affect loaders that are inserted later.

replaceURLText() does affect alternateURL values for child loaders.

Parameters

fromText:String — The old String that should be replaced in each child loader.
 
toText:String — The new String that should replace the fromText.
 
includeNested:Boolean (default = false) — If true, loaders nested inside child LoaderMax instances will also be affected. It is false by default.

See also

Event Detail
childCancel Event
Event Object Type: com.greensock.events.LoaderEvent

Dispatched when any child of the LoaderMax instance dispatches a CANCEL event which could occur when another child is prioritized in the queue or when the LoaderMax is canceled while loading the child. CHILD_CANCEL can be dispatched even if the LoaderMax itself isn't in the process of loading (because load() or prioritize() could have been called directly on a child loader)

childComplete Event  
Event Object Type: com.greensock.events.LoaderEvent

Dispatched when any child of the LoaderMax instance completes. So if a LoaderMax contains 5 loaders, the CHILD_COMPLETE event will be dispatched 5 times during the course of the LoaderMax's load. This can occur even if the LoaderMax itself isn't in the process of loading (because load() or prioritize() could have been called directly on a child loader)

childFail Event  
Event Object Type: com.greensock.events.LoaderEvent

Dispatched when any child of the LoaderMax instance fails to load. This occurs even if the LoaderMax itself isn't in the process of loading (because load() or prioritize() could have been called directly on a child loader)

childOpen Event  
Event Object Type: com.greensock.events.LoaderEvent

Dispatched when any child of the LoaderMax instance starts loading. So if a LoaderMax contains 5 loaders, the CHILD_OPEN event will be dispatched 5 times during the course of the LoaderMax's load. This can occur even if the LoaderMax itself isn't in the process of loading (because load() or prioritize() could have been called directly on a child loader)

childProgress Event  
Event Object Type: com.greensock.events.LoaderEvent

Dispatched when any child of the LoaderMax instance dispatches a PROGRESS event. This can occur even if the LoaderMax itself isn't in the process of loading (because load() or prioritize() could have been called directly on a child loader)

httpStatus Event  
Event Object Type: com.greensock.events.LoaderEvent

Dispatched when any child of the LoaderMax instance dispatches an HTTP_STATUS event. This can occur even if the LoaderMax itself isn't in the process of loading (because load() or prioritize() could have been called directly on a child loader)

ioError Event  
Event Object Type: com.greensock.events.LoaderEvent

Dispatched when any child of the LoaderMax instance dispatches an IO_ERROR event. This can occur even if the LoaderMax itself isn't in the process of loading (because load() or prioritize() could have been called directly on a child loader)

scriptAccessDenied Event  
Event Object Type: com.greensock.events.LoaderEvent

Dispatched when any child of the LoaderMax instance dispatches a SCRIPT_ACCESS_DENIED event. This can occur even if the LoaderMax itself isn't in the process of loading (because load() or prioritize() could have been called directly on a child loader)

securityError Event  
Event Object Type: com.greensock.events.LoaderEvent

Dispatched when any child of the LoaderMax instance dispatches a SECURITY_ERROR event. This can occur even if the LoaderMax itself isn't in the process of loading (because load() or prioritize() could have been called directly on a child loader)