The Drawing API is Flash's way of drawing shapes and lines with ActionScript. The Drawing API can be used in conjunction with any movie clip including the _root timeline.
The following sections cover some of the methods used in the Drawing API, starting with the lineStyle() method.
The lineStyle() Method
The lineStyle() method is used to define the stroke size, color, and transparency of a line before you start drawing with the other methods.
Its generic layout is this:
This method has the following parameters:
Although the lineStyle() method has many parameters, for the most part, you will need to work with the first three. And, this method alone will not show anything, so the example will have to wait until we draw a line.
The next method you would use with the Drawing API is the moveTo() method.
The moveTo() Method
The moveTo() method is used to create a starting point for the drawing API. It can also be used to move the drawing point without drawing a line. If the moveTo() method is skipped, the Drawing API begins drawing at points (0,0) of the movie clip it is being drawn in.
Here is the generic layout of the moveTo method:
This method has two parameters:
Like the lineStyle() method, the moveTo() method does not do anything that can be seen, so the example of its use can be seen in the following section covering the next method: the lineTo() method.
The lineTo() Method
The lineTo() method is used to draw a line from the preceding point created by either the moveTo() method or another lineTo() method to the next point. The line drawn will have the characteristics created by the lineStyle() method (or the lineGradientStyle() method, which we will discuss later).
The generic layout for this method is
The two parameters for this method are
Now that we have covered three of the basic methods for the drawing API, here is an example that will bring them together.
The preceding code does three things. First, it creates the line style with a weight of 2 pixels, with black as its color, and a 100% alpha setting. After that, it moves the starting point to (100,100). Then it draws a diagonal line to point (200,200).
Test the movie and your screen should look similar to Figure 13.11 with a diagonal line. You can go back in and add more lineTo() methods to make the line go from point to point.
Figure 13.11. Use the Drawing API to draw lines right from ActionScript at runtime.
That was a simple enough example. Next is a more advanced example, which enables the user to draw lines during runtime all over the stage. To accomplish this, follow these steps:
The preceding code does many things. First, it creates an event for when the user clicks the mouse button, which in turn creates another event that triggers continuously while the user moves the mouse. While the user is moving the mouse, a line is drawn to where the mouse is, and the line continuously changes color. Finally, we create an event for when the user releases the mouse. When that event is triggered, the onMouseMove event is destroyed and the line will not follow the mouse any more.
Test the movie and you will see that when you click the mouse and move the mouse around, a constantly color-changing line will follow the mouse around.
There is also another way to set line properties, and that is to use the lineGradientStyle() method.
The lineGradientStyle() Method
New to Flash 8 is the capability to have gradients within strokes. This can also be accomplished in ActionScript using the lineGradientStyle() method like this:
The preceding method has the following parameters:
It is important to note that this method can be called only after calling the lineStyle() method to set the line size.
Revisiting our previous example, this next example will draw a line following the mouse, but use a predefined gradient.
The preceding code is very similar to the previous example, except this time we set the lineStyle() first and then set the new lineGradientStyle(). Test this movie, and after drawing for a little bit, you should see something similar to Figure 13.12.
Figure 13.12. You can see the radial gradient being formed after drawing several lines.
Note that the lineGradientStyle() method is available only in the Flash 8 player.
Now that you know how to draw a line, the next step is how to draw a shape and fill it with the beginFill() method.
The beginFill() Method
The beginFill() method is used to fill shapes drawn with drawing API. Whenever you use the beginFill() method, when you are done filling the shape, you should always have the endFill() method to tell the Drawing API you are done filling.
Here is the generic layout of the beginFill() method:
This method has two parameters:
In the next example, we will draw a square and fill it with a light green color.
The preceding code started out similar to previous examples, but this time after we went to the starting point, we began to fill the shape. After that we drew the square. And finally, we ended the fill with the endFill() method.
Test the movie, and you should see a square with a light green color for the fill, as shown in Figure 13.13.
Figure 13.13. You can use the drawing API to draw shapes and color them in.
You can create gradient fills as well using the beginGradientFill() method.
The beginGradientFill() Method
The beginGradientFill() acts just like the beginFill() method, except it has these parameters:
Following is a better explanation of those parameters:
Now let's see an example of this.
This code first creates some properties for our gradient and then sets the line style and gradient fill. Finally, the square is drawn, as you can see in Figure 13.14.
Figure 13.14. You can set gradients to the fill color for a more vibrant effect.
So far, we have drawn straight lines, but the next section will go over how to draw curved lines with the curveTo() method.
The curveTo() Method
The curveTo() method is used to draw curved lines with the Drawing API. It works similarly to the lineTo() method in that it starts from the previous point created by either a moveTo() method or a lineTo() method.
Its generic layout is as follows:
This method has four parameters:
The generic layout is a little difficult to grasp without an example, so here is one:
The preceding code creates the line style, then declares a starting point, and finally draws the curved line.
Test the movie and your screen should have a curved line on it similar to Figure 13.15.
Figure 13.15. Use the curveTo() method to draw curved lines with the Drawing API.
That example was pretty simple. The following example shows off the curveTo() method a little further.
The preceding code doesn't really do anything special. It declares the line style we want to use. Then it sets a start point using the moveTo() method. After that, it begins the fill with a shade of red as its color. Then it begins to draw the shape using a few curveTo() methods. It finishes by ending the fill with the endFill() method (which is good practice).
Now test the movie, and you will see a shape on your screen similar to the one in Figure 13.16. Now that you see what can be accomplished with the Drawing API, you can start creating your own custom shapes entirely through ActionScript.
Figure 13.16. A heart is just one of the many shapes that can be drawn with a little math and the Drawing API.