Flash CS3 Documentation

ActionScript 2.0 Language Reference > ActionScript classes > MovieClipLoader > loadClip (MovieClipLoader.loadClip method)

loadClip (MovieClipLoader.loadClip method)

Loads a SWF, JPEG, progressive JPEG, unanimated GIF, or PNG file into a movie clip in Flash Player while the original movie is playing. If you load an animated GIF, only the first frame is displayed. Using this method you can display several SWF files at once and switch between SWF files without loading another HTML document.

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 or later:

• 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:

• 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 9 Security white paper at http://www.adobe.com/go/fp9_0_security
• The Flash Player 8 Security-Related API white paper at http://www.adobe.com/go/fp8_security_apis

Availability: ActionScript 1.0; Flash Player 7 - Support for unanimated GIF files, PNG files, and progressive JPEG files is available as of Flash Player 8.

Parameters

url:String - The absolute or relative URL of the SWF, JPEG, GIF, or PNG file to be loaded. A relative path must be relative to the SWF file at level 0. Absolute URLs must include the protocol reference, such as http:// or file:///. Filenames cannot include disk drive specifications.

target:Object - The target path of a movie clip, or an integer specifying the level in Flash Player into which the movie will be loaded. The target movie clip is replaced by the loaded SWF file or image.

Returns

Boolean - A Boolean value. Returns true if the URL request was sent successfully; otherwise false.

Example

The following example shows how to use the MovieClipLoader.loadClip() method by creating a handler for the onLoadInit event and then making the request.

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.

See also

onLoadInit (MovieClipLoader.onLoadInit event listener)

Flash CS3