Table of Contents

removeMovieClip(target)

Arguments

target

A string or reference indicating the path to the movie clip instance to be removed from the Player (references to movie clips are converted to paths when used in a string context).

Description

The removeMovieClip( ) function deletes the specified movie clip from the Player, leaving no trace of the clip's contents or shell. Subsequent references to the clip or any variables or properties it contained yield undefined.

The removeMovieClip( ) function can be used only on movie clip instances that were originally created via duplicateMovieClip( ), attachMovie( ), or createEmptyMovieClip( ). It has no effect on movie clips on negative depths (normally those created at authoring time). To remove a negative-depth clip, first swap it to a positive depth, then remove it:

theClip_mc.swapDepths(1234);   // Pick a safe number to swap to.
theClip_mc.removeMovieClip();  // Remove the clip.

If more than one variable refers to the same movie clip, removeMovieClip( ) deletes the movie clip from the Stage but other references to it remain. That is, the movie clip persists as a data object until all references to the clip have been removed. For example:

// Create a new clip, clipInstance_mc, from the Library symbol clipSymbol.
// Store a convenient reference to clipInstance_mc in the variable c.
var c = this.attachMovie("clipSymbol", "clipInstance_mc", 1);
// At this point, two references to the movie clip exist:
// one in c, and one in clipInstance_mc.
   
// Remove clipInstance_mc
clipInstance_mc.removeMovieClip();
// Check if clipInstance_mc still exists...
trace(typeof clipInstance_mc);  // Nope. Displays: undefined
// Check if the reference to clipInstance_mc in c still exists....
trace(typeof c);                // Yup! Displays: movieclip 
                                // (the reference still exists!)

To fully remove all traces of the clip, we must delete any remaining variables that store a reference to it. Continuing the preceding example:

// Remove the reference in c.
delete c;
trace(typeof c);   // Displays: undefined (now it's really gone)

See Also

attachMovie( ), duplicateMovieClip( ), MovieClip.removeMovieClip( ), MovieClip.swapDepths( ), unloadMovie( ), Section 13.6

Table of Contents