ACTIONSCRIPT 3 Developer’s Guide en

ACTIONSCRIPT 3.0 DEVELOPER’S GUIDE
Display programming
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-toback
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.
AIR 2
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.
About masking device fonts
You can use a display object to mask text that is set in a device font. When you use a display object to mask text set in
a device font, the rectangular bounding box of the mask is used as the masking shape. That is, if you create a nonrectangular
display object mask for device font text, the mask that appears in the SWF file is the shape of the
rectangular bounding box of the mask, not the shape of the mask itself.
Alpha channel masking
Alpha channel masking is supported if both the mask and the masked display objects use bitmap caching, as shown here:
// maskShape is a Shape instance which includes a gradient fill.
mySprite.cacheAsBitmap = true;
maskShape.cacheAsBitmap = true;
mySprite.mask = maskShape;
For instance, one application of alpha channel masking is to use a filter on the mask object independently of a filter
that is applied to the masked display object.
In the following example, an external image file is loaded onto the Stage. That image (or more accurately, the Loader
instance it is loaded into) will be the display object that is masked. A gradient oval (solid black center fading to
transparent at the edges) is drawn over the image; this will be the alpha mask. Both display objects have bitmap caching
turned on. The oval is set as a mask for the image, and it is then made draggable.
Last updated 6/6/2012
191