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 endFill().

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();
}