# 4.10. Filling a Shape with a Gradient

## Problem

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

## Solution

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

## 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`

`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`

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.

// 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};

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

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

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.