Recipe 4.10 Filling a Shape with a Gradient

4.10.1 Problem

You want to draw a shape and fill it with a gradient at runtime.

4.10.2 Solution

Use the beginGradientFill( ) and endFill( ) methods to initiate and close a shape drawn at runtime.

4.10.3 Discussion

In a gradient fill, there is a graded change in colors. Flash supports linear gradients, in which one color fades into the next from left to right. Flash also supports radial gradients, in which the colors radiate out from a center point. You can initiate a gradient-filled shape using beginGradientFill( ) in the same way you initiate a solid-filled shape with beginFill( ). The difference is that the call to beginGradientFill( ) requires a more complex set of parameters:

gradientType

Either "linear" for a linear gradient, or "radial" for a radial gradient.

colors

An array of RGB values for the colors to use in the gradient. They are displayed in the gradient from left to right in a linear gradient, or from the center outward in a radial gradient.

alphas

An array of alpha values that correspond to the colors in the colors parameter array.

ratios

An array whose elements are numbers corresponding to the colors and alphas elements. The values in the ratios array indicate the point within the gradient at which each color is pure. The range of values for the ratios should be from 0 (leftmost point in a linear fill, or innermost point in a radial fill) to 255 (rightmost or outermost).

matrix

An object with the following properties:

matrixType

This value should always be "box".

x

The x coordinate of the bottom-left corner of the gradient.

y

The y coordinate of the bottom-left corner of the gradient.

width

The width of the gradient in pixels.

height

The height of the gradient in pixels.

r

The rotation of the gradient in radians (not degrees).

Here is an example that uses a linear gradient to fill a rectangle:

// Include the drawing methods, which are needed for the drawRectangle(  ) method.
#include "DrawingMethods.as"

// Define the width and height of the rectangle to be drawn and filled.
rectWidth  = 100;
rectHeight = 200;

// Create an empty clip into which we will draw the shape.
_root.createEmptyMovieClip("shape_mc", 1);
shape_mc.lineStyle(3, 0, 100);

// Create a colors array with RGB values for blue, green, and red.
colors = [0x0000FF, 0x00FF00, 0xFF0000];

// Create an alphas array in which the colors are 100% opaque.
alphas = [100, 100, 100];

// Create a ratios array where pure blue is at the left edge of the gradient, pure
// green is in the center, and pure red at the right edge.
ratios = [0, 127.5, 255];

// Create the matrix object. Set the x and y coordinates so that the bottom-left 
// corner of the gradient lines up with the bottom-left corner of the rectangle. Set
// the width and height of the gradient to match the rectangle.
matrix = {matrixType: "box", x: -rectWidth/2, y: -rectHeight/2, w: rectWidth, 
          h: rectHeight, r:0};

// Call beginGradientFill(  ) so that the rectangle will be 
// filled with a linear gradient.
shape_mc.beginGradientFill("linear", colors, alphas, ratios, matrix);

// Draw the rectangle with rounded corners (requires DrawingMethods.as).
shape_mc.drawRectangle(rectHeight, rectWidth, 10);

// End the fill.
shape_mc.endFill(  );

Note that the endFill( ) method is used to end a drawing operation begun with either beginFill( ) or beginGradientFill( ).

Here is an example of a radial, gradient fill used to fill an ellipse:

// Include the drawing methods, which are needed for the drawEllipse(  ) method.
#include "DrawingMethods.as"

// Define the width and height of the ellipse to be drawn and filled.
ellipseWidth  = 100;
ellipseHeight = 200;

_root.createEmptyMovieClip("shape_mc", 1);
shape_mc.lineStyle(3, 0x000000, 100);

// Create colors, alphas, and ratios arrays for white and black, both 100% opaque. 
// Pure white starts in the center and grades into pure black at the outside edge.
colors = [0xFFFFFF, 0x000000];
alphas = [100, 100];
ratios = [0, 255];

// Define the matrix object.
matrix = {matrixType: "box", x: -ellipseWidth/2, y: -ellipseHeight/2, 
          w: ellipseWidth, h: ellipseHeight, r:0};

// Begin the radial fill.
shape_mc.beginGradientFill("radial", colors, alphas, ratios, matrix);

// Draw the ellipse (requires DrawingMethods.as).
shape_mc.drawEllipse(ellipseWidth/2, ellipseHeight/2);

// End the fill.
shape_mc.endFill(  );

4.10.4 See Also

See Recipe 4.4 and Recipe 4.6 for implementations of the custom drawRectangle( ) and drawEllipse( ) methods. See Recipe 4.11 for details on creating a custom gradient fill.