Packageflash.display
Classpublic class LoaderInfo
InheritanceLoaderInfo Inheritance EventDispatcher Inheritance Object

The LoaderInfo class provides information about a loaded SWF file or a loaded image file (JPEG, GIF, or PNG). LoaderInfo objects are available for any display object. The information provided includes load progress, the URLs of the loader and loaded content, the number of bytes total for the media, and the nominal height and width of the media.

You can access LoaderInfo objects in two ways:

The contentLoaderInfo property of a Loader object provides information about the content that the Loader object is loading, whereas the loaderInfo property of a DisplayObject provides information about the root SWF file for that display object.

When you use a Loader object to load a display object (such as a SWF file or a bitmap), the loaderInfo property of the display object is the same as the contentLoaderInfo property of the Loader object (DisplayObject.loaderInfo = Loader.contentLoaderInfo). Because the instance of the main class of the SWF file has no Loader object, the loaderInfo property is the only way to access the LoaderInfo for the instance of the main class of the SWF file.

The following diagram shows the different uses of the LoaderInfo object—for the instance of the main class of the SWF file, for the contentLoaderInfo property of a Loader object, and for the loaderInfo property of a loaded object:

An image of different LoaderInfo situations

When a loading operation is not complete, some properties of the contentLoaderInfo property of a Loader object are not available. You can obtain some properties, such as bytesLoaded, bytesTotal, url, loaderURL, and applicationDomain. When the loaderInfo object dispatches the init event, you can access all properties of the loaderInfo object and the loaded image or SWF file.

Note: All properties of LoaderInfo objects are read-only.

The EventDispatcher.dispatchEvent() method is not applicable to LoaderInfo objects. If you call dispatchEvent() on a LoaderInfo object, an IllegalOperationError exception is thrown.

View the examples

See also

flash.display.Loader
flash.display.Loader.content
flash.display.DisplayObject
flash.display.DisplayObject.loaderInfo
Monitoring loading progress


Public Properties
 PropertyDefined By
  actionScriptVersion : uint
[read-only] The ActionScript version of the loaded SWF file.
LoaderInfo
  applicationDomain : ApplicationDomain
[read-only] When an external SWF file is loaded, all ActionScript 3.0 definitions contained in the loaded class are stored in the applicationDomain property.
LoaderInfo
  bytes : ByteArray
[read-only] The bytes associated with a LoaderInfo object.
LoaderInfo
  bytesLoaded : uint
[read-only] The number of bytes that are loaded for the media.
LoaderInfo
  bytesTotal : uint
[read-only] The number of compressed bytes in the entire media file.
LoaderInfo
  childAllowsParent : Boolean
[read-only] Expresses the trust relationship from content (child) to the Loader (parent).
LoaderInfo
  AIR-only childSandboxBridge : Object
A object that can be set by the loaded content's code to expose properties and methods that can be accessed by code in the Loader object's sandbox.
LoaderInfo
 Inheritedconstructor : Object
A reference to the class object or constructor function for a given object instance.
Object
  content : DisplayObject
[read-only] The loaded object associated with this LoaderInfo object.
LoaderInfo
  contentType : String
[read-only] The MIME type of the loaded file.
LoaderInfo
  frameRate : Number
[read-only] The nominal frame rate, in frames per second, of the loaded SWF file.
LoaderInfo
  height : int
[read-only] The nominal height of the loaded file.
LoaderInfo
  loader : Loader
[read-only] The Loader object associated with this LoaderInfo object.
LoaderInfo
  loaderURL : String
[read-only] The URL of the SWF file that initiated the loading of the media described by this LoaderInfo object.
LoaderInfo
  parameters : Object
[read-only] An object that contains name-value pairs that represent the parameters provided to the loaded SWF file.
LoaderInfo
  parentAllowsChild : Boolean
[read-only] Expresses the trust relationship from Loader (parent) to the content (child).
LoaderInfo
  AIR-only parentSandboxBridge : Object
A object that can be set by code in the Loader object's sandbox to expose properties and methods that can be accessed by the loaded content's code.
LoaderInfo
 Inheritedprototype : Object
[static] A reference to the prototype object of a class or function object.
Object
  sameDomain : Boolean
[read-only] Expresses the domain relationship between the loader and the content: true if they have the same origin domain; false otherwise.
LoaderInfo
  sharedEvents : EventDispatcher
[read-only] An EventDispatcher instance that can be used to exchange events across security boundaries.
LoaderInfo
  swfVersion : uint
[read-only] The file format version of the loaded SWF file.
LoaderInfo
  url : String
[read-only] The URL of the media being loaded.
LoaderInfo
  width : int
[read-only] The nominal width of the loaded content.
LoaderInfo
Public Methods
 MethodDefined By
 Inherited
addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void
Registers an event listener object with an EventDispatcher object so that the listener receives notification of an event.
EventDispatcher
  
[static] Returns the LoaderInfo object associated with a SWF file defined as an object.
LoaderInfo
 Inherited
Checks whether the EventDispatcher object has any listeners registered for a specific type of event.
EventDispatcher
 Inherited
Indicates whether an object has a specified property defined.
Object
 Inherited
Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter.
Object
 Inherited
Indicates whether the specified property exists and is enumerable.
Object
 Inherited
removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void
Removes a listener from the EventDispatcher object.
EventDispatcher
 Inherited
Sets the availability of a dynamic property for loop operations.
Object
 Inherited
Returns the string representation of this object, formatted according to locale-specific conventions.
Object
 Inherited
Returns the string representation of the specified object.
Object
 Inherited
Returns the primitive value of the specified object.
Object
 Inherited
Checks whether an event listener is registered with this EventDispatcher object or any of its ancestors for the specified event type.
EventDispatcher
Events
 Event Summary Defined By
 Inherited[broadcast event] Dispatched when the Flash Player or AIR application gains operating system focus and becomes active.EventDispatcher
  Dispatched when data has loaded successfully.LoaderInfo
 Inherited[broadcast event] Dispatched when the Flash Player or AIR application operating loses system focus and is becoming inactive.EventDispatcher
  Dispatched when a network request is made over HTTP and an HTTP status code can be detected.LoaderInfo
  Dispatched when the properties and methods of a loaded SWF file are accessible and ready for use.LoaderInfo
  Dispatched when an input or output error occurs that causes a load operation to fail.LoaderInfo
  Dispatched when a load operation starts.LoaderInfo
  Dispatched when data is received as the download operation progresses.LoaderInfo
  Dispatched by a LoaderInfo object whenever a loaded object is removed by using the unload() method of the Loader object, or when a second load is performed by the same Loader object and the original content is removed prior to the load beginning.LoaderInfo
Property Detail
actionScriptVersionproperty
actionScriptVersion:uint  [read-only]

The ActionScript version of the loaded SWF file. The language version is specified by using the enumerations in the ActionScriptVersion class, such as ActionScriptVersion.ACTIONSCRIPT2 and ActionScriptVersion.ACTIONSCRIPT3.

Note: This property always has a value of either ActionScriptVersion.ACTIONSCRIPT2 or ActionScriptVersion.ACTIONSCRIPT3. ActionScript 1.0 and 2.0 are both reported as ActionScriptVersion.ACTIONSCRIPT2 (version 2.0). This property only distinguishes ActionScript 1.0 and 2.0 from ActionScript 3.0.



Implementation
    public function get actionScriptVersion():uint

Throws
Error — If the file is not downloaded sufficiently to retrieve the requested information.
 
Error — If the file is not a SWF file.

See also

applicationDomainproperty 
applicationDomain:ApplicationDomain  [read-only]

When an external SWF file is loaded, all ActionScript 3.0 definitions contained in the loaded class are stored in the applicationDomain property.

All code in a SWF file is defined to exist in an application domain. The current application domain is where your main application runs. The system domain contains all application domains, including the current domain and all classes used by Flash Player or Adobe AIR.

All application domains, except the system domain, have an associated parent domain. The parent domain of your main application's applicationDomain is the system domain. Loaded classes are defined only when their parent doesn't already define them. You cannot override a loaded class definition with a newer definition.

For usage examples of application domains, see the "Client System Environment" chapter in Programming ActionScript 3.0.



Implementation
    public function get applicationDomain():ApplicationDomain

Throws
SecurityError — This security sandbox of the caller is not allowed to access this ApplicationDomain.

See also

bytesproperty 
bytes:ByteArray  [read-only]

The bytes associated with a LoaderInfo object.



Implementation
    public function get bytes():ByteArray

Throws
SecurityError — If the object accessing this API is prevented from accessing the loaded object due to security restrictions. This situation can occur, for instance, when a Loader object attempts to access the contentLoaderInfo.content property and it is not granted security permission to access the loaded content.

For more information, see the "Flash Player Security" chapter in Programming ActionScript 3.0.

bytesLoadedproperty 
bytesLoaded:uint  [read-only]

The number of bytes that are loaded for the media. When this number equals the value of bytesTotal, all of the bytes are loaded.



Implementation
    public function get bytesLoaded():uint
bytesTotalproperty 
bytesTotal:uint  [read-only]

The number of compressed bytes in the entire media file.

Before the first progress event is dispatched by this LoaderInfo object's corresponding Loader object, bytesTotal is 0. After the first progress event from the Loader object, bytesTotal reflects the actual number of bytes to be downloaded.



Implementation
    public function get bytesTotal():uint

See also

childAllowsParentproperty 
childAllowsParent:Boolean  [read-only]

Expresses the trust relationship from content (child) to the Loader (parent). If the child has allowed the parent access, true; otherwise, false. This property is set to true if the child object has called the allowDomain() method to grant permission to the parent domain or if a URL policy is loaded at the child domain that grants permission to the parent domain. If child and parent are in the same domain, this property is set to true.

For more information, see the "Flash Player Security" chapter in Programming ActionScript 3.0.



Implementation
    public function get childAllowsParent():Boolean

Throws
Error — Thrown if the file is not downloaded sufficiently to retrieve the requested information.
AIR-only childSandboxBridgeproperty 
childSandboxBridge:Object

A object that can be set by the loaded content's code to expose properties and methods that can be accessed by code in the Loader object's sandbox. This sandbox bridge lets content from a non-application domain have controlled access to scripts in the AIR application sandbox, and vice versa. The sandbox bridge serves as a gateway between the sandboxes, providing explicit interaction between application and non-application security sandboxes.



Implementation
    public function get childSandboxBridge():Object
    public function set childSandboxBridge(value:Object):void

Throws
SecurityError — Only content in the loaded content's sandbox can set this property.

See also

contentproperty 
content:DisplayObject  [read-only]

The loaded object associated with this LoaderInfo object.



Implementation
    public function get content():DisplayObject

Throws
SecurityError — If the object accessing this API is prevented from accessing the loaded object due to security restrictions. This situation can occur, for instance, when a Loader object attempts to access the contentLoaderInfo.content property and it is not granted security permission to access the loaded content.

For more information, see the "Flash Player Security" chapter in Programming ActionScript 3.0.

contentTypeproperty 
contentType:String  [read-only]

The MIME type of the loaded file. The value is null if not enough of the file has loaded in order to determine the type. The following list gives the possible values:



Implementation
    public function get contentType():String
frameRateproperty 
frameRate:Number  [read-only]

The nominal frame rate, in frames per second, of the loaded SWF file. This number is often an integer, but need not be.

This value may differ from the actual frame rate in use. Flash Player or Adobe AIR only uses a single frame rate for all loaded SWF files at any one time, and this frame rate is determined by the nominal frame rate of the main SWF file. Also, the main frame rate may not be able to be achieved, depending on hardware, sound synchronization, and other factors.



Implementation
    public function get frameRate():Number

Throws
Error — If the file is not downloaded sufficiently to retrieve the requested information.
 
Error — If the file is not a SWF file.
heightproperty 
height:int  [read-only]

The nominal height of the loaded file. This value might differ from the actual height at which the content is displayed, since the loaded content or its parent display objects might be scaled.



Implementation
    public function get height():int

Throws
Error — If the file is not downloaded sufficiently to retrieve the requested information.
loaderproperty 
loader:Loader  [read-only]

The Loader object associated with this LoaderInfo object. If this LoaderInfo object is the loaderInfo property of the instance of the main class of the SWF file, no Loader object is associated.



Implementation
    public function get loader():Loader

Throws
SecurityError — If the object accessing this API is prevented from accessing the Loader object because of security restrictions. This can occur, for instance, when a loaded SWF file attempts to access its loaderInfo.loader property and it is not granted security permission to access the loading SWF file.

For more information, see the "Flash Player Security" chapter in Programming ActionScript 3.0.

loaderURLproperty 
loaderURL:String  [read-only]

The URL of the SWF file that initiated the loading of the media described by this LoaderInfo object. For the instance of the main class of the SWF file, this URL is the same as the SWF file's own URL.



Implementation
    public function get loaderURL():String
parametersproperty 
parameters:Object  [read-only]

An object that contains name-value pairs that represent the parameters provided to the loaded SWF file.

You can use a for-in loop to extract all the names and values from the parameters object.

The two sources of parameters are: the query string in the URL of the main SWF file, and the value of the FlashVars HTML parameter (this affects only the main SWF file).

The parameters property replaces the ActionScript 1.0 and 2.0 technique of providing SWF file parameters as properties of the main timeline.

The value of the parameters property is null for Loader objects that contain SWF files that use ActionScript 1.0 or 2.0. It is only non-null for Loader objects that contain SWF files that use ActionScript 3.0.



Implementation
    public function get parameters():Object
parentAllowsChildproperty 
parentAllowsChild:Boolean  [read-only]

Expresses the trust relationship from Loader (parent) to the content (child). If the parent has allowed the child access, true; otherwise, false. This property is set to true if the parent object called the allowDomain() method to grant permission to the child domain or if a URL policy file is loaded at the parent domain granting permission to the child domain. If child and parent are in the same domain, this property is set to true.

For more information, see the "Flash Player Security" chapter in Programming ActionScript 3.0.



Implementation
    public function get parentAllowsChild():Boolean

Throws
Error — Thrown if the file is not downloaded sufficiently to retrieve the requested information.
AIR-only parentSandboxBridgeproperty 
parentSandboxBridge:Object

A object that can be set by code in the Loader object's sandbox to expose properties and methods that can be accessed by the loaded content's code. This sandbox bridge lets content from a non-application domain have controlled access to scripts in the AIR application sandbox, and vice versa. The sandbox bridge serves as a gateway between the sandboxes, providing explicit interaction between application and non-application security sandboxes.



Implementation
    public function get parentSandboxBridge():Object
    public function set parentSandboxBridge(value:Object):void

Throws
SecurityError — Only content in the Loader object's sandbox can set this property.

See also

sameDomainproperty 
sameDomain:Boolean  [read-only]

Expresses the domain relationship between the loader and the content: true if they have the same origin domain; false otherwise.



Implementation
    public function get sameDomain():Boolean

Throws
Error — Thrown if the file is not downloaded sufficiently to retrieve the requested information.
sharedEventsproperty 
sharedEvents:EventDispatcher  [read-only]

An EventDispatcher instance that can be used to exchange events across security boundaries. Even when the Loader object and the loaded content originate from security domains that do not trust one another, both can access sharedEvents and send and receive events via this object.



Implementation
    public function get sharedEvents():EventDispatcher
swfVersionproperty 
swfVersion:uint  [read-only]

The file format version of the loaded SWF file. The file format is specified using the enumerations in the SWFVersion class, such as SWFVersion.FLASH7 and SWFVersion.FLASH9.



Implementation
    public function get swfVersion():uint

Throws
Error — If the file is not downloaded sufficiently to retrieve the requested information.
 
Error — If the file is not a SWF file.

See also

urlproperty 
url:String  [read-only]

The URL of the media being loaded.

Before the first progress event is dispatched by this LoaderInfo object's corresponding Loader object, the value of the url property might reflect only the initial URL specified in the call to the load() method of the Loader object. After the first progress event, the url property reflects the media's final URL, after any redirects and relative URLs are resolved.



Implementation
    public function get url():String

See also

widthproperty 
width:int  [read-only]

The nominal width of the loaded content. This value might differ from the actual width at which the content is displayed, since the loaded content or its parent display objects might be scaled.



Implementation
    public function get width():int

Throws
Error — If the file is not downloaded sufficiently to retrieve the requested information.
Method Detail
getLoaderInfoByDefinition()method
public static function getLoaderInfoByDefinition(object:Object):LoaderInfo

Returns the LoaderInfo object associated with a SWF file defined as an object.

Parameters

object:Object — The object for which you want to get an associated LoaderInfo object.

Returns
LoaderInfo — The associated LoaderInfo object. Returns null when called in non-debugger builds (or when debugging is not enabled) or if the referenced object does not have an associated LoaderInfo object (such as some objects used by the AIR runtime).

Throws
SecurityError — The caller is not running in the local trusted sandbox.
Event Detail
complete Event
Event Object Type: flash.events.Event
property Event.type = flash.events.Event.COMPLETE

Dispatched when data has loaded successfully. In other words, it is dispatched when all the content has been downloaded and the loading has finished. The complete event is always dispatched after the init event. The init event is dispatched when the object is ready to access, though the content may still be downloading.

The Event.COMPLETE constant defines the value of the type property of a complete event object.

This event has the following properties:

PropertyValue
bubblesfalse
cancelablefalse; there is no default behavior to cancel.
currentTargetThe object that is actively processing the Event object with an event listener.
targetThe network object that has completed loading.

See also

httpStatus Event  
Event Object Type: flash.events.HTTPStatusEvent
property HTTPStatusEvent.type = flash.events.HTTPStatusEvent.HTTP_STATUS

Dispatched when a network request is made over HTTP and an HTTP status code can be detected.

The HTTPStatusEvent.HTTP_STATUS constant defines the value of the type property of a httpStatus event object.

This event has the following properties:

PropertyValue
bubblesfalse
cancelablefalse; there is no default behavior to cancel.
currentTargetThe object that is actively processing the Event object with an event listener.
statusThe HTTP status code returned by the server.
targetThe network object receiving an HTTP status code.

See also

init Event  
Event Object Type: flash.events.Event
property Event.type = flash.events.Event.INIT

Dispatched when the properties and methods of a loaded SWF file are accessible and ready for use. The content, however, can still be downloading. A LoaderInfo object dispatches the init event when the following conditions exist:

For example, an Event.INIT is dispatched when the first frame of a movie or animation is loaded. The movie is then accessible and can be added to the display list. The complete movie, however, can take longer to download. The Event.COMPLETE is only dispatched once the full movie is loaded.

The init event always precedes the complete event.

The Event.INIT constant defines the value of the type property of an init event object.

This event has the following properties:

PropertyValue
bubblesfalse
cancelablefalse; there is no default behavior to cancel.
currentTargetThe object that is actively processing the Event object with an event listener.
targetThe LoaderInfo object associated with the SWF file being loaded.

See also

ioError Event  
Event Object Type: flash.events.IOErrorEvent
property IOErrorEvent.type = flash.events.IOErrorEvent.IO_ERROR

Dispatched when an input or output error occurs that causes a load operation to fail.

Defines the value of the type property of an ioError event object.

This event has the following properties:

PropertyValue
bubblesfalse
cancelablefalse; there is no default behavior to cancel.
currentTargetThe object that is actively processing the Event object with an event listener.
errorIDA reference number associated with the specific error (AIR only).
targetThe network object experiencing the input/output error.
textText to be displayed as an error message.

See also

open Event  
Event Object Type: flash.events.Event
property Event.type = flash.events.Event.OPEN

Dispatched when a load operation starts.

The Event.OPEN constant defines the value of the type property of an open event object.

This event has the following properties:

PropertyValue
bubblesfalse
cancelablefalse; there is no default behavior to cancel.
currentTargetThe object that is actively processing the Event object with an event listener.
targetThe network object that has opened a connection.

See also

progress Event  
Event Object Type: flash.events.ProgressEvent
property ProgressEvent.type = flash.events.ProgressEvent.PROGRESS

Dispatched when data is received as the download operation progresses.

Defines the value of the type property of a progress event object.

This event has the following properties:

PropertyValue
bubblesfalse
bytesLoadedThe number of items or bytes loaded at the time the listener processes the event.
bytesTotalThe total number of items or bytes that ultimately will be loaded if the loading process succeeds.
cancelablefalse; there is no default behavior to cancel.
currentTargetThe object that is actively processing the Event object with an event listener.
targetThe object reporting progress.

See also

unload Event  
Event Object Type: flash.events.Event
property Event.type = flash.events.Event.UNLOAD

Dispatched by a LoaderInfo object whenever a loaded object is removed by using the unload() method of the Loader object, or when a second load is performed by the same Loader object and the original content is removed prior to the load beginning.

The Event.UNLOAD constant defines the value of the type property of an unload event object.

This event has the following properties:

PropertyValue
bubblesfalse
cancelablefalse; there is no default behavior to cancel.
currentTargetThe object that is actively processing the Event object with an event listener.
targetThe LoaderInfo object associated with the SWF file being unloaded or replaced.

See also

Examples How to use this example
LoaderInfoExample.as

The following example uses the LoaderInfoExample class to display an image on the stage. This is accomplished by performing the following steps:
  1. A property url is created, which is the location and name of the image.
  2. The class constructor creates a Loader object named loader.
  3. The loader object instantiates an event listener to ensure that the image loads properly.
  4. The constructor creates a new instance of a URLRequest object, request, with url passed so that the file name and location are known.
  5. The request object is then passed to the load() method of the loader object, which loads the image onto the display list.

Important: This example requires that you add a file named Image.gif in the same directory as the compiled SWF file. Use an image that has an area that fits within the dimensions of the main SWF file.

package {
    import flash.display.Loader;
    import flash.display.LoaderInfo;
    import flash.display.Sprite;
    import flash.events.*;
    import flash.net.URLRequest;

    public class LoaderInfoExample extends Sprite {
        private var url:String = "Image.gif";

        public function LoaderInfoExample() {
            var loader:Loader = new Loader();
            loader.contentLoaderInfo.addEventListener(Event.INIT, initHandler);
            loader.contentLoaderInfo.addEventListener(IOErrorEvent.IO_ERROR, ioErrorHandler);
            var request:URLRequest = new URLRequest(url);
            loader.load(request);
            addChild(loader);
        }

        private function initHandler(event:Event):void {
            var loader:Loader = Loader(event.target.loader);
            var info:LoaderInfo = LoaderInfo(loader.contentLoaderInfo);
            trace("initHandler: loaderURL=" + info.loaderURL + " url=" + info.url);
        }

        private function ioErrorHandler(event:IOErrorEvent):void {
            trace("ioErrorHandler: " + event);
        }
    }
}