MovieClip.beginFill( ) Method

	ActionScript for Flash MX: The Definitive Guide, 2nd Edition By Colin Moock

	Chapter 18. ActionScript Language Reference

MovieClip.beginFill( ) Method

Flash 6

starts drawing a solid-filled shape

mc.beginFill(RGB, alpha)

Arguments

RGB: An integer specifying the color of the shape, normally supplied in RGB hexadecimal triplet notation 0xRRGGBB, where RR, GG, and BB are two-digit hex numbers representing Red, Green, and Blue. For example, the hex integer 0xFF0000 indicates red. If RGB is omitted or undefined, no fill is drawn. For a complete discussion of RGB triplet notation, see the Color class.
alpha: An integer between 0 and 100 specifying the opacity (or, conversely, the transparency) of the shape as a percentage 0 is completely transparent, whereas 100 is completely opaque. Defaults to 100. Values above 100 are interpreted as 100; those below 0 are interpreted as 0.

Description

Part of the Drawing API, the beginFill( ) method starts drawing a new shape within mc, filled with a solid color of RGB and a transparency of alpha. The shape appears above any existing Drawing API content in mc but beneath all other content in mc (e.g., movie clips, shapes, text, and buttons placed at authoring time, or content attached at runtime via attachMovie( ), duplicateMovieClip( ), or createTextField( )). To draw a shape with a gradient fill, use beginGradientFill( ).

The beginFill( ) method is only one component of the shape drawing process. Think of the Drawing API as an old line plotter (like the kind used for architectural drawings) with an imaginary pen that can be lifted, dropped, or moved in order to draw lines and curves. To draw a filled shape, we must combine beginFill( ) with other MovieClip drawing methods, as follows:

Position the drawing pen with moveTo( ).
Start the shape with beginFill( ).
Draw the shape's outline with a series of lineTo( ) and/or curveTo( ) calls, the last of which must end at the point specified in the original moveTo( ) call.
Close the shape with endFill( ).

You can draw into an existing or empty movie clip with the Drawing API. Either use a movie clip created during authoring or use one created programmatically. To start with a fresh canvas, use MovieClip.createEmptyMovieClip( ). You can draw on the main timeline by specifying _root as the movie clip in which to draw, but drawing into a clip attached to the main timeline is the preferred approach.

The following code creates an empty movie clip, drawing_mc, and draws a red triangle in it, 100 pixels below and to the right of the clip's registration point:

// Create the clip this.createEmptyMovieClip("drawing_mc", 1); // Position the drawing pen var startX = 100; var startY = 100; drawing_mc.moveTo(startX , startY); // Start the shape drawing_mc.beginFill(0xFF0000, 100); // Draw the lines of the triangle drawing_mc.lineTo(startX+100, startY );    // Right 100 pixels drawing_mc.lineTo(startX+50, startY+100);  // Left 50 pixels, down 100 pixels drawing_mc.lineTo(startX, startY);         // Return to start point to close shape // End the shape drawing_mc.endFill();

The stroke defined by the most recent call to lineStyle( ) is automatically added to the shape. If lineStyle( ) has never been called, the shape is not stroked. For example, the following code draws the same red triangle, but with a 1-pixel black line around its perimeter. This time we specify positions using numeric literals only, rather than the variables startX and startY:

this.createEmptyMovieClip("drawing_mc", 1); // Indicate a 1-pixel black stroke for the shape drawing_mc.lineStyle(1, 0x000000); drawing_mc.moveTo(100, 100); drawing_mc.beginFill(0xFF0000, 100); drawing_mc.lineTo(200, 100); drawing_mc.lineTo(150, 200); drawing_mc.lineTo(100, 100); drawing_mc.endFill();

Even though Flash attempts to fix improperly specified shapes (e.g., a shape with no endFill( ) method), predictable results can be guaranteed only when these shape-drawing rules are observed:

The line around the shape's perimeter must have identical start and end points.
The shape must be formally closed with a call to endFill( ).
The beginFill( ) call must be preceded immediately by a moveTo( ) call that defines the starting point of the shape to be filled.

For example, the following code draws a line to the point (100, 100) and then draws our red triangle starting at that point. Before the triangle is drawn, moveTo( ) sets the starting point to (100, 100), even though the pen need not move. If the call to moveTo( ) is omitted or placed after the beginFill( ) call, Flash will not properly render the line and triangle.

this.createEmptyMovieClip("drawing_mc", 1); drawing_mc.lineStyle(1); drawing_mc.lineTo(100, 100);  // Draw the line // Now draw a triangle drawing_mc.moveTo(100, 100);  // Set the triangle's starting point. Required! drawing_mc.beginFill(0xFF0000); drawing_mc.lineTo(200, 100); drawing_mc.lineTo(150, 200); drawing_mc.lineTo(100, 100); drawing_mc.endFill();

Movie clips that contain content drawn via ActionScript behave exactly like movie clips with content created in the Flash MX authoring tool. For example, the _width and _height properties reflect content drawn at runtime, as do calls to getBounds( ) and hitTest( ). Furthermore, provided they're not completely transparent, shapes created with calls to beginFill( ) or beginGradientFill( ) are available as hit test areas for onRollover( ) and onPress( ) events or for use as a mask (see MovieClip.setMask( )).

To draw a fully contained hole within a shape, draw the shape and then the hole within a single beginFill( )/endFill( ) block. For example, the following code draws a "square doughnut":

this.lineStyle(3); this.beginFill(0xFF0000, 100);   // First square   this.moveTo(100, 100);   this.lineTo(200, 100);   this.lineTo(200, 200);   this.lineTo(100, 200);   this.lineTo(100, 100);       // Second square (the hole in the doughnut!)   this.moveTo(150, 150);   this.lineTo(170, 150);   this.lineTo(170, 170);   this.lineTo(150, 170);   this.lineTo(150, 150); this.endFill;

Note that bitmap fills are not directly supported by the Drawing API, but it is possible to achieve a similar effect by loading an image into a movie clip, then drawing a shape in a second clip and applying the second clip as a mask to the image clip. The image clip must be fully loaded before the mask is applied. For example:

// Create the mask clip this.createEmptyMovieClip("mask_mc", 2 );     // Draw the mask mask_mc.beginFill(0xFF0000); mask_mc.moveTo(100,100); mask_mc.lineTo(200,100); mask_mc.lineTo(200,200); mask_mc.lineTo(100,200); mask_mc.lineTo(100,100); mask_mc.endFill();     // Create a clip to hold the image to be masked this.createEmptyMovieClip("image_mc", 1); // Load image to be masked image_mc.loadMovie("image.jpg");     // Apply the mask once the image is loaded this.onEnterFrame = function () {   // Wait until the image is loaded   if (image_mc._width > 0 && image_mc._totalframes =  = image_mc._framesloaded) {     // The image has loaded, so apply the mask     this.setMask(mask_mc);     // Stop checking for the image to load     delete this.onEnterFrame;   } }

Example

The Drawing API does not include methods for drawing primitive shapes, such as rectangles, circles, or polygons. These must be custom-created by ActionScript developers, as shown in Example 18-2, which adds drawRect( ) and drawCircle( ) methods to all movie clips.

Example 18-2. Custom drawRect( ) and drawCircle( ) methods

// Method: MovieClip.drawRect() //   Desc: Draws a rectangle with optional fill. // Params: x          Horizontal position of rectangle's top-left corner. //         y          Vertical position of rectangle's top-left corner. //         w          Width of rectangle, in pixels. //         h          Height of rectangle, in pixels. //         RGB        Color of rectangle. //         alpha      Transparency of rectangle. MovieClip.prototype.drawRect = function (x, y, w, h, RGB, alpha) {   this.moveTo(x, y);   this.beginFill(RGB, alpha);   this.lineTo(x+w, y);   this.lineTo(x+w, y+h);   this.lineTo(x, y+h);   this.lineTo(x, y);   this.endFill; };     // drawRect() usage: // Set line width to 3 pixels. this.lineStyle(3); // Draw two overlapping rectangles with a transparency effect. Ooohhh... this.drawRect(300, 200, 50, 20, 0x0000FF, 100); this.drawRect(320, 210, 100, 120, 0x00FF00, 60);     // Method: MovieClip.drawCircle() //   Desc: Draws a circle outline (no fill) as a series of n curves. // Params: x          Horizontal position of circle's center. //         y          Vertical position of circle's center. //         segments   Number of curves used to draw the circle (defaults to 8). MovieClip.prototype.drawCircle = function (x, y, r, segments) {   // Variables to hold the end and control points of each curve.   var endX, endY, controlX, controlY;   // Use 8 segments if not specified.   if (segments =  = undefined) {     segments = 8;   }   // Calculate how many degrees are in each segment   // (360/segments), and convert that to radians.   var segmentAngle = (360/segments)/180 * Math.PI;   // Calculate the distance to the control point of each curve.   var controlDist = r / Math.cos(segmentAngle/2);   // Start drawing on the circle's positive X-axis.   this.moveTo(x+r, y);   // Draw the circle segments.   for (var i = 1; i <= segments; i++) {     // Calculate the end point of this curve.     endX = x + r * Math.cos(i*segmentAngle);     endY = y - r * Math.sin(i*segmentAngle);         // Calculate the control point of this curve.     controlX = x + controlDist * Math.cos(i*segmentAngle-segmentAngle/2);     controlY = y - controlDist * Math.sin(i*segmentAngle-segmentAngle/2);         // Draw this curve.     this.curveTo(controlX, controlY, endX, endY);   } };     // drawCircle() usage: // Outlined circle this.lineStyle(1); this.drawCircle(200, 200, 100); // Outlined and filled circle this.lineStyle(3, 0xFF0000); this.beginFill(0x0000FF); this.drawCircle(300, 250, 50); this.endFill();

Ric Ewing has posted more custom drawing methods at: http://www.formequalsfunction.com/downloads/drawmethods.html

Arguments

Description

Example

Example 18-2. Custom drawRect( ) and drawCircle( ) methods

See Also