Flash 8 ActionScript 2.0 Language Reference

Class MovieClipLoader

Object

After you issue the MovieClipLoader.loadClip() command, the following events take place in the order listed:

• When the first bytes of the downloaded file have been written to the hard disk, the MovieClipLoader.onLoadStart listener is invoked.
• If you have implemented the MovieClipLoader.onLoadProgress listener, it is invoked during the loading process.
  Note: You can call MovieClipLoader.getProgress() at any time during the load process.
• When the entire downloaded file has been written to the hard disk, the MovieClipLoader.onLoadComplete listener is invoked.
• When the downloaded file's first frame actions have been executed, the MovieClipLoader.onLoadInit listener is invoked.

When MovieClipLoader.onLoadInit has been invoked, you can set properties, use methods, and otherwise interact with the loaded movie.

If the file fails to load completely, the MovieClipLoader.onLoadError listener is invoked.

onLoadComplete Event Listener

public onLoadComplete = function([target_mc:MovieClip], [httpStatus:Number]) {}

In Flash Player 8, this listener can return an HTTP status code. If Flash Player cannot get the status code from the server, or if Flash Player cannot communicate with the server, the default value of 0 is passed to your ActionScript code. A value of 0 can be generated in any player (for example, if a malformed URL is requested), and a value of 0 is always generated by the Flash Player plug-in when run in the following browsers, which cannot pass HTTP status codes from the server to Flash Player: Netscape, Mozilla, Safari, Opera, and Internet Explorer for the Macintosh.

It's important to understand the difference between MovieClipLoader.onLoadComplete and MovieClipLoader.onLoadInit. The onLoadComplete event is called after the SWF, JPEG, GIF, or PNG file loads, but before the application is initialized. At this point, it is impossible to access the loaded movie clip's methods and properties, and therefore you cannot call a function, move to a specific frame, and so on. In most situations, it's better to use the onLoadInit event instead, which is called after the content is loaded and fully initialized.

var loadListener:Object = new Object();

loadListener.onLoadComplete = function(target_mc:MovieClip, httpStatus:Number):Void {
    trace(">> loadListener.onLoadComplete()");
    trace(">> =============================");
    trace(">> target_mc._width: " + target_mc._width);    // 0
    trace(">> httpStatus: " + httpStatus);
}

loadListener.onLoadInit = function(target_mc:MovieClip):Void {
    trace(">> loadListener.onLoadInit()");
    trace(">> =============================");
    trace(">> target_mc._width: " + target_mc._width);    // 315
}

var mcLoader:MovieClipLoader = new MovieClipLoader();
mcLoader.addListener(loadListener);

var mc:MovieClip = this.createEmptyMovieClip("mc", this.getNextHighestDepth());
mcLoader.loadClip("http://www.w3.org/Icons/w3c_main.png", mc);

If your SWF file includes a version 2 component, use the version 2 component's DepthManager class instead of the MovieClip.getNextHighestDepth() method, which is used in this example.

onLoadError Event Listener

public onLoadError = function(target_mc:MovieClip, errorCode:String, [httpStatus:Number]) {}

Call this listener on a listener object that you add by using MovieClipLoader.addListener().

The value of target_mc identifies the movie clip for which this call is being made. This parameter is useful if you are loading multiple files with the same set of listeners.

For the errorCode parameter, the string "URLNotFound" is returned if neither the MovieClipLoader.onLoadStart or MovieClipLoader.onLoadComplete listener has been called; for example, if a server is down or the file is not found. The string "LoadNeverCompleted" is returned if MovieClipLoader.onLoadStart was called but MovieClipLoader.onLoadComplete was not called; for example, if the download was interrupted because of server overload, server crash, and so on.

In Flash Player 8, this listener can return an HTTP status code in the httpStatus parameter. If Flash Player cannot get a status code from the server, or if Flash Player cannot communicate with the server, the default value of 0 is passed to your ActionScript code. A value of 0 can be generated in any player (for example, if a malformed URL is requested), and a value of 0 is always generated by the Flash Player plug-in when run in the following browsers, which cannot pass HTTP status codes from the server to Flash Player: Netscape, Mozilla, Safari, Opera, and Internet Explorer for the Macintosh. A value of 0 can also be generated if the player did not try to make the URL request to perform the load operation. This can happen because the request violates security sandbox rules for the SWF file.

var loadListener:Object = new Object();

loadListener.onLoadError = function(target_mc:MovieClip, errorCode:String, httpStatus:Number) {
    trace(">> loadListener.onLoadError()");
    trace(">> ==========================");
    trace(">> errorCode: " + errorCode);
    trace(">> httpStatus: " + httpStatus);
}

var mcLoader:MovieClipLoader = new MovieClipLoader();
mcLoader.addListener(loadListener);

var mc:MovieClip = this.createEmptyMovieClip("mc", this.getNextHighestDepth());
mcLoader.loadClip("http://www.fakedomain.com/images/bad_hair_day.jpg", mc);     

If your SWF file includes a version 2 component, use the version 2 component's DepthManager class instead of the MovieClip.getNextHighestDepth() method, which is used in this example.

onLoadInit Event Listener

public onLoadInit = function([target_mc:MovieClip]) {}

The value for target_mc identifies the movie clip for which this call is being made. This parameter is useful if you are loading multiple files with the same set of listeners.

this.createEmptyMovieClip("image_mc", this.getNextHighestDepth());
var mclListener:Object = new Object();
mclListener.onLoadStart = function(target_mc:MovieClip) {
    target_mc.startTimer = getTimer();
};
mclListener.onLoadComplete = function(target_mc:MovieClip) {
    target_mc.completeTimer = getTimer();
};
mclListener.onLoadInit = function(target_mc:MovieClip) {
    var timerMS:Number = target_mc.completeTimer-target_mc.startTimer;
    target_mc.createTextField("timer_txt", target_mc.getNextHighestDepth(), 0, target_mc._height, 
target_mc._width, 22);
    target_mc.timer_txt.text = "loaded in "+timerMS+" ms.";
};
var image_mcl:MovieClipLoader = new MovieClipLoader();
image_mcl.addListener(mclListener);
image_mcl.loadClip("http://www.helpexamples.com/flash/images/image1.jpg", image_mc);

The following example checks whether a movie has loaded into a movie clip created at runtime. The URL used in this example is for demonstration purposes only; replace it with your own valid URL.

this.createEmptyMovieClip("tester_mc", 1);
var mclListener:Object = new Object();
mclListener.onLoadInit = function(target_mc:MovieClip) {
    trace("movie loaded");
}
var image_mcl:MovieClipLoader = new MovieClipLoader();
image_mcl.addListener(mclListener);
image_mcl.loadClip("http://www.yourserver.com/your_movie.swf", tester_mc);

If your SWF file includes a version 2 component, use the version 2 component's DepthManager class instead of the MovieClip.getNextHighestDepth() method, which is used in this example.

onLoadProgress Event Listener

public onLoadProgress = function([target_mc:MovieClip], loadedBytes:Number, totalBytes:Number) {}

The value for target_mc identifies the movie clip for which this call is being made. This is useful when you are loading multiple files with the same set of listeners.

Note: If you attempt to use onLoadProgress in test mode with a local file that resides on your hard disk, it does not work properly because, in test mode, Flash Player loads local files in their entirety.

var container:MovieClip = this.createEmptyMovieClip("container", this.getNextHighestDepth());
var mcLoader:MovieClipLoader = new MovieClipLoader();
var listener:Object = new Object();
listener.onLoadProgress = function(target:MovieClip, bytesLoaded:Number, bytesTotal:Number):Void {
    trace(target + ".onLoadProgress with " + bytesLoaded + " bytes of " + bytesTotal);
}
listener.onLoadInit = function(target:MovieClip):Void {
    trace(target + ".onLoadInit");
}
mcLoader.addListener(listener);
mcLoader.loadClip("http://www.w3.org/Icons/w3c_main.png", container);

If your SWF file includes a version 2 component, use the version 2 component's DepthManager class instead of the MovieClip.getNextHighestDepth() method, which is used in this example.

onLoadStart Event Listener

public onLoadStart = function([target_mc:MovieClip]) {}

The value for target_mc identifies the movie clip for which this call is being made. This parameter is useful if you are loading multiple files with the same set of listeners.

this.createEmptyMovieClip("image_mc", this.getNextHighestDepth());
var mclListener:Object = new Object();
mclListener.onLoadStart = function(target_mc:MovieClip) {
    target_mc.startTimer = getTimer();
};
mclListener.onLoadComplete = function(target_mc:MovieClip) {
    target_mc.completeTimer = getTimer();
};
mclListener.onLoadInit = function(target_mc:MovieClip) {
    var timerMS:Number = target_mc.completeTimer-target_mc.startTimer;
    target_mc.createTextField("timer_txt", target_mc.getNextHighestDepth(), 0, target_mc._height, 
target_mc._width, 22);
    target_mc.timer_txt.text = "loaded in "+timerMS+" ms.";
};
var image_mcl:MovieClipLoader = new MovieClipLoader();
image_mcl.addListener(mclListener);
image_mcl.loadClip("http://www.helpexamples.com/flash/images/image1.jpg", image_mc);

If your SWF file includes a version 2 component, use the version 2 component's DepthManager class instead of the MovieClip.getNextHighestDepth() method, which is used in this example.

MovieClipLoader Constructor

public MovieClipLoader()

addListener Method

public addListener(listener:Object) : Boolean

this.createEmptyMovieClip("image_mc", this.getNextHighestDepth());
var mclListener:Object = new Object();
mclListener.onLoadInit = function(target_mc:MovieClip) {
    target_mc._x = Stage.width/2-target_mc._width/2;
    target_mc._y = Stage.height/2-target_mc._width/2;
    var w:Number = target_mc._width;
    var h:Number = target_mc._height;
    target_mc.lineStyle(4, 0x000000);
    target_mc.moveTo(0, 0);
    target_mc.lineTo(w, 0);
    target_mc.lineTo(w, h);
    target_mc.lineTo(0, h);
    target_mc.lineTo(0, 0);
    target_mc._rotation = 3;
};
var image_mcl:MovieClipLoader = new MovieClipLoader();
image_mcl.addListener(mclListener);
image_mcl.loadClip("http://www.helpexamples.com/flash/images/image1.jpg", image_mc);

If your SWF file includes a version 2 component, use the version 2 component's DepthManager class instead of the MovieClip.getNextHighestDepth() method, which is used in this example.

getProgress Method

public getProgress(target:Object) : Object

var container:MovieClip = this.createEmptyMovieClip("container", this.getNextHighestDepth());
var image:MovieClip = container.createEmptyMovieClip("image", container.getNextHighestDepth());

var mcLoader:MovieClipLoader = new MovieClipLoader();
var listener:Object = new Object();
listener.onLoadProgress = function(target:MovieClip, bytesLoaded:Number, bytesTotal:Number):Void {
    trace(target + ".onLoadProgress with " + bytesLoaded + " bytes of " + bytesTotal);            
}
mcLoader.addListener(listener);
mcLoader.loadClip("http://www.w3.org/Icons/w3c_main.png", image);

var interval:Object = new Object();
interval.id = setInterval(checkProgress, 100, mcLoader, image, interval);

function checkProgress(mcLoader:MovieClipLoader, image:MovieClip, interval:Object):Void {
    trace(">> checking progress now with : " + interval.id);
    var progress:Object = mcLoader.getProgress(image);
    trace("bytesLoaded: " + progress.bytesLoaded + " bytesTotal: " + progress.bytesTotal);
    if(progress.bytesLoaded == progress.bytesTotal) {
        clearInterval(interval.id);
    }
}

If your SWF file includes a version 2 component, use the version 2 component's DepthManager class instead of the MovieClip.getNextHighestDepth() method, which is used in this example.

loadClip Method

public loadClip(url:String, target:Object) : Boolean

Using the loadClip() method instead of loadMovie() or MovieClip.loadMovie() has a number of advantages. The following handlers are implemented by the use of a listener object. You activate the listener by registering it with the MovieClipLoader class by using MovieClipLoader.addListener(listenerObject).

• The MovieClipLoader.onLoadStart handler is invoked when loading begins.
• The MovieClipLoader.onLoadError handler is invoked if the clip cannot be loaded.
• The MovieClipLoader.onLoadProgress handler is invoked as the loading process progresses.
• The MovieClipLoader.onLoadComplete handler is invoked when a file completes downloading, but before the loaded movie clip's methods and properties are available. This handler is called before the onLoadInit handler.
• The MovieClipLoader.onLoadInit handler is invoked after the actions in the first frame of the clip have executed, so you can begin manipulating the loaded clip. This handler is called after the onLoadComplete handler. For most purposes, use the onLoadInit handler.

A SWF file or image loaded into a movie clip inherits the position, rotation, and scale properties of the movie clip. You can use the target path of the movie clip to target the loaded movie.

You can use the loadClip() method to load one or more files into a single movie clip or level; MovieClipLoader listener objects are passed to the loading target movie clip instance as parameters. Alternatively, you can create a different MovieClipLoader object for each file that you load.

Use MovieClipLoader.unloadClip() to remove movies or images loaded with this method or to cancel a load operation that is in progress.

MovieClipLoader.getProgress() and MovieClipLoaderListener.onLoadProgress do not report the actual bytesLoaded and bytesTotal values in the authoring player when the files are local. When you use the Bandwidth Profiler feature in the authoring environment, MovieClipLoader.getProgress() and MovieClipLoaderListener.onLoadProgress report the download at the actual download rate, not at the reduced bandwidth rate that the Bandwidth Profiler provides.

When using this method, consider the Flash Player security model.

For Flash Player 8:

• Loading is not allowed if the calling movie clip is in the local-with-file-system sandbox and the loaded movie clip is from a network sandbox.
• Loading is not allowed if the calling SWF file is in a network sandbox and the movie clip to be loaded is local.
• Network sandbox access from the local-trusted or local-with-networking sandbox requires permission from the website by means of a cross-domain policy file.
• Movie clips in the local-with-file-system sandbox may not script movie clips in the local-with-networking sandbox (and the reverse is also prevented).

For Flash Player 7 and later:

• Websites can permit cross-domain access to a resource by means of a cross-domain policy file.
• Scripting between SWF files is restricted based on the origin domain of the SWF files. Use the System.security.allowDomain() method to adjust these restrictions.

For more information, see the following:

• "Understanding Security" in Learning ActionScript 2.0 in Flash
• The Flash Player 8 Security white paper at http://www.macromedia.com/go/fp8_security
• The Flash Player 8 Security-Related API white paper at http://www.macromedia.com/go/fp8_security_apis

You should either place the following code directly into a frame action on a Timeline, or paste it into a class that extends MovieClip. This code also expects an image named YourImage.jpg to exist in the same directory as the compiled SWF file.

var container:MovieClip = createEmptyMovieClip("container", getNextHighestDepth());
var mcLoader:MovieClipLoader = new MovieClipLoader();
mcLoader.addListener(this);
mcLoader.loadClip("YourImage.jpg", container);

function onLoadInit(mc:MovieClip) {
    trace("onLoadInit: " + mc);
}

If your SWF file includes a version 2 component, use the version 2 component's DepthManager class instead of the MovieClip.getNextHighestDepth() method, which is used in this example.

removeListener Method

public removeListener(listener:Object) : Boolean

this.createEmptyMovieClip("image_mc", this.getNextHighestDepth());
var mclListener:Object = new Object();
mclListener.onLoadStart = function(target_mc:MovieClip) {
    trace("\t onLoadStart");
};
mclListener.onLoadComplete = function(target_mc:MovieClip) {
    trace("\t onLoadComplete");
};
mclListener.onLoadError = function(target_mc:MovieClip, errorCode:String) {
    trace("\t onLoadError: "+errorCode);
};
mclListener.onLoadInit = function(target_mc:MovieClip) {
    trace("\t onLoadInit");
    start_button.enabled = true;
    stop_button.enabled = false;
};
var image_mcl:MovieClipLoader = new MovieClipLoader();
//
start_button.clickHandler = function() {
    trace("Starting...");
    start_button.enabled = false;
    stop_button.enabled = true;
    //
    image_mcl.addListener(mclListener);
    image_mcl.loadClip("http://www.helpexamples.com/flash/images/image1.jpg", image_mc);
};
stop_button.clickHandler = function() {
    trace("Stopping...");
    start_button.enabled = true;
    stop_button.enabled = false;
    //
    image_mcl.removeListener(mclListener);
};
stop_button.enabled = false;

If your SWF file includes a version 2 component, use the version 2 component's DepthManager class instead of the MovieClip.getNextHighestDepth() method, which is used in this example.

unloadClip Method

public unloadClip(target:Object) : Boolean

this.createEmptyMovieClip("image_mc", this.getNextHighestDepth());
var mclListener:Object = new Object();
mclListener.onLoadInit = function(target_mc:MovieClip) {
    target_mc._x = 100;
    target_mc._y = 100;
    target_mc.onRelease = function() {
    trace("Unloading clip...");
    trace("\t name: "+target_mc._name);
    trace("\t url:  "+target_mc._url);
    image_mcl.unloadClip(target_mc);
    };
};
var image_mcl:MovieClipLoader = new MovieClipLoader();
image_mcl.addListener(mclListener);
image_mcl.loadClip("http://www.helpexamples.com/flash/images/image1.jpg", image_mc);

If your SWF file includes a version 2 component, use the version 2 component's DepthManager class instead of the MovieClip.getNextHighestDepth() method, which is used in this example.