An Applet and the Code

In this simple example, we show how to use the Loader class to load an image at runtime. We show how to instantiate the Loader class, add all the necessary listeners, and display load progress. We happen to load a jpeg file, but you can use the same code to load an external swf file.

Download

The code in the source file is exhaustively commented.

The Code

We load an image called space2.jpg. The image file is located in the same directory as the fla file for the applet, htimgload.fla, but more importantly, the image file will be located in the same directory on the server as the swf and html files corresponding to this applet. That is why, within 'doLoad' function, we pass the local address "space2.jpg" to the URLRequest. If the file is not in the same directory, you pass the corresponding local address of your image file on your server to the URLRequest. Loading from remote domains may cause Flash Player security errors. We do not try to catch security errors in this How-To.

In htimgload.fla, we created on the Stage some static text and a dynamic TextField with the instance name 'infoBox'. In this field, we display messages to the user about loading. We also created on the Stage a button with the instance name 'btnLoad'.

Now, on to the code. We create an instance of the AS3 Loader class and store the instance in a variable called, in our case, 'loader'. The simplest way to add loaded content to the Display List, is to add 'loader' itself to the Display List. We make it a child of the MainTimeline ('this' stands for the MainTimeline.)

 

var loader:Loader =new Loader();

this.addChild(loader);

loader.x=65;

loader.y=50;

 

//Note: listeners are added to the contentLoaderInfo property of 'loader'

//and not to 'loader' itself.

 

loader.contentLoaderInfo.addEventListener(Event.COMPLETE,doneLoad);

 

//If you don't expect loading errors and do not care to display

//loading progress, you don't need the next two listeners.

 

loader.contentLoaderInfo.addEventListener(IOErrorEvent.IO_ERROR,loadingError);

loader.contentLoaderInfo.addEventListener(ProgressEvent.PROGRESS,updateInfo);

 

btnLoad.addEventListener(MouseEvent.CLICK,doLoad);

infoBox.text="Click the arrow button to load an image.";

 

//Since we load only one image, we remove the button's listener and make

//the button invisible when loading begins.

 

function doLoad(e:MouseEvent):void {

loader.load(new URLRequest("space2.jpg"));

infoBox.text="Loading starts...";

btnLoad.removeEventListener(MouseEvent.CLICK,doLoad);

btnLoad.visible=false;

}

 

function updateInfo(e:ProgressEvent):void {

infoBox.text="Loading: "+String(Math.floor(e.bytesLoaded/1024))+" KB of "+String(Math.floor(e.bytesTotal/1024))+" KB.";

}

 

function loadingError(e:IOErrorEvent):void {

infoBox.text="There has been an error loading the image. The server may be busy. Refresh the page and try again.";

}

 

function doneLoad(e:Event):void {

loader.contentLoaderInfo.removeEventListener(Event.COMPLETE,doneLoad);

loader.contentLoaderInfo.removeEventListener(ProgressEvent.PROGRESS,updateInfo);

loader.contentLoaderInfo.removeEventListener(IOErrorEvent.IO_ERROR,loadingError);

infoBox.text="";

infoBox.visible=false;

}

 

An Alternative to Adding Loader to the Display List

Instead of adding our 'loader' to the Display List as we did above, you may want to extract its content; that is, the downloaded Bitmap, and add the Bitmap as a child of, say, the MainTimeline. Extracting downloded content is especially important if you want to process that content. For example, if you want to access the pixel information of the downloaded Bitmap. If that is what you want, the alternative code looks as follows. Delete the lines:

this.addChild(loader);

loader.x=65;

loader.y=50;

Instead declare a global variable, say, 'image':

var image:Bitmap;

Then change the 'doneLoad' function as follows:

 

function doneLoad(e:Event):void {

image=Bitmap(loader.content);

this.addChild(image);

image.x=65;

image.y=50;

loader.contentLoaderInfo.removeEventListener(Event.COMPLETE,doneLoad);

loader.contentLoaderInfo.removeEventListener(ProgressEvent.PROGRESS,updateInfo);

loader.contentLoaderInfo.removeEventListener(IOErrorEvent.IO_ERROR,loadingError);

infoBox.text="";

infoBox.visible=false;

loader=null;

}

 

You can now manipulate the downloaded Bitmap as you like.

Comments

In this applet, we load just one image. In another 'AS3 How-To' item: How To Load a Sequence of Images at Runtime in AS3, we show how to load a sequence of images at consecutive clicks of the button.

In the example presented here, we place the code on the Timeline of our fla file. If you'd like to know how the code would look like placed in a Document Class, and what AS3 classes would then need to be imported explicitly check out: How To Find the AS3 Classes that Must be Imported in a Custom AS3 Class. In the latter How-To, we use the example whose functionality is the same as here.

If you want to load many images concurrently rather than consecutively, we recommend our custom ImageLoader classs: 3D Menu on a Cube with Perspective.

For comments on Flash Player security see: 3D Card Flips with Tweens in Flash CS4 and CS3.

The image of the outer space that you see in the applet above is courtesy of NASA: NASA multimedia collection.

Back to AS3 How To and Tips              Back to Flash and Math Home

We welcome your comments, suggestions, and contributions. Click the Contact Us link below and email one of us.

Adobe®, Flash®, ActionScript®, Flex® are registered trademarks of Adobe Systems Incorporated.