Loading an External Image - Page 3
       by kirupa  |  19 May 2008

In the previous page you got your application working. Copying and pasting some code is great to quickly get up and running, but it is more important for you to understand why the code works the way it does - which is what this page will do!

Looking at the Code
Let's start right at the top:

var imageLoader:Loader;

In this line, I declare a new object called imageLoader whose type is Loader. The Loader class allows you to load image-based content such as JPG, PNG, and GIF, and it provides a lot of handy methods to make it easy for you to do that. You'll see some of them in our code shortly.

function loadImage(url:String):void {

// Set properties on my Loader object

imageLoader = new Loader();

imageLoader.load(new URLRequest(url));

imageLoader.contentLoaderInfo.addEventListener(ProgressEvent.PROGRESS, imageLoading);

imageLoader.contentLoaderInfo.addEventListener(Event.COMPLETE, imageLoaded);

}

In the next line, I begin our loadImage method. This method takes a url value encoded as a string, and its return type is void. In other words, it doesn't return a value.

function loadImage(url:String):void {

// Set properties on my Loader object

imageLoader = new Loader();

imageLoader.load(new URLRequest(url));

imageLoader.contentLoaderInfo.addEventListener(ProgressEvent.PROGRESS, imageLoading);

imageLoader.contentLoaderInfo.addEventListener(Event.COMPLETE, imageLoaded);

}

The lines of code inside loadImage set properties on our imageLoader object. The first thing I do is initialize my declared imageLoader object as a Loader. Now that my value is initialized, I can start populating some of its properties.

function loadImage(url:String):void {

// Set properties on my Loader object

imageLoader = new Loader();

imageLoader.load(new URLRequest(url));

imageLoader.contentLoaderInfo.addEventListener(ProgressEvent.PROGRESS, imageLoading);

imageLoader.contentLoaderInfo.addEventListener(Event.COMPLETE, imageLoaded);

}

In the next line, I call our imageLoader object's load method. The load method takes a URLRequest object as its argument, so I create a new URLRequest object, and since its constructor accepts a string to create the url request, I pass it our url argument that loadImage takes.

function loadImage(url:String):void {

// Set properties on my Loader object

imageLoader = new Loader();

imageLoader.load(new URLRequest(url));

imageLoader.contentLoaderInfo.addEventListener(ProgressEvent.PROGRESS, imageLoading);

imageLoader.contentLoaderInfo.addEventListener(Event.COMPLETE, imageLoaded);

}

The next two lines are interesting! I am creating two event listeners that call the appropriate event handler when fired. The two events are ProgressEvent.PROGRESS and Event.COMPLETE.

As your image is being downloaded, your Progress event fires each time more of your image downloads. This allows you to have an accurate snapshot of how much of your data has been downloaded and how much more is left. Once all of your data has been downloaded, then your Complete event fires letting you know that.

When an event is fired, an event handler is what gets notified. An event handler is a fancy name for a method. The event handler that gets called for our Progress event is imageLoading, and the event handler that gets called for our Complete event is imageLoaded. The tying up of the event with the event handler is taken care of by addEventListener.

The final thing to note is that I am not calling addEventListener, the method that registers the relationship between your event and event handler, on your imageLoader object itself. Instead, I am adding it to a property called contentLoaderInfo. The reason is that contentLoaderInfo returns a LoaderInfo object that provides you with everything you need to register events. That is something your default Loader object, imageLoader, does not do.

With that, we are done with our loadImage method, and we can proceed to what may be most important line of code inside this app - the one that actually gets everything started.

loadImage("pixelHouses.jpg");

The this line I call the loadImage method and pass it what looks like the filename of our image. Because the image is in the same directory as my FLA and SWF file, I am simply referencing the filename, but it actually is the relative path to the image. If your image was stored in an images folder, your argument to loadImage would be:

loadImage("images/pixelHouses.jpg");

Details aside, it is this call that sets in motion everything else needed to load your image. This call to loadImage sets up your Loader object and the two event listeners that deal with the Progress and Complete events.

function imageLoaded(e:Event):void {

// Load Image

imageArea.addChild(imageLoader);

}

This method is our event handler for the Complete event you had earlier. Notice that it takes for its argument an object of type Event. You don't have to worry about passing in an Event object though, for internally, that value is populated by your Complete event itself.

Anyway, the important line of code is the part where I call the addChild method on our movie clip, imageArea. Notice that the argument I am passing in to our addChild method is our Loader object imageLoader. It is this line of code that is responsible for displaying your loaded image into your imageArea movie clip, and by placing it inside the event handler for the Complete event, we ensure that we display the image only after it has fully downloaded.

function imageLoading(e:ProgressEvent):void {

// Use it to get current download progress

// Hint: You could tie the values to a preloader :)

}

Earlier, we covered the imageLoaded method that is the event handler for the Complete event, and what you see now is the event handler for our Progress event. Each time the progress event fires, this imageLoading method gets called. If you wanted to create a preloader, you would specify that right here. Since that is a bigger topic altogether, I will save that discussion for a later time.

Wrapping it All Up
Phew! That was a lot of work for about ten lines of code. Overall, as you can see, it is pretty straightforward to load an external image into your Flash application. The main thing to do is to create your Loader object and populate its load method with a URLRequest containing the path to the image you want to load.

Your loader object is only responsible for downloading the image into memory, and you can register events on its contentLoaderInfo property to figure out exactly how much of the image has been loaded and also when the image has finished downloading. Once your image has downloaded, you simply call your movie clip's addChild method and pass it your loader object.

1 | 2 | 3