Loading an Asset with the MovieClipLoader API

Flash Player 7 ActionScript introduced the MovieClipLoader class. The actions associated with this class, collectively referred to as the API, or Application Programming Interface, enable you to more easily initiate and monitor the loading of external SWF or image files into a Flash movie file (.swf) at run time. One of the benefits of using the MovieClipLoader class is that you can handle loading errors within your code. For example, it would be good to know if a URL failed to load or if there were other difficulties with loading a particular asset.

In the following steps, you learn how to use a MovieClipLoader object to initiate the loading of an external .swf or image file.

On the CD-ROM

Use the load_image_100.fla document, in the ch28 folder of this book's CD-ROM, as a starting point for this exercise.

Open the load_image_100.fla document, and save it as MovieClipLoader_100.fla.
Select frame 1 of the actions layer, and open the Actions panel (F9). Delete the existing code in the Script pane, and add the code shown in Listing 28-5.

Listing 28-5: An Example of a MovieClipLoader Object at Work
```
 1.  var cbtLoad:mx.controls.Button; 2.  var cbtUnload:mx.controls.Button; 3.  var tImg:TextField; 4.  var mcHolder:MovieClip; 5. 6.  var mcl:MovieClipLoader = new MovieClipLoader(); 7. 8.  var oLoader:Object = new Object(); 9.  oLoader.onLoadError = function(mc:MovieClip, sError:String):Void { 10.    trace("A loading error has occurred: "+ sError); 11. }; 12. oLoader.click = function(oEvent:Object):Void { 13.    var sLabel:String = oEvent.target.label.toLowerCase(); 14.    if(sLabel == "load image"){ 15.       mcl.loadClip(tImg.text, mcHolder); 16.    } else if (sLabel == "unload image"){ 17.       mcl.unloadClip(mcHolder); 18.    } 19. }; 20. 21. mcl.addListener(oLoader); 22. 23. cbtLoad.addEventListener("click", oLoader); 24. cbtUnload.addEventListener("click", oLoader); 
```
In lines 1-4, the data types of existing elements on the Stage are declared. In line 6, a new MovieClipLoader object named mcl is created, using the constructor function of the MovieClipLoader class.

In line 8, a listener object named oLoader is created. This object will receive events that are broadcasted from the mcl object, as well as the Button components you used previously.

In lines 9 through 11, an onLoadError() handler is defined for the oLoader object. This handler is specific to MovieClipLoader listeners. If there is an error during the loading of an external asset via the MovieClipLoader object, mcl, this handler will be invoked. The handler can accept two parameters, the MovieClip instance receiving the loaded asset (mc) and an error message indicating what went wrong with the loading (sError). In our example, on line 10, we simply throw the error message to the Output panel.

In lines 12 through 19, the click() method of the oLoader object is defined. (Note that this is effectively the same oLoader object we used in previous exercises of this chapter.) The oLoader receives events from the cbtLoad and cbtUnload instances (lines 23 and 24). When either Button instance is clicked, the click() handler in lines 12 through 19 is invoked.

In line 21, the oLoader object is added as a bonafide listener of the mcl object. Without this line of code, the mcl object would not know to broadcast events to the oLoader object.

The difference from our previous exercises occurs primarily in line 15: Instead of using the loadMovie() method, the loadClip() method of the MovieClipLoader class is used with the mcl object. loadClip() takes two parameters: the URL of the SWF or image asset to load, and the MovieClip object that will hold the asset.

In line 17, the unloadClip() method of the MovieClipLoader class is used to unload the content from the mcHolder instance.
Save your document, and test it (Ctrl+Enter or z+Enter). Type a valid URL to an image or Flash movie asset, and click the Load Image button. The mcHolder instance will then display the image when it's finished loading. Click the Unload Image button, and type an invalid URL into the text field — just type any gibberish that comes to mind. Click the Load Image button, and the error message from the onLoadError() handler should display in the Output panel. If you load an image or .swf file from a valid URL into the mcHolder instance, you can remove it by clicking the Unload Image button.

On the CD-ROM

You can find the completed document, MovieClipLoader_100.fla, in the ch28 folder of this book's CD-ROM.

While this might not seem to be a revolutionary way to load an external image or .swf file into a Flash movie, there are other reasons why MovieClipLoader objects are useful:

You can queue several load targets. One instance of the MovieClipLoader class can be used to manage the loading of one or more external assets.
You can integrate other components or code with additional methods of the MovieClipLoader class, not shown in this exercise. For example, you can tie a ProgressBar component to a MovieClipLoader object to monitor the downloading of an asset. You'll learn how to do this procedure later in the chapter.
You can program fail-safes into your ActionScript code. In our simple example, we didn't do much with the onLoadError() handler. In your own work, though, you can use the onLoadError() handler to direct the user to alternate content or attempt to load the content from a backup server or to display an alert dialog box.
You can invoke the onLoadComplete() and/or onLoadInit() handlers on a listener of a MovieClipLoader object to perform further operations with the loaded asset or the master Flash movie after loading has finished.

On theCD-ROM

In the ch28 folder of this book's CD-ROM, you can find an example of an onLoadInit() handler that resizes images or .swf files to fit the boundary of the mcHolder instance. This document is named MovieClipLoader_resize_100.fla.