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
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, GreenSock. All rights reserved. This work is subject to the terms in http://www.greensock.com/terms_of_use.html or for corporate Club GreenSock members, the software agreement that was issued with the corporate membership.

See also

com.greensock.loading.data.LoaderMaxVars


Public Properties
 PropertyDefined by
  auditedSize : Boolean
[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
 InheritedbytesLoaded : uint
Bytes loaded
LoaderCore
 InheritedbytesTotal : uint
Total bytes that are to be loaded by the loader.
LoaderCore
  content : *
[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
  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
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
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
[read-only] Integer code indicating the loader's status; options are LoaderStatus.READY, LoaderStatus.LOADING, LoaderStatus.COMPLETE, 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
LoaderCore
  
Appends a loader to the end of the queue.
LoaderMax
  
auditSize():void
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
  
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):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
  
getLoader(nameOrURL:String):*
Finds a loader 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
  
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
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
Events
 EventSummaryDefined by
 Inherited Dispatched 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
 Inherited Dispatched when the loader completes.LoaderCore
 Inherited Dispatched when the loader experiences some type of error, like a SECURITY_ERROR or IO_ERROR.LoaderCore
 Inherited Dispatched 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
 Inherited Dispatched when the loader starts loading.LoaderCore
 Inherited Dispatched 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
Property detail
auditedSizeproperty
auditedSize:Boolean  [read-only]

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

Implementation
    public function get auditedSize():Boolean
contentproperty 
content:*  [read-only]

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.

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]

Integer code indicating the loader's status; options are LoaderStatus.READY, LoaderStatus.LOADING, LoaderStatus.COMPLETE, 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.
  • 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 successfully. 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
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 
public override 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

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):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.COMPLETE, 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.

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

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

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). For example:

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

Example
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.");
}
 

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.
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
childCancelevent 
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)

childCompleteevent  
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)

childFailevent  
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)

childOpenevent  
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)

childProgressevent  
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)

httpStatusevent  
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)

ioErrorevent  
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)

scriptAccessDeniedevent  
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)

securityErrorevent  
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)