How Do I Draw with Code?: Chapter 12 - ActionScript 3.0 Quick Reference Guide
Pages: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13

## 12.10 Creating a Gradient Fill

### Problem

You want to create a gradient fill to replace solid colors when filling drawn shapes.

### Solution

Use the `beginGradientFill()` and `endFill()` methods of the `Graphics` class.

### Discussion

To create a gradient fill, you must first understand its component parts. First is the type of gradient: linear or radial. Next is a set of parallel arrays (arrays with an equal number of objects in the same order) that represent up to 15 colors in the gradient. These arrays contain the color values themselves, their alpha values, and the amount of the total gradient each color is meant to occupy, respectively. Finally, an optional matrix can be used to rotate, scale, skew, or offset the location of the gradient. Here is the gradient fill creation segment:

```var gradType:String = GradientType.LINEAR;
var colors:Array = [0x000000, 0x000000];
var alphas:Array = [1, 0];
var ratios:Array = [0, 255];
var matrix:Matrix = new Matrix();

The color values use standard hexadecimal notation. The alpha values are expressed in decimal notation of percent values between 0 and 1. However, the ratio of color quantity, is expressed as an increasing set of numbers between 0 and 255, representing their position along the gradient.

An equally spaced two-color gradient, such as this example uses, is created using the two extreme values of 0 and 255. Both colors are full at the ends of the gradient, and mix together in the middle. Adding another equally spaced third color would require a ratio array of 0, 127, and 255. Finally, to skew a gradient toward one dominant color, you might use a ratio array of 0 and 127. This would show the first color in one third of the gradient and mix over to the second color that occupied two thirds of the gradient.

The last part of creating a gradient is the optional matrix to manipulate its position, scale, and angle. You create the matrix with the standard use of the `new` keyword, but editing it can get complex. Fortunately, you have a special method of the `Matrix` class specifically for this purpose, `createGradientBox()`. The eponymous method accepts a width, height, rotation, horizontal translation, and vertical translation to manipulate the gradient for you.

This example uses a width and height that matches the size of the rectangle itself, and no horizontal or vertical translation is specified, so the full gradient is visible. With a rotation of 0, the gradient moves from first color to last color, in a left to right direction.

Finally, these values are passed into the `beginGradientFill()` method (used in place of the `beginFill()` method of prior recipes) in the order discussed: gradient type, color array, alpha array, ratio array, and matrix. The result is a smooth gradient from opaque black to transparent.

```var sp:Sprite = new Sprite();