indicate that a display object will be the mask for another display
object, set the mask object as the mask property
of the display object to be masked:
// Make the object maskSprite be a mask for the object mySprite.
mySprite.mask = maskSprite;
The masked display object is revealed under all opaque (nontransparent)
areas of the display object acting as the mask. For instance, the
following code creates a Shape instance containing a red 100 by
100 pixel square and a Sprite instance containing a blue circle
with a radius of 25 pixels. When the circle is clicked, it is set
as the mask for the square, so that the only part of the square
that shows is the part that is covered by the solid part of the
circle. In other words, only a red circle will be visible.
// This code assumes it's being run within a display object container
// such as a MovieClip or Sprite instance.
// Draw a square and add it to the display list.
var square:Shape = new Shape();
square.graphics.drawRect(0, 0, 100, 100);
// Draw a circle and add it to the display list.
var circle:Sprite = new Sprite();
circle.graphics.drawCircle(25, 25, 25);
square.mask = circle;
The display object that is acting as a mask can be draggable,
animated, resized dynamically, and can use separate shapes within
a single mask. The mask display object doesn’t necessarily need
to be added to the display list. However, if you want the mask object
to scale when the Stage is scaled or if you want to enable user
interaction with the mask (such as user-controlled dragging and
resizing), the mask object must be added to the display list. The
actual z-index (front-to-back order) of the display objects doesn’t
matter, as long as the mask object is added to the display list.
(The mask object will not appear on the screen except as a mask.)
If the mask object is a MovieClip instance with multiple frames,
it plays all the frames in its timeline, the same as it would if
it were not serving as a mask. You can remove a mask by setting
the mask property to null:
// remove the mask from mySprite
mySprite.mask = null;
You cannot use a mask to mask another mask. You cannot set the alpha property
of a mask display object. Only fills are used in a display object
that is used as a mask; strokes are ignored.
If a masked display
object is cached by setting the cacheAsBitmap and cacheAsBitmapMatrix properties,
the mask must be a child of the masked display object. Similarly,
if the masked display object is a descendent of a display object
container that is cached, both the mask and the display object must
be descendents of that container. If the masked object is a descendent
of more than one cached display object container, the mask must
be a descendent of the cached container closest to the masked object
in the display list.