Removing Clip Instances and Main Movies (ActionScript: The Definitive Guide)

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.

13.6.1.1. 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:

unloadMovie("_level1");
_level1.unloadMovie( );

13.6.1.2. 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.

WARNING

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:

unloadMovie(_level1);

Yes, there's some logic to this behavior, but we'll cover that later under Section 13.8.3.1, "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
  unloadMovie(_level1);
}

13.6.2. Using removeMovieClip( ) to Delete Instances

To delete attached and duplicated instances from the Player, we can use removeMovieClip( ). Note that removeMovieClip( ) works on duplicated or attached instances only. It cannot delete a manually created instance or a main movie. Like unloadMovie( ), removeMovieClip( ) may be used in both method and global function form (though the syntax is different, the effect is the same):

removeMovieClip(clip)    // Global function
clip.removeMovieClip( )  // Method

In global function form, clip is a string indicating the path to the clip to remove. Due to automatic value conversion, clip may also be a movie clip reference (movie clips are converted to paths when used as strings). In method form, clip must be a reference to a movie clip object.

Unlike unloadMovie( ), deleting an instance via removeMovieClip( ) completely obliterates the entire clip object, leaving no shell or trace of the clip and its properties. When we execute clip.removeMovieClip( ), future references to clip yield undefined.

13.6.3. Removing Manually Created Instances Manually

Clip instances created manually in the Flash authoring tool also have a limited life span -- they are removed when the playhead enters a keyframe that does not include them. Manually created movie clips, hence, live in fear of the almighty blank keyframe.

Remember that when a movie clip disappears from the timeline, it ceases to exist as a data object. All variables, functions, methods, and properties that may have been defined inside it are lost. Therefore, if we want a clip's information or functions to persist, we should be careful about removing the clip manually and should ensure that the span of frames on which the clip resides extends to the point where we need that clip's information. (In fact, to avoid this worry entirely, we should attach most permanent code to a frame in the main movie timeline.) To hide a clip while it's present on the timeline, simply position the clip outside the visible area of the Stage, and set the clip's _visible property to false. Setting a clip's _x property to a very large positive number or very small negative number should also suffice to hide it from the user's view without removing it from memory.