The Drawing API

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:

[View full width]
 movie.lineStyle(thickness, color, alpha, pixelHinting, noScale, capsStyle, jointStyle,  miterLimit); 

This method has the following parameters:

• thickness A numerical value used to declare the weight of the line.

• color A hexadecimal value used to declare the color of the line.

• alpha A numerical value representing the transparency level of the line.

• pixelHinting An optional Flash 8 player parameter with a Boolean value stating whether to use pixel hinting, which affects anchors and position or curves.

• noScale An optional Flash 8 player parameter with a string value stating how to scale the line:

  • normal Always scale the thickness of the line. This is the default choice.

  • none Never scale the thickness of the line.

  • vertical Do not scale the thickness of the line when the line is vertically scaled.

  • horizontal Do not scale the thickness of the line when the line is horizontally scaled.

• capStyle An optional Flash 8 player parameter with a string value controlling the end caps of the line segment; it handles none, round, or square.

• jointStyle An optional Flash 8 player parameter with a string value controlling the joint style of the line segments; it handles miter, round, or bevel.

• miterLimit An optional Flash 8 player parameter with a string value controlling the level of miter on line segments, but only when the jointStyle parameter is set to "miter."

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:

 myMovie.moveTo(X,Y); 

This method has two parameters:

• X A numerical value representing the horizontal position the drawing point is moved to without a line being drawn

• Y A numerical value representing the vertical position the drawing point is moved to without a line being drawn

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

 myMovie.lineTo(X,Y); 

The two parameters for this method are

• X A numerical value representing the horizontal position to draw the line to

• Y A numerical value representing the vertical position to draw the line to

Now that we have covered three of the basic methods for the drawing API, here is an example that will bring them together.

1.	Create a new Flash document.
2.	In the first frame of the main timeline, open the Actions panel and place these actions in it: //create the line style this.lineStyle(2,0x000000,100); //move the starting point this.moveTo(100,100); //draw a line this.lineTo(200,200);

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:

1.

Create a new Flash document.

2.

In the first frame of the main timeline, open the Actions panel and place these actions in it: //this event will trigger when the user presses the mouse button this.onMouseDown = function(){ //declare the line style this.lineStyle(4,Math.random()*0x1000000,100); //set the starting point this.moveTo(this._xmouse,this._ymouse); //this event will fire as the user moves the mouse this.onMouseMove=function(){ //draw a line this.lineTo(this._xmouse,this._ymouse); //re-style the line this.lineStyle(4,Math.random()*0x1000000,100); } } //this event triggers when the user releases the mouse this.onMouseUp = function(){ //destroy the onMouseMove event delete this.onMouseMove; }

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:

[View full width]
 myMovie.lineGradientStyle(fillType, colors, alphas, ratios, matrix, spreadMethod,  interpolationMethod, focalPointRatio); 

The preceding method has the following parameters:

• fillType This parameter controls the type of gradient, either "linear" or "radial."

• colors This is an array of the different colors you want to use in the gradient.

• alphas This is an array of the different levels of alpha you want to use in conjunction with the colors parameter.

• ratios This is an array of the color distribution levels you want to use in conjunction with the colors parameter. Range from 0255.

• matrix This is the transformation matrix used in our gradient.

• spreadMethod This controls the mode of gradient fill and will accept "pad," "reflect," or "repeat."

• interpolationMethod This controls the type of interpolation of the colors and accepts "RGB" or "linearRGB."

• focalPointRatio This numerical value controls the focal point of the gradient.

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.

1.

Create a new Flash document.

2.

In the first frame, place these actions: //set up the properties of the gradient we are going to use var colors:Array = [0x009900, 0x397dce]; var alphas:Array = [50, 100]; var ratios:Array = [0, 0xFF]; var matrix:Object = {a:200, b:0, c:0, d:0, e:200, f:0, g:200, h:200, i:1}; var sMethod:String = "repeat"; var iMethod:String = "RGB"; var fpRatio:Number = .5; //set the line style and gradient this.lineStyle(4); this.lineGradientStyle("radial",colors,alphas,ratios,matrix,sMethod,iMethod,fpRatio); //this.lineGradientStyle(4,Math.random()*0x1000000,100); //this event will trigger when the user presses the mouse button this.onMouseDown = function() { //set the starting point this.moveTo(this._xmouse,this._ymouse); //this event will fire as the user moves the mouse this.onMouseMove = function() { //draw a line this.lineTo(this._xmouse,this._ymouse); } } //this event triggers when the user releases the mouse this.onMouseUp = function() { //destroy the onMouseMove event delete this.onMouseMove; }

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

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:

 myMovie.beginFill(color,alpha); 

This method has two parameters:

• color A hexadecimal value used in declaring the color of the fill

• alpha A numerical value representing the transparency of the fill

In the next example, we will draw a square and fill it with a light green color.

1.	Create a new Flash document.
2.	In the first frame of the main timeline, open the Actions panel and place these actions in it: //create the line style this.lineStyle(2,0x000000,100); //move the starting point this.moveTo(100,100); //begin the fill this.beginFill(0x00ff00,50); //draw a line this.lineTo(100,200); this.lineTo(200,200); this.lineTo(200,100); this.lineTo(100,100); //end the fill this.endFill();

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:

[View full width]
 myMovie.beginGradientFill(fillType, colors, alphas, ratios, matrix, spreadMethod,  interpolationMethod, focalPointRatio); 

Following is a better explanation of those parameters:

• fillType This parameter controls the type of gradient, either "linear" or "radial."

• colors This is an array of the different colors you want to use in the gradient.

• alphas This is an array of the different levels of alpha you want to use in conjunction with the colors parameter.

• ratios This is an array of the color distribution levels you want to use in conjunction with the colors parameter. Range from 0255.

• matrix This is the transformation matrix used in our gradient.

• spreadMethod This controls the mode of gradient fill and will accept "pad," "reflect," or "repeat."

• interpolationMethod This controls the type of interpolation of the colors and accepts "RGB" or "linearRGB."

• focalPointRatio This numerical value controls the focal point of the gradient.

Now let's see an example of this.

1.

Create a new Flash document.

2.

Place these actions in the first frame: //properties for our gradient var fillType:String = "radial"; var colors:Array = [0x009900, 0x397dce]; var alphas:Array = [50, 100]; var ratios:Array = [0x00, 0xFF]; var matrix:Object = {a:100, b:0, c:0, d:0, e:100, f:0, g:100, h:100, i:1}; var spreadMethod:String = "repeat"; //set the linestyle and gradient fill this.lineStyle(2,0x000000,100); this.beginGradientFill(fillType, colors, alphas, ratios, matrix, spreadMethod); //draw a square this.moveTo(0, 0); this.lineTo(0, 200); this.lineTo(200, 200); this.lineTo(200, 0); this.lineTo(0, 0); this.endFill();

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:

 myMovie.curveTo(controlX,controlY,X,Y); 

This method has four parameters:

• controlX This represents the horizontal position toward which the line will curve.

• controlY This represents the vertical position toward which the line will curve.

• X This is the horizontal position where the curved line will end.

• Y This is the vertical position where the curved line will end.

The generic layout is a little difficult to grasp without an example, so here is one:

1.	Create a new Flash document.
2.	In the first frame of the main timeline, open the Actions panel and place these actions in it: //declare the line style this.lineStyle(2,0x000000,100); //create the start point this.moveTo(100,100); //draw the curved line this.curveTo(200,100,200,200);

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.

1.

Create a new Flash document.

2.

In the first frame of the main timeline, open the Actions panel and place these actions in it: //declare the line style this.lineStyle(3,0x000000,100); //go to the start point this.moveTo(300,260); //start the fill this.beginFill(0xff0000,100); //start drawing the shape this.curveTo(300,200,250,200); this.curveTo(185,200,195,270); this.curveTo(220,350,300,400); this.curveTo(398,350,400,260); this.curveTo(400,200,350,200); this.curveTo(300,200,300,260); //end the fill this.endFill();

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.