| MovieClip.setMask( ) Method | Flash 6 |
| assigns a movie clip as a mask for another clip |
A string indicating the path to the movie clip to be used as mc's mask. Because movie clip references are converted to paths when used in a string context, maskMovieClip can also be a movie clip object reference, as in mc.setMask(maskClip) versus mc.setMask("maskClip").
The setMask( ) method assigns maskMovieClip as a mask for mc. When invoked, the content of maskMovieClip becomes a hole through which the content of mc is visible. Those portions of mc beneath occupied pixels of maskMovieClip are displayed, but portions of mc beneath empty pixels in maskMovieClip are hidden. Therefore, masks typically are created with black pixels in the areas where you want the masked clip, mc, to show through. For example, maskMovieClip may contain a filled black circle used as a spotlight on mc's content. To remove any mask currently applied to mc, call setMask( ) with a maskMovieClip parameter of null.
The following code sets flashlight_mc as the mask of darkroom_mc:
darkroom_mc.setMask(flashlight_mc);
And the following code removes the flashlight_mc mask:
darkroom_mc.setMask(null);
Shapes drawn with the movie clip drawing methods (beginFill( ), lineTo( ), curveTo( ), etc.) can be used in masks. As of Flash 6 (but not before), timelines of movie clips used as masks play normally. Each frame's content becomes the mask when the content is displayed. Mask clips can also be dragged, sized, and moved programmatically, and they can take movie clip and button-style event handlers. For example, a mask clip can define an onEnterFrame( ) handler that changes its position with each passing frame. Or, a mask clip can define onPress( ) and onRelease( ) handlers that drag and drop it, as follows:
darkroom_mc.setMask("spotlight_mc");
spotlight_mc.onPress = function () {
trace("Dragging spotlight");
this.startDrag();
}
spotlight_mc.onRelease = spotlight_mc.onReleaseOutside = function () {
trace("Dropping spotlight");
this.stopDrag();
}
When maskMovieClip defines at least one button event handler or contains a button object, no button events pass through to mc. That is, a masked clip cannot respond to button events when its mask defines a button event or contains a button.
If we apply a runtime mask to a movie clip used in an author-time mask layer, Flash removes the author-time mask and places the newly masked clip behind the layers it masked at authoring time.
Masks in Flash have several limitations:
Prior to Flash Player 6.0.40.0, text fields without embedded fonts cannot be masked with a mask movie clip. As of Flash Player 6.0.40.0, the rectangular bounding box of a runtime mask movie clip can mask a text field even when its fonts are not embedded. To mask a text field in older versions of the Player, be sure to embed its font(s).
Text fields without embedded fonts cannot be used as masks.
Text fields without embedded fonts cannot be masked with an author-time mask layer.
Lines cannot be used as masks. Use fills, not lines, in mask movie
clips. Lines can be turned into fills via Modify 
Shape Convert Lines to Fills.
The setMask( ) method cannot assign more than one clip to be masked by a single mask movie clip. To apply an identical mask to several clips, duplicate the original mask movie clip as often as needed, or use an author-time mask, which can be applied to multiple movie clips simultaneously.
In Flash 6, fully contained holes in shapes inside movie clips are not reflected by masks. For example, it is impossible to create a doughnut-shaped mask using a movie clip (the doughnut's hole will be filled, and the mask will simply be a solid circle). However, an author-time primitive shape in a mask layer can be used to create mask shapes with fully contained holes. The beginFill( ) method can also be used at runtime to draw a shape with a hole that functions properly as a mask.