One of the improvements made in AS3 is how you load external content into your application. Some of the new changes make it easier for you to initiate and measure the progress of a download - something which was always a bit of a challenge in the AS2 world.

In this article, I will describe how to load an external image into a movie clip in a Flash CS3 application. The following is an example of what you will create towards the end of this tutorial:

[ picture taken from the city formerly known as kirupaVille! ]

In the above example, when you run, an image stored in the same folder as the SWF is loaded and displayed. I know it is hard to see that, but don't worry, for you will be able to display this very quickly on your own computer very quickly.

Let's Get Started

The following steps will help you create a small application that loads an image file from an external location:

1. First, create a new Flash CS3 application and save this application as loadimage.
   
   For this article, the size of your stage, the background color, etc. are not that important, so feel free to leave everything at the default settings if you want.
2. Let's add a movie clip that will host your loaded image. Go to Insert | New Symbol or press Ctrl + F8 to display the Create New Symbol dialog. From this dialog, give your new symbol the name ImageClip and make sure the Movie Clip option is selected:

[ create a new Movie Clip called ImageClip ]

Once everything is set, press OK to close this dialog and to create your new ImageClip movie clip symbol.

3. You will now be in the editing view for your newly created ImageClip. We really don't want to do anything to this clip, so exit out of ImageClip and return to Scene 1 by clicking the Scene 1 link in the navigation bar:

[ click on Scene 1 to go back to your main scene ]

4. You should be back in your main Scene 1 view. Now, we created new ImageClip symbol, but we haven't actually added it to our scene. From the Library, drag and drop your ImageClip movie clip into your scene:

[ insert your ImageClip movie into your main scene ]

Once you have inserted ImageClip into your scene, you shouldn't see anything outside of the little circle representing your empty movie clip:

[ an empty movie clip is represented by a hollow circle ]

5. Make sure the hollow circle representing ImageClip is selected, and from the Properties panel, give your selected ImageClip instance the name imageArea:

[ give your movie clip the instance name imageArea ]

All right - you are done with the UI part of this tutorial. In the last five steps, all you really did was create a new empty movie clip that you dragged to your scene and gave it the instance name imageArea. In the next section, let's go further.

In the previous section you added an empty movie clip whose instance name is imageArea to your scene. That movie clip will be responsible for displaying the image you load. Speaking of image...

Finding an Image

Be sure to save an image into the same location as your SWF publish location - by default, the same folder as your FLA. If you can't find an image quickly, feel free to save the following image that I used in my example from kirupaVille:

Getting back to the tutorial, I saved the image as pixelHouses.jpg, and you can find it right along side my loadimage FLA file:

[ save your image in the same folder as your FLA ]

You will see why I am emphasizing saving the image in the same location as your FLA and output when I show you the code.

Adding the Code

The next step is to add some code. Your timeline should have just one layer called Layer 1, and Layer 1 will have just one keyframe. Right click on the keyframe, and from the menu that appears, select Actions:

[ right click on your keyframe and select Actions ]

The Actions window will appear. Inside this window, copy and paste the following code:

var imageLoader:Loader;
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);
}
loadImage("pixelHouses.jpg");
function imageLoaded(e:Event):void {
  // Load Image
  imageArea.addChild(imageLoader);
}
function imageLoading(e:ProgressEvent):void {
  // Use it to get current download progress
  // Hint: You could tie the values to a preloader :)
}

In my above code, notice that I am passing in the name of the image file that I want to load:

var imageLoader:Loader;
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);
}
loadImage("pixelHouses.jpg");
function imageLoaded(e:Event):void {
  // Load Image
  imageArea.addChild(imageLoader);
}
function imageLoading(e:ProgressEvent):void {
  // Use it to get current download progress
  // Hint: You could tie the values to a preloader :)
}

Be sure to change the name of the image file to the one you want to load. Once you have done that, hit Ctrl + Enter (Control | Test Movie), and you will see your image displayed.

 While you are now able to load an external image and display it, the next section is probably more important because it helps you to understand what the code actually does.

In the previous section 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.

---

Just a final word before we wrap up. What you've seen here is freshly baked content without added preservatives, artificial intelligence, ads, and algorithm-driven doodads. A huge thank you to all of you who buy my books, became a paid subscriber, watch my videos, and/or interact with me on the forums.

Your support keeps this site going! 😇