Loader  - AS3

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.

Related API Elements

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.

Related API Elements

var url:String = "http://www.helpexamples.com/flash/images/image2.jpg";
var urlRequest:URLRequest = new URLRequest(url);
var loader:Loader = new Loader();
loader.contentLoaderInfo.addEventListener(Event.COMPLETE, loader_complete);
loader.load(urlRequest);
addChild(loader);
 
function loader_complete(evt:Event):void {
    var target_mc:Loader = evt.currentTarget.loader as Loader;
    target_mc.x = (stage.stageWidth - target_mc.width) / 2;
    target_mc.y = (stage.stageHeight - target_mc.height) / 2;
}

An object that dispatches an uncaughtError event when an unhandled error occurs in the SWF that's loaded by this Loader object. An uncaught error happens when an error is thrown outside of any try..catch blocks or when an ErrorEvent object is dispatched with no registered listeners.

Note that a Loader object's uncaughtErrorEvents property dispatches events that bubble through it, not events that it dispatches directly. It never dispatches an uncaughtErrorEvent in the target phase. It only dispatches the event in the capture and bubbling phases. To detect an uncaught error in the current SWF (the SWF in which the Loader object is defined) use the LoaderInfo.uncaughtErrorEvents property instead.

If the content loaded by the Loader object is an AVM1 (ActionScript 2) SWF file, uncaught errors in the AVM1 SWF file do not result in an uncaughtError event.

Related API Elements

package
{
    import flash.display.Loader;
    import flash.display.Sprite;
    import flash.events.ErrorEvent;
    import flash.events.UncaughtErrorEvent;
    import flash.net.URLRequest;

    public class LoaderUncaughtErrorEventExample extends Sprite
    {
        private var ldr:Loader;
        
        public function LoaderUncaughtErrorEventExample()
        {
            ldr = new Loader();
            ldr.load(new URLRequest("child.swf"));
            ldr.uncaughtErrorEvents.addEventListener(UncaughtErrorEvent.UNCAUGHT_ERROR, uncaughtErrorHandler);
        }
        
        private function uncaughtErrorHandler(event:UncaughtErrorEvent):void
        {
            if (event.error is Error)
            {
                var error:Error = event.error as Error;
                // do something with the error
            }
            else if (event.error is ErrorEvent)
            {
                var errorEvent:ErrorEvent = event.error as ErrorEvent;
                // do something with the error
            }
            else
            {
                // a non-Error, non-ErrorEvent type was thrown and uncaught
            }
        }
    }
}

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.

Notes (iOS only): In AIR applications on iOS, you can only load a SWF file containing ActionScript from the application package. This restriction includes any ActionScript, such as assets with class names exported for ActionScript. For loading any SWF file, you must load the SWF using the same application domain as the parent SWF.

Prior to AIR 3.6, only SWF files that do not contain ActionScript bytecode can be loaded, regardless of whether they're loaded from the application package or over a network. As an alternative to using an external SWF file with ActionScript, create a SWC library and link it in to your main SWF.

These restrictions do not apply when an application is running in the iOS Simulator (ipa-test-interpreter-simulator or ipa-debug-interpreter-simulator) or interpreter mode (ipa-test-interpreter or ipa-debug-interpreter.)

Related API Elements

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

Related API Elements

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.

iOS notes

In AIR applications on iOS, you can only load a SWF file containing ActionScript from the application package. This restriction includes any ActionScript, such as assets with class names exported for ActionScript. For loading any SWF file, you must load the SWF using the same application domain as the parent SWF, as shown in the following example:

     var loader:Loader = new Loader();
     var url:URLRequest = new URLRequest("swfs/SecondarySwf.swf");
     var loaderContext:LoaderContext = new LoaderContext(false, ApplicationDomain.currentDomain, null);
     loader.load(url, loaderContext);

In addition, on iOS you can't load a SWF file that contains any ActionScript ByteCode (ABC) then unload it and reload it. If you attempt to do this, the runtime throws error 3764.

Prior to AIR 3.6, only SWF files that do not contain ActionScript bytecode can be loaded, regardless of whether they're loaded from the application package or over a network. As an alternative to using an external SWF file with ActionScript, create a SWC library and link it in to your main SWF.

These restrictions do not apply when an application is running in the iOS Simulator (ipa-test-interpreter-simulator or ipa-debug-interpreter-simulator) or interpreter mode (ipa-test-interpreter or ipa-debug-interpreter.)

Loader security

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.

Parameters

More examples

Learn more

Related API Elements

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.

Note (iOS only): In AIR applications on iOS, you can only load a SWF file containing ActionScript from the application package. This restriction includes any ActionScript, such as assets with class names exported for ActionScript. For loading any SWF file, you must load the SWF using the same application domain as the parent SWF.

Prior to AIR 3.6, calling this method has no effect on iOS.

Parameters

Learn more

Related API Elements

Loads an IFilePromise instance.

The loadFilePromise method takes an IFilePromise object and loads the binary data. If the data is a progressive stream, such as a video wait for the "init" or progress events before accessing the properties of the loaded object. Otherwise, wait for the complete event to make sure that the data is fully loaded.

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

Parameters

Related API Elements

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.

When you call the unload() method, the Loader object's contentLoaderInfo property is set to null. Any visual assets that were loaded with the SWF are unloaded and removed from memory. ActionScript class definitions in the loaded SWF remain in memory, and code in the same application domain as the loaded SWF can access instances of those classes and create new instances.

Note (iOS only): Prior to AIR 3.6, this method has no effect on iOS.

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

Related API Elements

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.

When you call the unloadAndStop() method, the Loader object's contentLoaderInfo property is set to null. Any visual assets that were loaded with the SWF are unloaded and removed from memory. ActionScript class definitions in the loaded SWF remain in memory, and code in the same application domain as the loaded SWF can access instances of those classes and create new instances.

Note (iOS only): Prior to AIR 3.6, this method has no effect on iOS.

Parameters

Related API Elements

1. A url property is created, which is the location and name of the image file
2. In the LoaderExample constructor, a new Loader object named loader is created, which is then passed to the configureListeners() method, described in step 3.
3. The constructor creates a new instance of a URLRequest object, request, with url passed so that the file name and location are known.
4. The request object is passed to the loader object's load() method, which loads the image onto the display list.
5. A clickHandler event listener is registered for the click event on the loader. After a mouse click, the loaded image is unloaded.
6. The configureListeners() method adds seven event listeners by using the following methods:
   • The completeHandler() method executes when the image finishes loading.
   • The httpStatusHandler() method executes if the image is not loaded locally and only if the network request is made available and the Flash Player can detect it.
   • The initHandler() method executes before the completeHandler() method and after the progressHandler() method. Generally, the init event is more useful when loading SWF files.
   • The ioErrorHandler() method executes if the image file is not available or not accessible.
   • The openHandler() method executes when the image file is first opened.
   • The progressHandler() method executes when the image file starts to load and again when the image is finished loading.
   • The unLoadHandler() method executes when the image is unloaded by using the unload() method when the user clicks the image.

Keep in mind the following requirements:

• This example requires that you place 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.
• Although this example makes use of all events available to the LoaderInfo object, most situations require only a subset. In particular, when loading only an image file, the complete event (and perhaps the ioError event) are sufficient when loading a local image.

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

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

        public function LoaderExample() {
            var loader:Loader = new Loader();
            configureListeners(loader.contentLoaderInfo);
            loader.addEventListener(MouseEvent.CLICK, clickHandler);

            var request:URLRequest = new URLRequest(url);
            loader.load(request);

            addChild(loader);
        }

        private function configureListeners(dispatcher:IEventDispatcher):void {
            dispatcher.addEventListener(Event.COMPLETE, completeHandler);
            dispatcher.addEventListener(HTTPStatusEvent.HTTP_STATUS, httpStatusHandler);
            dispatcher.addEventListener(Event.INIT, initHandler);
            dispatcher.addEventListener(IOErrorEvent.IO_ERROR, ioErrorHandler);
            dispatcher.addEventListener(Event.OPEN, openHandler);
            dispatcher.addEventListener(ProgressEvent.PROGRESS, progressHandler);
            dispatcher.addEventListener(Event.UNLOAD, unLoadHandler);
        }

        private function completeHandler(event:Event):void {
            trace("completeHandler: " + event);
        }

        private function httpStatusHandler(event:HTTPStatusEvent):void {
            trace("httpStatusHandler: " + event);
        }

        private function initHandler(event:Event):void {
            trace("initHandler: " + event);
        }

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

        private function openHandler(event:Event):void {
            trace("openHandler: " + event);
        }

        private function progressHandler(event:ProgressEvent):void {
            trace("progressHandler: bytesLoaded=" + event.bytesLoaded + " bytesTotal=" + event.bytesTotal);
        }

        private function unLoadHandler(event:Event):void {
            trace("unLoadHandler: " + event);
        }

        private function clickHandler(event:MouseEvent):void {
            trace("clickHandler: " + event);
            var loader:Loader = Loader(event.target);
            loader.unload();
        }
    }
}