Actionscript Cookbook

4.12. Scripting Masks

Problem

You want to create a mask at runtime.

Solution

Use the Drawing API to create a shape and then use MovicClip.setMask( ) to apply the mask.

Discussion

Masks can be used to create unique shapes or visual effects. For example, you can use masks to create wipes and transitions or interesting animations in which only the masked portion of the artwork is visible at a given time. You can even create masks that change shape over time, and use them to mask bitmapped graphics (in movie clips).

You can use any movie clip as a mask of another movie clip using the setMask( ) method. The setMask( ) method is called from the movie clip to be masked, and you should pass it a reference to the movie clip that acts as the mask:

maskedMovieClip.setMask(maskMovieClip);

In most cases, masks are simple shapes, such as rectangles or circles. You do not need to use the Drawing API to draw the mask movie clip, but it is recommended that you do so unless the mask is of an unusual shape.

First, here is an example in which a mask follows the mouse. The mask is assigned to a movie clip containing a loaded image, so the effect is that the user can see only the portion of the image over which he has positioned the mouse.

// Include the drawing methods, which are needed for the drawCircle(  ) method.
#include "DrawingMethods.as"

// Create a movie clip and a nested movie clip for loading an image. See Recipe 15.3 // for more information on the need for creating nested movie clips when loading ...