Written by: Patrick Mineault, patrick@5etdemi.com , http://www.5etdemi.com
Difficulty Level: advanced
Requirements: MX and experience with actionscript
Topics Covered: Drawing API, dynamic masking masking, preloaders,
transitions and draggable masks
Assumed Knowledge: basic actionscript (loops conditions clip events
properties arrays whatnot)
Download FLA

Dynamic masking using the drawing API

Flash is a much more mature beast than it was years ago and certainly the introduction of the drawing API has helped establish this. Macromedia has included functions for drawing dynamically on stage since the introduction of MX. If you've tried using these functions you've certainly found that although deceptively simple they can be quite effective for creating components and advanced effects.

One of the neatest things you can do with the drawing API is use it to draw dynamic masks. This allows you to create effects that would otherwise been a pain with static masking. In this tutorial I'll give you an overview of the way the drawing API works in connection with dynamic masks with three complete real-world examples. I'm sure you will be impressed by the simplicity and flexibility of this set of tools.

How to use the drawing API and dynamic masks

The drawing API consists of these 8 functions:


That's it. In our particular case we won't even need all of these. In the following we will use beginFill, clear, endFill, lineTo and moveTo. In addition we will need the with keyword and createEmptyMovieClip. Let's write a simple script that draws a square on stage:


You can put this script on a frame and test the movie to see the effect. It's very simple really. The createEmptyMovieClip call creates a new movie clip on stage with the specified instance name and level. The with action is a shortcut that selects a certain movie clip and assumes that subsequent actions are applied to it. This allows us to have cleaner code than with the conventional alternative:


Although this script is functionally equivalent to the first one you can easily see that the with action makes everything tidier and simpler.

Now for the meat of the drawing API. Basically you first move a "pointer" to a certain point in the target movie clip. Then you start drawing by calling beginFill. Next, you move the pointer across the stage using lineTo, following the outline of the shape you want to draw. Finally, you end the routine with a call to endFill, which effectively draws the shape that you have outlined. Although we have not used it in this example, calling _root.square.clear() will clear the square that we have drawn. Those of you who were in the Quebec education system in the late 80s may have flashbacks of LOGO and the infamous LC and BC (if you have no idea what I'm speaking of please ignore the preceding).

Using this movie clip as a mask is just a matter of adding a single line of code. Start out by drawing a small shape in the top left corner of the stage. Convert to a movie clip using F8. Assign it the instance name "maskee". Then at the end of the script we've created you will add:

_root.maskee.setMask (_root.square)

This assigns the square movie clip as the mask of maskee. As you see Macromedia has created a marvelously simple API that is plenty powerful. Let's see a few examples in action.

Movie 1: Draggable mask

Those of you that were around in the "good old days" of Flash 5 remember what a pain it was to create a draggable mask. For some reason the mask was unavailable for scripting and so the container movie clip and the maskee had to be moved simultaneously in a splendidly awkward workaround. Gone is this nightmare in MX. Let's start out by creating a new movie. Draw something on stage (anything, as long as it has colors). Now convert to movie clip using F8. We'll call this clip the maskee.

Select the movie clip and attach this script to it (not to the frame, the movie clip!):

        function drawSquare()
                x = _root._xmouse;
                y = _root._ymouse;
        this.setMask (_root.square)

Test the movie (Ctrl+Enter): you now have a draggable mask! How does it work? Well, as with the first example an empty movie clip is created and assigned as the mask of the target movie clip. The trick here is that the mouseMove clip event is used to trigger the drawing of a square around the mouse. The mouseMove event is triggered every time the mouse is moved. When this is done the drawSquare function is called. Using the coordinates of the mouse it draws a square with the top left corner at (-50, -50) and (50,50) relative to the mouse cursor, hence drawing a square 100 pixels wide that follows the mouse.

Question: why bother using the drawing API every time the mouse is moved? Wouldn't it be better to draw the square once and then change the _x and _y of the mask when the cursor is moved, or even, gasp!, using startDrag()?

Answer: The advantage of using the method outlined above should become apparent with this simple modification: comment out the clear(); line. Test the movie. There you have it folks: a scratch and win game!

What just happened? By commenting out the clear(); line, the previously drawn squares are never erased. Therefore every time the mouse is moved a square is added to the clip, effectively creating a bigger and bigger mask. By adding a condition that checks for mouse down and using a smaller and different shape you could easily transform this into a "real" scratch and win game.