public removeMovieClip() : Void

Removes a movie clip instance created with duplicateMovieClip(), MovieClip.duplicateMovieClip(), MovieClip.createEmptyMovieClip(), or MovieClip.attachMovie().

This method does not remove a movie clip assigned to a negative depth value. Movie clips created in the authoring tool are assigned negative depth values by default. To remove a movie clip that is assigned to a negative depth value, first use MovieClip.swapDepths() to move the movie clip to a positive depth value.

Note: If you are using V2 components, and use MovieClip.getNextHighestDepth() instead of the DepthManager class to assign depth values, you may find that removeMovieClip() fails silently. When any V2 component is used, the DepthManager class automatically reserves the highest (1048575) and lowest (-16383) available depths for cursors and tooltips. A subsequent call to getNextHighestDepth() returns 1048576, which is outside the valid range. The removeMovieClip() method fails silently if it encounters a depth value outside the valid range. If you must use getNextHighestDepth() with V2 components, then you can use swapDepths() to assign a valid depth value or use MovieClip.unloadMovie() to remove the contents of the movie clip. Alternatively, you can use the DepthManager class to assign depth values within the valid range.

You can extend the methods and event handlers of the MovieClip class by creating a subclass.

Example

Each time you click a button in the following example, you attach a movie clip instance to the Stage in a random position. When you click a movie clip instance, you remove that instance from the SWF file.

function randRange(min:Number, max:Number):Number {
    var randNum:Number = Math.round(Math.random()*(max-min))+min;
    return randNum;
}
var bugNum:Number = 0;
addBug_btn.onRelease = addBug;
function addBug() {
    var thisBug:MovieClip = this._parent.attachMovie("bug_id", "bug"+bugNum+"_mc", bugNum, 
{_x:randRange(50, 500), _y:randRange(50, 350)});
    thisBug.onRelease = function() {
    this.removeMovieClip();
    };
    bugNum++;
}

See also

duplicateMovieClip function, createEmptyMovieClip (MovieClip.createEmptyMovieClip method), duplicateMovieClip (MovieClip.duplicateMovieClip method), attachMovie (MovieClip.attachMovie method), swapDepths (MovieClip.swapDepths method)