| loadMovie( ) Global Function | Flash 4; Flash 6 adds .jpg loading and security restrictions |
| load an external .swf or .jpg file into the Player |
A string specifying the absolute or relative file path of the external .swf movie or .jpg image file to load. All URLs must use forward slashes, and absolute URLs must include the protocol reference (e.g., http:// or file:///). Relative URLs are resolved relative to the URL of the movie on _level0 (i.e., _level0._url) and use the http:// protocol by default.
A string indicating the movie clip or document level that will host the external .swf or .jpg file. Can also be a reference to an existing movie clip or document level (references are converted to paths when used in a string context).
An optional string indicating the method by which to send variables to an external script. The legal values for method are "GET" and "POST". This parameter must be a literal, not a variable or other expression. On Windows, prior to Flash 6, the Standalone Player always used the "GET" method, regardless of the method specified. As of Flash 6, both "GET" and "POST" are supported. See Appendix F.
The loadMovie( ) function is the global analogue of the MovieClip.loadMovie( ) method. Both versions import the .swf movie or .jpg (JPEG) image file located at url into the Flash Player, but the global version uses target to identify the new location of the loaded file, whereas the MovieClip method version always uses the calling movie clip as the target. If url is a JPEG image, it cannot be a .jpg file saved in progressive format.
If target is a reference to an existing movie clip or a string indicating the path to a movie clip, the loaded .swf or .jpg file is placed into the specified clip (causing the eviction of any previous content). To load a movie or image into the current movie clip, use the empty string as the target parameter, as in:
loadMovie("myMovie.swf", "");
or use the MovieClip.loadMovie( ) version with the keyword this:
this.loadMovie("myMovie.swf");
If target is a reference to an existing document level (such as _level2) or a string indicating the path to a document level (such as "_level2"), then the .swf or .jpg file is placed into the specified document level. Loading a movie into _level0 clears the Player of all content on all levels and places the new .swf or .jpg file into _level0.
Note that loadMovie( ) executes asynchronously; the load operation does not actually begin until after all scripts on the current frame execute (specifically, Flash requests the external asset from the operating system just before the screen is updated). Once the .swf or .jpg file begins loading into the Player, download progress can be monitored via MovieClip.getBytesLoaded( ) and MovieClip._framesloaded. For details on preloading movies, see those entries and the following article:
Be careful not to check load progress before loadMovie( ) actually executes. To ensure an accurate progress reading for a loading .swf file, set a flag on its first frame, indicating that loading has started:
var loadStarted = true;
Then, poll for that variable from outside the .swf file before checking load progress:
if (target_mc.loadStarted = = true) {
// It's safe to display accurate load progress...
}
It is possible to send variables along with a loadMovie( ) invocation, in which case url normally is the location of a script that returns a .swf or .jpg file based on the variables sent. To send variables with a loadMovie( ) call, we include the method argument (set to either "GET" or "POST"). "GET" sends the current movie clip timeline variables as a query string attached to the script url. "POST" sends the current movie clip timeline variables after the HTTP POST-request header. Prior to Flash 6, the "POST" method was not available in the Standalone Player, but it is functional in the Flash 6 Standalone Player. Because most web servers restrict the length of URLs to no more than 1024 characters (and some to as little as 255 characters), use "POST" instead of "GET" to transfer larger amounts of data.
A loadMovie( ) invocation that uses the "GET" method can pass variables to a loaded movie without the help of an intervening script, provided the movie is served from a web server and not by the local filesystem. For example, the following code loads the external movie myMovie.swf into level 1 of the Player document stack, passing it the variables from the current timeline:
loadMovie("myMovie.swf", "_level1", "GET");
Variables passed to the loaded movie are defined on its main timeline. This technique works only when the loadMovie( ) request is handled by a web server. Attempts to use the "GET" method with loadMovie( ) using local files will cause an "Error opening URL" error.
As of Flash 6, a movie from one domain can load a movie from another domain but cannot access its variables, properties or functions unless it provides special permission. For full details, see System.security.allowDomain( ).
Be careful when using movie clip and level references as the target argument of loadMovie( ). If a loadMovie( )'s target argument yields undefined or the empty string, the loadMovie( ) function uses the current timeline as its target (i.e., it replaces the current timeline with the newly loaded content). In particular, this causes problems for loading movies onto new, unoccupied levels. Consider the following code:
loadMovie("myMovie.swf", _level1);
If no _level1 object exists prior to the execution of this statement, the code will load myMovie.swf into the timeline that contains the loadMovie( ) statement, not _level1! To avoid the problem, you can use loadMovieNum( ) instead. Alternatively, you can use a string for the target parameter to loadMovie( ), as in:
loadMovie("myMovie.swf", "_level1");
In this case, the level will be created if it doesn't already exist (only _level0 exists by default in all movies). For more information, see Section 13.7.
The global loadMovie( ) function replaces the target path version of Flash 4's Load Movie action.
Here are some loadMovie( ) examples:
loadMovie("myMovie.swf", "_level1"); // Place myMovie.swf on level 1
loadMovie("myMovie.swf", "_level0"); // Place myMovie.swf on level 0
loadMovie("myMovie.swf", "myClip"); // Place myMovie.swf into myClip
// Replace the contents of the Player with coolmovie.swf, using an absolute path
loadMovie("http://www.yourflashsite.com/coolmovie.swf", "_level0");
// Load a movie into level 1 from the Windows desktop. Note the
// file:/// protocol and the forward slashes.
loadMovie("file:///C|/WINDOWS/Desktop/animation.swf", "_level1");
// Load a JPEG image into imageHolder_mc
loadMovie("photo.jpg", "_level0.imageHolder_mc");
The following code loads a .jpg file into a movie for use as a button. It first creates a clip to act as the button, then creates a clip inside that clip to act as the image holder. Note the clip nesting. If onRelease( ) were attached to the image holder clip rather than the outer button clip, it would be deleted by the loading .jpg file.
this.createEmptyMovieClip("btn_mc", 1);
this.btn_mc.createEmptyMovieClip("imgHolder_mc", 1);
this.btn_mc.onRelease = function () {
trace("Image clicked");
}
this.btn_mc.imgHolder_mc.loadMovie("buttonPhoto.jpg");
A generic image loading utility with pan, zoom, and preloading support is available at the online Code Depot.
loadMovieNum( ), MovieClip.loadMovie( ), System.security.allowDomain( ), unloadMovie( ); Section 13.3.4
