The following is an excerpt from the forthcoming ActionScript Cookbook. It is unedited. Furthermore, some of the code examples rely on classes discussed in other chapters in the book. However, the main thesis of the excerpt should still be clear.

Removing Movie Clips

Problem

You want to programmatically remove a movie clip instance.

Solution

Use the removeMovieClip( ) method. If the depth is outside the valid range, use the static remove( ) method of the custom ascb.util.MovieClipUtils class.

Discussion

You can programmatically remove a movie clip instance using the removeMovieClip( ) method. You can call the method from any movie clip instance. It does not require any parameters, and it does not return a value.

mClip.removeMovieClip();

That's simple enough. However, as many Flash developers have learned over the years, removeMovieClip( ) doesn't necessarily work in every case. The reason is that Flash only allows you to programmatically remove a movie clip instance if its depth is within a specific range. Any movie clip with a depth between 0 and 1048575 inclusive can be programmatically removed. Any other movie clip remains unaffected by removeMovieClip( ). You can see that for yourself with a simple test.

this.createEmptyMovieClip("mA", -1);
this.createEmptyMovieClip("mB", 0);
this.createEmptyMovieClip("mC", 1048575);
this.createEmptyMovieClip("mD", 1048576);

mA.removeMovieClip();
mB.removeMovieClip();
mC.removeMovieClip();
mD.removeMovieClip();

trace(mA);  // _level0.mA
trace(mB);  // undefined
trace(mC);  // undefined
trace(mD);  // _level0.mD

As you may have already noticed, when you create movie clips using getNextHighestDepth( ), they are generally assigned depths greater than 1048575. That means you cannot remove them using a conventional removeMovieClip( ) method call. However, you can still remove them. The key is that you need to change the depth to be within the valid range. You can accomplish that using swapDepths( ). For example, you can use the following to remove mClip even if its original depth was not in the valid range.

mClip.swapDepths(0);
mClip.removeMovieClip();

Of course, if there's already a movie clip at depth 0, it will then change depths to the depth previously held by mClip. That could potentially cause that movie clip to appear in the incorrect z-axis order. Therefore, you should make sure you move the instance back to depth 0. To do that, you can first use the getInstanceAtDepth( ) method to get a reference to the instance (if any) at depth 0. Then, after changing the depths and removing mClip, you can change the depth of the other movie clip back to 0.

var mTemp:MovieClip = this.getInstanceAtDepth(0);
mClip.swapDepths(0);
mClip.removeMovieClip();
if(mTemp != undefined) {
  mTemp.swapDepths(0);
}

The MovieClipUtils.remove( ) method uses the same logic. You can use the method to simplify things. You can use the method any time you want to remove a movie clip, without having to concern yourself with the depth of that movie clip. The following example illustrates how you can use the remove( ) method.

import ascb.drawing.Pen;
import ascb.util.MovieClipUtils;

// Draw a triangle at depth 0.
this.createEmptyMovieClip("mTriangle", 0);
var pTriangle:Pen = new Pen(mTriangle);
pTriangle.drawTriangle(50, 40, 30);

// Draw a circle at depth 200000.
this.createEmptyMovieClip("mCircle", 200000);
var pCircle:Pen = new Pen(mCircle);
pCircle.beginFill(0xFFFFFF);
pCircle.drawCircle(20);
pCircle.endFill();

// Remove the circle when the user clicks on it.
mCircle.onRelease = function():Void {
  MovieClipUtils.remove(this);
};

You can see that in the preceding example the circle is removed, even though the depth is outside the range that Flash can programmatically remove. The remove( ) method temporarily changes the depth of the movie clip to 0. You can see that the triangle at depth 0 appears undisturbed, however. So the remove( ) method can remove any movie clip without disturbing any other movie clip in the application.