API Documentation | All Packages | All Classes | Index | Frames No Frames |
Class LoaderCore

Package | com.greensock.loading.core
Class | public class LoaderCore
Inheritance | LoaderCore flash.events.EventDispatcher
Subclasses | LoaderItem, LoaderMax

Serves as the base class for GreenSock loading tools like `LoaderMax, ImageLoader, XMLLoader, SWFLoader`, etc. There is no reason to use this class on its own. Please see the documentation for the other classes.
Copyright 2011, 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.

Public Properties

| Property | Defined 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. | LoaderCore
|  | 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). | LoaderCore
|  | bytesLoaded : uint [read-only] Bytes loaded | LoaderCore
|  | bytesTotal : uint [read-only] Total bytes that are to be loaded by the loader. | LoaderCore
|  | content : * [read-only] 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). | LoaderCore
|  | loadTime : Number [read-only] The number of seconds that elapsed between when the loader began and when it either completed, failed, or was canceled. | LoaderCore
|  | name : String A name that you use to identify the loader instance. | LoaderCore
|  | paused : 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
|  | progress : Number [read-only] A value between 0 and 1 indicating the overall progress of the loader. | LoaderCore
|  | status : int [read-only] Integer code indicating the loader's status; options are `LoaderStatus.READY, LoaderStatus.LOADING, LoaderStatus.COMPLETED, LoaderStatus.PAUSED,` and `LoaderStatus.DISPOSED`. | LoaderCore
|  | vars : Object An object containing optional configuration details, typically passed through a constructor parameter. | LoaderCore

Public Methods

| Method | Defined by
--- | --- | ---
|  | LoaderCore(vars:Object = null) Constructor | LoaderCore
|  | addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void | LoaderCore
|  | auditSize():void Attempts loading just enough of the content to accurately determine the `bytesTotal` in order to improve the accuracy of the `progress` property. | LoaderCore
|  | 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
|  | dispose(flushContent:Boolean = false):void Disposes of the loader and releases it internally for garbage collection. | LoaderCore
|  | load(flushContent:Boolean = false):void Loads the loader's content, optionally flushing any previously loaded content first. | LoaderCore
|  | pause():void Pauses the loader immediately. | LoaderCore
|  | prioritize(loadNow:Boolean = true):void Immediately prioritizes the loader inside any LoaderMax instances that contain it, forcing it to the top position in their queue and optionally calls `load()` immediately as well. | LoaderCore
|  | resume():void Unpauses the loader and resumes loading immediately. | LoaderCore
|  | toString():String Returns information about the loader, like its type, its `name`, and its `url` (if it has one). | LoaderCore
|  | unload():void Removes any content that was loaded and sets `bytesLoaded` back to zero. | LoaderCore

Events

| Event | Summary | Defined by
--- | --- | --- | ---
|  | cancel | 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
|  | complete | Dispatched when the loader completes. | LoaderCore
|  | error | Dispatched when the loader experiences some type of error, like a SECURITY_ERROR or IO_ERROR. | LoaderCore
|  | fail | Dispatched when the loader fails. | LoaderCore
|  | open | Dispatched when the loader starts loading. | LoaderCore
|  | progress | Dispatched each time the `bytesLoaded` value changes while loading (indicating progress). | LoaderCore
|  | unload | Dispatched 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

auditedSize | property

`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. You can disable this behavior by passing `auditSize:false` through the constructor's `vars` object.

Implementation
`public function get auditedSize():Boolean`

autoDispose | property |

`public var 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`.

bytesLoaded | property |

`bytesLoaded:uint` [read-only]

Bytes loaded

Implementation
`public function get bytesLoaded():uint`

bytesTotal | property |

`bytesTotal:uint` [read-only]

Total bytes that are to be loaded by the loader. Initially, this value is set to the `estimatedBytes` if one was defined in the `vars` object via the constructor, or it defaults to `LoaderMax.defaultEstimatedBytes`. When the loader loads enough of the content to accurately determine the bytesTotal, it will do so automatically.

Implementation
`public function get bytesTotal():uint`

content | property |

`content:*` [read-only]

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.

Implementation
`public function get content():*`

loadTime | property |

`loadTime:Number` [read-only]

The number of seconds that elapsed between when the loader began and when it either completed, failed, or was canceled. You may check a loader's `loadTime` anytime, not just after it completes. For example, you could access this value in an onProgress handler and you'd see it steadily increase as the loader loads and then when it completes, `loadTime` will stop increasing. LoaderMax instances ignore any pauses when calculating this value, so if a LoaderMax begins loading and after 1 second it gets paused, and then 10 seconds later it resumes and takes an additional 14 seconds to complete, its `loadTime` would be 15, not 25.

Implementation
`public function get loadTime():Number`

name | property |

`public var name:String`

A name that you use to identify the loader instance. This name can be fed to the `getLoader()` or `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".

paused | property |

`paused:Boolean` [read-write]

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

Implementation
`public function get paused():Boolean`
`public function set paused(value:Boolean):void`

progress | property |

`progress:Number` [read-only]

A value between 0 and 1 indicating the overall progress of the loader. When nothing has loaded, it will be 0; when it is halfway loaded, `progress` will be 0.5, and when it is fully loaded it will be 1.

Implementation
`public function get progress():Number`

status | property |

`status:int` [read-only]

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`

vars | property |

`public var vars:Object`

An object containing optional configuration details, typically passed through a constructor parameter. For example: `new SWFLoader("assets/file.swf", {name:"swf1", container:this, autoPlay:true, noCache:true})`. See the constructor's documentation for details about what special properties are recognized.

Constructor detail

LoaderCore | () | constructor

`public function LoaderCore(vars:Object = null)`

Constructor

Parameters

| `vars:Object` (default = `null`)`` — An object containing optional parameters like `estimatedBytes, name, autoDispose, onComplete, onProgress, onError`, etc. For example, `{estimatedBytes:2400, name:"myImage1", onComplete:completeHandler}`.

Method detail

addEventListener | () | method

`public override function addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void`

Parameters

| `type:String`
| `listener:Function`
| `useCapture:Boolean` (default = `false`)``
| `priority:int` (default = `0`)``
| `useWeakReference:Boolean` (default = `false`)``

auditSize | () | method |

`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.

cancel | () | method |

`public function 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`. This does NOT pause the loader - it simply halts the progress and it remains eligible for loading by any of its parent LoaderMax instances. A paused loader, however, cannot be loaded by any of its parent LoaderMax instances until you unpause it (by either calling `resume()` or setting its `paused` property to false).

See also

unload()
dispose()

dispose | () | method |

`public function dispose(flushContent:Boolean = false):void`

Disposes of the loader and releases it internally for garbage collection. If it is in the process of loading, it will also be cancelled immediately. By default, `dispose()` does NOT unload its content, but you may set the `flushContent` parameter to `true` in order to flush/unload the `content` as well (in the case of ImageLoaders, SWFLoaders, and VideoLoaders, this will also destroy its ContentDisplay Sprite, removing it from the display list if necessary). When a loader is disposed, all of the listeners that were added through the `vars` object (like `{onComplete:completeHandler, onProgress:progressHandler}`) are removed. If you manually added listeners, though, you should remove those yourself.

Parameters

| `flushContent:Boolean` (default = `false`)`` — If `true`, the loader's `content` will be unloaded as well (`flushContent` is `false` by default). In the case of ImageLoaders, SWFLoaders, and VideoLoaders, their ContentDisplay will also be removed from the display list if necessary when `flushContent` is `true`.

See also

unload()

load | () | method |

`public function load(flushContent:Boolean = false):void`

Loads the loader's content, optionally flushing any previously loaded content first. For example, a LoaderMax may have already loaded 4 out of the 10 loaders in its queue but if you want it to flush the data and start again, set the `flushContent` parameter to `true` (it is `false` by default).

Parameters

| `flushContent:Boolean` (default = `false`)`` — If `true`, any previously loaded content in the loader will be flushed so that it loads again from the beginning. For example, a LoaderMax may have already loaded 4 out of the 10 loaders in its queue but if you want it to flush the data and start again, set the `flushContent` parameter to `true` (it is `false` by default).

pause | () | method |

`public function pause():void`

Pauses the loader immediately. This is the same as setting the `paused` property to `true`. Some loaders may not stop loading immediately in order to work around some garbage collection issues in the Flash Player, but they will stop as soon as possible after calling `pause()`.

prioritize | () | method |

`public function prioritize(loadNow:Boolean = true):void`

Immediately prioritizes the 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.
You may use the static `LoaderMax.prioritize()` method instead and simply pass the name or url of the loader as the first parameter like:
`LoaderMax.prioritize("myLoaderName", true);`

Parameters

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

See also

load()

resume | () | method |

`public function resume():void`

Unpauses the loader and resumes loading immediately.

toString | () | method |

`public override function toString():String`

Returns information about the loader, like its type, its `name`, and its `url` (if it has one).

Returns

| `String`

unload | () | method |

`public function unload():void`

Removes any content that was loaded and sets `bytesLoaded` back to zero. When you `unload()` a LoaderMax instance, it will also call `unload()` on all of its children as well. If the loader is in the process of loading, it will automatically be canceled.

See also

dispose()
Event detail

cancel | event

Event object type: `com.greensock.events.LoaderEvent`

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.

complete | event |

Event object type: `com.greensock.events.LoaderEvent`

Dispatched when the loader completes.

error | event |

Event object type: `com.greensock.events.LoaderEvent`

Dispatched when the loader experiences some type of error, like a SECURITY_ERROR or IO_ERROR.

fail | event |

Event object type: `com.greensock.events.LoaderEvent`

Dispatched when the loader fails.

open | event |

Event object type: `com.greensock.events.LoaderEvent`

Dispatched when the loader starts loading.

progress | event |

Event object type: `com.greensock.events.LoaderEvent`

Dispatched each time the `bytesLoaded` value changes while loading (indicating progress).

unload | event |

Event object type: `com.greensock.events.LoaderEvent`

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