# MovieClip.beginGradientFill()

#### Availability

Flash Player 6.

#### Usage

`my_mc``.beginGradientFill (``fillType``,` `colors``,` `alphas``,` `ratios``,` `matrix``)`

#### Parameter

`fillType` Either the string "`linear`" or the string "`radial`".

`colors` An array of RGB hex color values to be used in the gradient (for example, red is 0xFF0000, blue is 0x0000FF, and so on).

`alphas` An array of alpha values for the corresponding colors in the `colors` array; valid values are 0-100. If the value is less than 0, Flash uses 0. If the value is greater than 100, Flash uses 100.

`ratios` An array of color distribution ratios; valid values are 0-255. This value defines the percentage of the width where the color is sampled at 100 percent.

`matrix` A transformation matrix that is an object with either of the following two sets of properties.

- `a`, `b`, `c`, `d`, `e`, `f`, `g`, `h`, `i`, which can be used to describe a 3 x 3 matrix of the following form:

    a 	b 	c
    d 	e 	f
    g 	h i

The following example uses a `beginGradientFill` method with a `matrix` parameter that is an object with these properties.

    _root.createEmptyMovieClip( "grad", 1 );
                  with ( _root.grad )

                  {

                  colors = [ 0xFF0000, 0x0000FF ];
                  alphas = [ 100, 100 ];
                  ratios = [ 0, 0xFF ];
                  matrix = { a:200, b:0, c:0, d:0, e:200, f:0, g:200, h:200, i:1 };
                  beginGradientFill( "linear", colors, alphas, ratios, matrix );
                  moveto(100,100);
                  lineto(100,300);
                  lineto(300,300);
                  lineto(300,100);
                  lineto(100,100);
                  endFill();

                  }

If a `matrixType` property does not exist then the remaining parameters are all required; the function fails if any of them are missing. This matrix scales, translates, rotates, and skews the unit gradient which is defined at (-1,-1) and (1,1).

- `matrixType`, `x`, `y`, `w`, `h`, `r`.

The properties indicate the following: `matrixType` is the string "`box`", `x` is the horizontal position relative to the registration point of the parent clip for the upper left corner of the gradient, `y` is the vertical position relative to the registration point of the parent clip for the upper left corner of the gradient, `w` is the width of the gradient, `h` is the height of the gradient, and `r` is the rotation in radians of the gradient.

The following example uses a `beginGradientFill` method with a `matrix` parameter that is an object with these properties.

    _root.createEmptyMovieClip( "grad", 1 );
                  with ( _root.grad )

                  {

                  colors = [ 0xFF0000, 0x0000FF ];
                  alphas = [ 100, 100 ];
                  ratios = [ 0, 0xFF ];
                  matrix = { matrixType:"box", x:100, y:100, w:200, h:200, r:(45/180)*Math.PI };
                  beginGradientFill( "linear", colors, alphas, ratios, matrix );
                  moveto(100,100);
                  lineto(100,300);
                  lineto(300,300);
                  lineto(300,100);
                  lineto(100,100);
                  endFill();
                  }

If a `matrixType` property exists then it must equal `"box"` and the remaining parameters are all required. The function fails if any of these conditions are not met.

#### Returns

Nothing.

#### Description

Method; indicates the beginning of a new drawing path. If the first parameter is `undefined,` or if no parameters are passed, the path has no fill. If an open path exists (that is if the current drawing position does not equal the previous position specified in a `moveTo` method), and it has a fill associated with it, that path is closed with a line and then filled. This is similar to what happens when you call the `endFill` method.

This method fails if any of the following conditions exist:

- The number of items in the `colors`, `alphas`, and `ratios` parameters are not equal.
- The `fillType` parameter is not `"linear"` or `"radial"`.
- Any of the fields in the object for the `matrix` parameter are missing or invalid.

#### Example

The following code uses both methods to draw two stacked rectangles with a red-blue gradient fill and a 5-pt. solid green stroke.

    _root.createEmptyMovieClip("goober",1);
    with ( _root.goober )
    {
    	colors = [ 0xFF0000, 0x0000FF ];
    	alphas = [ 100, 100 ];
    	ratios = [ 0, 0xFF ];
    	lineStyle( 5, 0x00ff00 );
    	matrix = { a:500,b:0,c:0,d:0,e:200,f:0,g:350,h:200,i:1};
    	beginGradientFill( "linear", colors, alphas, ratios, matrix );
    	moveto(100,100);
    	lineto(100,300);
    	lineto(600,300);
    	lineto(600,100);
    	lineto(100,100);
    	endFill();
    	matrix = { matrixType:"box", x:100, y:310, w:500, h:200, r:(0/180)*Math.PI };
    	beginGradientFill( "linear", colors, alphas, ratios, matrix );
    	moveto(100,310);
    	lineto(100,510);
    	lineto(600,510);
    	lineto(600,310);
    	lineto(100,310);
    	endFill();
    }

#### See also

`MovieClip.beginFill()`, `MovieClip.endFill()`, `MovieClip.lineStyle()``,` `MovieClip.lineTo()`, `MovieClip.moveTo()`