Drawing API


Flash comes with a drawing API (application programming interface). The drawing API is simply a set of movie clip methods that enable you to draw lines, curves, and shapes with fills programmatically with ActionScript.

When Flash saves images in a vector graphics file format, information about the vector shapes in the document is saved as areas of color that are defined by lines and curves. In the authoring environment, you define these lines and shapes with the drawing tools directly on the stage. With ActionScript, you can define the lines and fills of vector graphics dynamically. The images are then drawn, based on your code, when you export to your .swf document and while the .swf is running (run-time).

When drawing "by hand" on the stage of the authoring environment, you can start drawing first and then later convert the lines and shapes into a symbol. However, when drawing with ActionScript, you must create a movie clip symbol instance first, and then draw inside of it. You can think of this movie clip as the paper on which you draw with your ActionScript.

If you're going to draw with ActionScript, you need to understand how to position your work on the stage. The Flash coordinate system starts with (0,0) in the upper-left corner. The numbers are positive and increase from left to right and from top to bottom of the stage (see Figure 12.1). This differs from the Cartesian grid you might be familiar with. Figure 12.1 shows the two grid systems side by side. Understanding this difference becomes especially important when working with trigonometric functions and you need to covert the Cartesian coordinates to Flash coordinates before applying the result of the function to a movie clip.

Figure 12.1. Cartesian grid versus a Flash grid, with coordinates plotted on each grid.


All coordinates passed to the movie clip methods related to drawing are relative to the registration point of the parent clip (the clip inside of which you are drawing). If a line is drawn into a clip, the line's position is relative to the parent clip. If the parent clip is on the stage, its registration point is relative to the stage. The registration point of a movie clip is in the upper-left corner by default. When using the drawing API, you use these coordinates to tell Flash what and where to draw.

Drawing API Methods

The Drawing API methods can be applied to any movie clip instance, including the main timeline. The methods work together and some are dependent on others. For example, a lineStyle() method must define the style of a line before you can draw the line with the moveTo(), lineTo(), or curveTo() methods. The following section describes the movie clip methods available with the Flash Drawing API.

lineStyle()


Before you can draw a line or curve with your script, you first need to define its line style. Think of it as picking up a certain style of pen before drawing on a piece of paper. The lineStyle() statement applies to the lineTo() and curveTo() statements that follow it. When you draw several lines sequentially, you can change the look of any segment by redefining the line style before drawing the segment.

The syntax is as follows:

draw_mc.lineStyle(thickness , rgb , alpha)


For example,

myLine.lineStyle(5, 0x333366, 80);


The thickness parameter must have a value between 0 and 255. Any value less than 0 is evaluated as 0 by Flash. Also, any value greater than 255 is evaluated as 255. If no value is specified, the lineStyle is undefined and the line is not drawn.

The rgb parameter is the hex color value for the line. Its default value is black (0x000000).

The alpha parameter sets the transparency level of the line's color. It can range between 0 and 100. The default value is 100, which represents a completely solid color. Just as with thickness, numbers above the maximum are evaluated at the maximum level and numbers below the minimum are evaluated at the minimum. For example, if you accidentally set the alpha value at -90, it is drawn as 0.

moveTo()


The moveTo method gives your line a starting coordinate. This is rather like putting your pen down on a specific point on the paper and getting ready to draw. In the flow of your code, it should follow the lineStyle statement.

The syntax is as follows:

draw_mc.moveTo(x, y)


For example,

myLine.moveTo(100, 200);


The x and y parameters set the coordinates of the starting point for this drawing path. It's important to remember that these coordinates are relative to the parent clip, much like the position of a patch of paint is relative to the canvas it's painted on. In this example, the coordinate (100, 200) is positioned 100 pixels down from, and 200 pixels to the right of, the registration point (0,0) of the myLine movie clip.

lineTo()


The lineTo method sets the endpoint of a straight line.

The syntax is as follows:

draw_mc.lineTo(x, y)


For example,

myLine.lineTo(200, 200);


The x and y coordinates are relative to the registration point of the parent movie clip (the crosshair inside the movie clip). A straight line is drawn from the previous drawing position to the coordinate set with lineTo().

If you use a lineTo method without first using moveTo, the starting point defaults to (0,0). So, if you plan to start at (0,0), you do not need the moveTo line.

curveTo()


The curveTo method draws a line from a starting point to an endpoint with a curve toward a control point. The starting and end points are called anchor points. It might help to think of this process as drawing a regular straight line and then pulling the middle of it so that it stretches and curves toward a control point but never reaches it (see Figure 12.2).

Figure 12.2. Diagram of curveTo anchor points (squares) and control point (circle).


The syntax is as follows:

draw_mc.curveTo(controlX, controlY, anchorX, anchorY)


For example,

myCurve.curveTo(300, 100, 200, 200);


The controlX and controlY parameters set the coordinates for the curve's control point.

The anchorX and anchorY parameters set the coordinates for the end point of this curve segment.

clear()


The clear method removes all programmatically drawn elements from the drawing movie clip. It does not affect elements that were drawn in a movie clip during author-time. The MovieClip.clear() statement also resets lineStyle back to undefined.

The syntax is as follows:

draw_mc.clear()


For example,

myCurve.clear(); beginFill()


The beginFill() method enables you to define the fill color and transparency level of a closed shape. It precedes the methods used to draw the outline of the shape and is closed by calling the endFill() method.

The syntax is as follows:

draw_mc.beginFill(rgb, alpha)


For example,

myshape.beginFill(0x003366, 80);


The rgb parameter is the hex color value for the fill. This is the value of the color as you would see it in the Swatch panel, with a 0x proceeding the numeric value.

The alpha parameter sets the fill's transparency level. It defaults to 100 (solid color).

beginGradientFill()


Whereas the beginFill() method lets you define a single fill color and is simple to use, the beginGradientFill() method enables you to define a gradient and is a little more complicated to use. Figure 12.3 shows a gradient filled shape.

Figure 12.3. Radial gradient fill.


The syntax is as follows:

draw_mc.beginGradientFill(fillType, colors, alphas, ratios, matrix)


For example,

this.createEmptyMovieClip("gradient_mc", 1); with (gradient_mc) {     colors = [0xFF0000, 0xFF9933];     alphas = [100, 80];     ratios = [0, 0xFF];     matrix = {matrixType:"box", x:100, y:100, w:200, h:200, r:(45/180)*Math.PI};     beginGradientFill("radial", colors, alphas, ratios, matrix);     moveTo(100, 100);     lineTo(100, 300);     lineTo(300, 300);     lineTo(300, 100);     lineTo(100, 100);     endFill(); }


The fillType can be set to either linear or radial. These gradients are just like the gradients you can create with the tools in the authoring environment. A linear gradient transitions from one color to another in one direction, and a radial gradient transitions out from a central point.

The colors parameter holds an array (a list of values) of RGB hex color values for the gradient. You can use several different colors in one gradient fill.

The alphas parameter is also an array. This one holds the alpha values for the corresponding colors in the colors array. As with other alpha properties, each value can range from 0 to 100. There must be an alpha setting for each color in your colors array. For example, if you have three color elements, you must have three alpha elements.

The ratios parameter is an array that holds color distribution ratios for each color in the colors array. It sets the width of color that is rendered as a solid color before the transition to the next color begins. For example, you may want a span of solid red before the gradient starts to transition into orange. Values for these widths can range from 0 to 255. There must be a ratio value for each color in the colors array.

The matrix parameter is an object (like ratios is an array). It holds the matrixType, x, y, w, h, and r properties.

  • matrixType must be set as "box" for this format of the matrix object.

  • x and y are the coordinates for the position of the gradient's upper-left corner.

  • w is the width of the gradient.

  • h is the height of the gradient.

  • r is the rotation, in radians, of the gradient.

endFill()


The endFill() method closes the fill command for either beginFill() or beginGradientFill(). If you are drawing several shapes into a single movie clip, be sure to use the endFill() method before using another beginFill() or beginGradientFill() to change the fill color. Although it is not required, it is good practice to close every fill with the endFill() method.

The syntax is as follows:

myshape.endFill();


Drawing a Line

Now that you have been introduced to the methods of the Flash Drawing API, you can see how to put them together to draw a line. For each step of the process, an analogy to drawing with pen and paper is provided.

Here are the steps to draw a line:

  1. Create an empty movie clip (get a piece of paper):

    this.createEmptyMovieClip("myline", 100); 

  2. Create a style for the line (pick up a pen):

    myline.lineStyle(2,0x333366, 100); 

  3. Set the starting point for the line (set the pen down on the paper):

    myline.moveTo(0,0); 

  4. Set the end point for the line (drag the pen across the paper and stop):

    myline.lineTo(30,30); 

  5. Add as many lineTo statements as you want.

Drawing a Curved Line

Now that you've mastered drawing a straight line with the drawing API, it's time to throw you a curve. The process is much the same except that you use the curveTo() method instead of the lineTo() method.

Here are the steps to draw a curved line:

  1. Create an empty movie clip:

    this.createEmptyMovieClip("mycurve", 100); 

  2. Create a style for the curved line:

    mycurve.lineStyle(2,0x333366, 100); 

  3. Set a starting point for the curved line:

    mycurve.moveTo(100,100); 

  4. Set the end point (the curve's anchor point) and control point for the curve:

    mycurve.curveTo(200, 30, 300, 300); 

  5. Add as many curveTo statements as you want.

Drawing a Shape

Drawing a shape involves drawing a series of straight or curved lines with the last line ending at the same coordinates where the first line began (closing the shape).

Here are the steps to draw a shape:

  1. Create an empty movie clip:

    this.createEmptyMovieClip("myshape", 100);

  2. Create a style for the line and begin the fill:

    myshape.lineStyle(2,0x333366, 100); myshape.begingFill(0x003366, 80);

  3. Set the starting point:

    myshape.moveTo(2,2);

  4. Sequentially set the end points for each line or curve in the shape's line path:

    myshape.lineTo(88,2); myshape.lineTo(88,88); myshape.lineTo(2,88);

  5. Return to starting point to close the shape:

    myshape.lineTo(2,2);

  6. End the fill if there is one:

    myshape.endFill();

Tip

If you want a shape without a visible outline, omit the lineStyle.




Special Edition Using Macromedia Studio 8
Special Edition Using Macromedia Studio 8
ISBN: 0789733854
EAN: 2147483647
Year: 2003
Pages: 337

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net