home | O'Reilly's CD bookshelfs | FreeBSD | Linux | Cisco | Cisco Exam    

Book HomeActionScript: The Definitive GuideSearch this book

13.6. Removing Clip Instances and Main Movies

We've learned to create and refer to movie clips; now let's see how to turn them into so many recycled electrons (in other words, blow 'em away).

The manner in which we created an instance or a movie determines the technique we use to remove that instance or movie later. We can explicitly remove movies and instances using unloadMovie( ) and removeMovieClip( ). Additionally, we may evict a clip implicitly by loading, attaching, or duplicating a new clip in its stead. Let's look at these techniques individually.

13.6.1. Using unloadMovie( ) with Instances and Levels

The built-in unloadMovie( ) function can remove any clip instance or main movie -- both those created manually and those created via loadMovie( ), duplicateMovieClip( ), and attachMovie( ). It can be invoked both as a global function and as a method:

unloadMovie(clipOrLevel);   // Global function
clipOrLevel.unloadMovie( );  // Method

In global function form, clipOrLevel is a string indicating the path to the clip or level to unload. And due to automatic value conversion, clipOrLevel may also be a movie clip reference (movie clips are converted to paths when used as strings). In method form, clipOrLevel must be a reference to a movie clip object. The exact behavior of unloadMovie( ) varies according to whether it is used on a level or an instance. Using unloadMovie( ) with levels

When applied to a level in the document stack (e.g., _level0, _level1, _level2), unloadMovie( ) completely removes the target level and the movie that the level contains. Subsequent references to the level yield undefined. Removing document levels is the most common use of the unloadMovie( ) function:

_level1.unloadMovie( ); Using unloadMovie( ) with instances

When applied to an instance (whether manually or programmatically created), unloadMovie( ) removes the contents of the clip, but it does not remove the clip itself ! The timeline and canvas of the clip are removed, but an empty shell remains on stage. That shell can be referenced until the instance is permanently removed via removeMovieClip( ) (or until the span of frames on which the instance resides ends). Furthermore, any clip event handlers on the shell remain active.

This partial deletion of instances presents an interesting possibility; it lets us maintain a generic container clip whose contents can be repeatedly changed via loadMovie( ) and unloadMovie( ). For example, we may quite legitimately invoke the following function series on an instance called clipA (though in a real application, these statements would include the appropriate preloader code):

clipA.loadMovie("section1.swf");  // Load a document into clipA
clipA.unloadMovie( );              // Unload the document, leaving clipA intact
clipA.loadMovie("section2.swf");  // Load another document into clipA

One note of caution with this approach. When used on an instance, unloadMovie( ) removes all custom properties of the clip contained by the instance. Physical properties, such as _x and _alpha persist, but custom variables and functions are lost.


If you use the global function form of unloadMovie( ) with a non-existent clip or level instance as its argument, the clip from which you invoked the unloadMovie( ) function will, itself, unload.

For example, if _level1 is undefined, and we issue the following code from the main timeline of _level0, then _level0 will unload:


Yes, there's some logic to this behavior, but we'll cover that later under Section, "Method versus global function overlap issues". You can avoid the problem by using a string when specifying the clipOrLevel argument of unloadMovie( ) or by checking explicitly that clipOrLevel exists before unloading it. Here's an example of each approach:

unloadMovie("_level1");  // clipOrLevel specified as a string
if (_level1) {           // Explicit check to make sure level exists

Library Navigation Links

Copyright © 2002 O'Reilly & Associates. All rights reserved.