class openfl.display.Loader extends Sprite

Available on all platforms

The Loader class is used to load SWF files or image(JPG, PNG, or GIF) files. Use the load() method to initiate loading. The loaded display object is added as a child of the Loader object.

Use the URLLoader class to load text or binary data.

The Loader class overrides the following methods that it inherits, because a Loader object can only have one child display object - the display object that it loads. Calling the following methods throws an exception: addChild(), addChildAt(), removeChild(), removeChildAt(), and setChildIndex(). To remove a loaded display object, you must remove the Loader object from its parent DisplayObjectContainer child array.

Note: The ActionScript 2.0 MovieClipLoader and LoadVars classes are not used in ActionScript 3.0. The Loader and URLLoader classes replace them.

When you use the Loader class, consider the Flash Player and Adobe AIR security model:

  • You can load content from any accessible source.
  • Loading is not allowed if the calling SWF file is in a network sandbox and the file to be loaded is local.
  • If the loaded content is a SWF file written with ActionScript 3.0, it cannot be cross-scripted by a SWF file in another security sandbox unless that cross-scripting arrangement was approved through a call to the System.allowDomain() or the System.allowInsecureDomain() method in the loaded content file.
  • If the loaded content is an AVM1 SWF file(written using ActionScript 1.0 or 2.0), it cannot be cross-scripted by an AVM2 SWF file(written using ActionScript 3.0). However, you can communicate between the two SWF files by using the LocalConnection class.
  • If the loaded content is an image, its data cannot be accessed by a SWF file outside of the security sandbox, unless the domain of that SWF file was included in a URL policy file at the origin domain of the image.
  • Movie clips in the local-with-file-system sandbox cannot script movie clips in the local-with-networking sandbox, and the reverse is also prevented.
  • You cannot connect to commonly reserved ports. For a complete list of blocked ports, see "Restricting Networking APIs" in the ActionScript 3.0 Developer's Guide.

However, in AIR, content in the application security sandbox(content installed with the AIR application) are not restricted by these security limitations.

For more information related to security, see the Flash Player Developer Center Topic: Security.

When loading a SWF file from an untrusted source(such as a domain other than that of the Loader object's root SWF file), you may want to define a mask for the Loader object, to prevent the loaded content(which is a child of the Loader object) from drawing to portions of the Stage outside of that mask, as shown in the following code:

Instance Fields

var content:DisplayObject

Contains the root display object of the SWF file or image(JPG, PNG, or GIF) file that was loaded by using the load() or loadBytes() methods.

var contentLoaderInfo:LoaderInfo

Returns a LoaderInfo object corresponding to the object being loaded. LoaderInfo objects are shared between the Loader object and the loaded content object. The LoaderInfo object supplies loading progress information and statistics about the loaded file.

Events related to the load are dispatched by the LoaderInfo object referenced by the contentLoaderInfo property of the Loader object. The contentLoaderInfo property is set to a valid LoaderInfo object, even before the content is loaded, so that you can add event listeners to the object prior to the load.

To detect uncaught errors that happen in a loaded SWF, use the Loader.uncaughtErrorEvents property, not the Loader.contentLoaderInfo.uncaughtErrorEvents property.

function new():Void

Creates a Loader object that you can use to load files, such as SWF, JPEG, GIF, or PNG files. Call the load() method to load the asset as a child of the Loader instance. You can then add the Loader object to the display list(for instance, by using the addChild() method of a DisplayObjectContainer instance). The asset appears on the Stage as it loads.

You can also use a Loader instance "offlist," that is without adding it to a display object container on the display list. In this mode, the Loader instance might be used to load a SWF file that contains additional modules of an application.

To detect when the SWF file is finished loading, you can use the events of the LoaderInfo object associated with the contentLoaderInfo property of the Loader object. At that point, the code in the module SWF file can be executed to initialize and start the module. In the offlist mode, a Loader instance might also be used to load a SWF file that contains components or media assets. Again, you can use the LoaderInfo object event notifications to detect when the components are finished loading. At that point, the application can start using the components and media assets in the library of the SWF file by instantiating the ActionScript 3.0 classes that represent those components and assets.

To determine the status of a Loader object, monitor the following events that the LoaderInfo object associated with the contentLoaderInfo property of the Loader object:

  • The open event is dispatched when loading begins.
  • The ioError or securityError event is dispatched if the file cannot be loaded or if an error occured during the load process.
  • The progress event fires continuously while the file is being loaded.
  • The complete event is dispatched when a file completes downloading, but before the loaded movie clip's methods and properties are available.
  • The init event is dispatched after the properties and methods of the loaded SWF file are accessible, so you can begin manipulating the loaded SWF file. This event is dispatched before the complete handler. In streaming SWF files, the init event can occur significantly earlier than the complete event. For most purposes, use the init handler.

function close():Void

Cancels a load() method operation that is currently in progress for the Loader instance.

function load(request:URLRequest, ?context:LoaderContext = null):Void

Loads a SWF, JPEG, progressive JPEG, unanimated GIF, or PNG file into an object that is a child of this Loader object. If you load an animated GIF file, only the first frame is displayed. As the Loader object can contain only a single child, issuing a subsequent load() request terminates the previous request, if still pending, and commences a new load.

Note: In AIR 1.5 and Flash Player 10, the maximum size for a loaded image is 8,191 pixels in width or height, and the total number of pixels cannot exceed 16,777,215 pixels.(So, if an loaded image is 8,191 pixels wide, it can only be 2,048 pixels high.) In Flash Player 9 and earlier and AIR 1.1 and earlier, the limitation is 2,880 pixels in height and 2,880 pixels in width.

A SWF file or image loaded into a Loader object inherits the position, rotation, and scale properties of the parent display objects of the Loader object.

Use the unload() method to remove movies or images loaded with this method, or to cancel a load operation that is in progress.

You can prevent a SWF file from using this method by setting the allowNetworking parameter of the the object and embed tags in the HTML page that contains the SWF content.

When you use this method, consider the Flash Player security model, which is described in the Loader class description.

In Flash Player 10 and later, if you use a multipart Content-Type(for example "multipart/form-data") that contains an upload(indicated by a "filename" parameter in a "content-disposition" header within the POST body), the POST operation is subject to the security rules applied to uploads:

  • The POST operation must be performed in response to a user-initiated action, such as a mouse click or key press.
  • If the POST operation is cross-domain(the POST target is not on the same server as the SWF file that is sending the POST request), the target server must provide a URL policy file that permits cross-domain access.

Also, for any multipart Content-Type, the syntax must be valid (according to the RFC2046 standard). If the syntax appears to be invalid, the POST operation is subject to the security rules applied to uploads.

For more information related to security, see the Flash Player Developer Center Topic: Security.

@event asyncError Dispatched by the contentLoaderInfo object if the LoaderContext.requestedContentParent property has been specified and it is not possible to add the loaded content as a child to the specified DisplayObjectContainer. This could happen if the loaded content is a openfl.display.AVM1Movie or if the addChild() call to the requestedContentParent throws an error. @event complete Dispatched by the contentLoaderInfo object when the file has completed loading. The complete event is always dispatched after the init event. @event httpStatus Dispatched by the contentLoaderInfo object when a network request is made over HTTP and Flash Player can detect the HTTP status code. @event init Dispatched by the contentLoaderInfo object when the properties and methods of the loaded SWF file are accessible. The init event always precedes the complete event. @event ioError Dispatched by the contentLoaderInfo object when an input or output error occurs that causes a load operation to fail. @event open Dispatched by the contentLoaderInfo object when the loading operation starts. @event progress Dispatched by the contentLoaderInfo object as data is received while load operation progresses. @event securityError Dispatched by the contentLoaderInfo object if a SWF file in the local-with-filesystem sandbox attempts to load content in the local-with-networking sandbox, or vice versa. @event securityError Dispatched by the contentLoaderInfo object if the LoaderContext.requestedContentParent property has been specified and the security sandbox of the LoaderContext.requestedContentParent does not have access to the loaded SWF. @event unload Dispatched by the contentLoaderInfo object when a loaded object is removed.

request

The absolute or relative URL of the SWF, JPEG, GIF, or PNG file to be loaded. A relative path must be relative to the main SWF file. Absolute URLs must include the protocol reference, such as http:// or file:///. Filenames cannot include disk drive specifications.

context

A LoaderContext object, which has properties that define the following:

  • Whether or not to check for the existence of a policy file upon loading the object
  • The ApplicationDomain for the loaded object
  • The SecurityDomain for the loaded object
  • The ImageDecodingPolicy for the loaded image object

If the context parameter is not specified or refers to a null object, the loaded content remains in its own security domain.

For complete details, see the description of the properties in the LoaderContext class.

function loadBytes(buffer:ByteArray):Void

Loads from binary data stored in a ByteArray object.

The loadBytes() method is asynchronous. You must wait for the "init" event before accessing the properties of a loaded object.

When you use this method, consider the Flash Player security model, which is described in the Loader class description.

@event asyncError Dispatched by the contentLoaderInfo object if the LoaderContext.requestedContentParent property has been specified and it is not possible to add the loaded content as a child to the specified DisplayObjectContainer. This could happen if the loaded content is a openfl.display.AVM1Movie or if the addChild() call to the requestedContentParent throws an error. @event complete Dispatched by the contentLoaderInfo object when the operation is complete. The complete event is always dispatched after the init event. @event init Dispatched by the contentLoaderInfo object when the properties and methods of the loaded data are accessible. The init event always precedes the complete event. @event ioError Dispatched by the contentLoaderInfo object when the runtime cannot parse the data in the byte array. @event open Dispatched by the contentLoaderInfo object when the operation starts. @event progress Dispatched by the contentLoaderInfo object as data is transfered in memory. @event securityError Dispatched by the contentLoaderInfo object if the LoaderContext.requestedContentParent property has been specified and the security sandbox of the LoaderContext.requestedContentParent does not have access to the loaded SWF. @event unload Dispatched by the contentLoaderInfo object when a loaded object is removed.

bytes

A ByteArray object. The contents of the ByteArray can be any of the file formats supported by the Loader class: SWF, GIF, JPEG, or PNG.

context

A LoaderContext object. Only the applicationDomain property of the LoaderContext object applies; the checkPolicyFile and securityDomain properties of the LoaderContext object do not apply.

If the context parameter is not specified or refers to a null object, the content is loaded into the current security domain - a process referred to as "import loading" in Flash Player security documentation. Specifically, if the loading SWF file trusts the remote SWF by incorporating the remote SWF into its code, then the loading SWF can import it directly into its own security domain.

For more information related to security, see the Flash Player Developer Center Topic: Security.

function unload():Void

Removes a child of this Loader object that was loaded by using the load() method. The property of the associated LoaderInfo object is reset to null. The child is not necessarily destroyed because other objects might have references to it; however, it is no longer a child of the Loader object.

As a best practice, before you unload a child SWF file, you should explicitly close any streams in the child SWF file's objects, such as LocalConnection, NetConnection, NetStream, and Sound objects. Otherwise, audio in the child SWF file might continue to play, even though the child SWF file was unloaded. To close streams in the child SWF file, add an event listener to the child that listens for the unload event. When the parent calls Loader.unload(), the unload event is dispatched to the child. The following code shows how you might do this:

 function closeAllStreams(evt:Event) {
myNetStream.close(); mySound.close(); myNetConnection.close();
myLocalConnection.close(); }
myMovieClip.loaderInfo.addEventListener(Event.UNLOAD,
closeAllStreams);

function unloadAndStop(?gc:Bool = true):Void

Attempts to unload child SWF file contents and stops the execution of commands from loaded SWF files. This method attempts to unload SWF files that were loaded using Loader.load() or Loader.loadBytes() by removing references to EventDispatcher, NetConnection, Timer, Sound, or Video objects of the child SWF file. As a result, the following occurs for the child SWF file and the child SWF file's display list:

  • Sounds are stopped.
  • Stage event listeners are removed.
  • Event listeners for enterFrame, frameConstructed, exitFrame, activate and deactivate are removed.
  • Timers are stopped.
  • Camera and Microphone instances are detached
  • Movie clips are stopped.

gc

Provides a hint to the garbage collector to run on the child SWF objects(true) or not(false). If you are unloading many objects asynchronously, setting the gc paramter to false might improve application performance. However, if the parameter is set to false, media and display objects of the child SWF file might persist in memory after running the unloadAndStop() command.