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:

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

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:

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

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.

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.