Flash CS3 Documentation

ActionScript 2.0 Language Reference > ActionScript classes > MovieClip > beginGradientFill (MovieClip.beginGradientFill method)

beginGradientFill (MovieClip.beginGradientFill 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 MovieClip.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 MovieClip.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.

You can extend the methods and event handlers of the MovieClip class by creating a subclass.

Availability: ActionScript 1.0; Flash Player 6 - Additional parameters spreadMethod, interpolationMethod, and focalPointRatio added in Flash Player 8.

Parameters

fillType:String - Valid values are the string "linear" and the string "radial".

colors:Array - An array of RGB hexadecimal color values you can use in the gradient; for example; red is 0xFF0000, blue is 0x0000FF. You can specify up to 15 colors. For each color, ensure to specify a corresponding value in the alphas and ratios parameters.

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

ratios:Array - An array of color distribution ratios; valid values are 0 to 255. This value defines the percentage of the width where the color is sampled at 100%. Specify a value for each value in the colors parameter.

For example, for a linear gradient that includes two colors, blue and green, the following figure illustrates the placement of the colors in the gradient based on different values in the ratios array:

The values in the array must increase sequentially; for example, [0, 63, 127, 190, 255].

matrix:Object - A transformation matrix that can be in any one of three forms:

• A matrix object (supported by Flash Player 8 and later only), as defined by the flash.geom.Matrix class. The flash.geom.Matrix class includes a createGradientBox() method, which lets you conveniently set up the matrix for use with the beginGradientFill() method of MovieClip class. Adobe recommends that you use this form of matrix for Flash Player 8 and later.

  The following example uses the beginGradientFill() method with a matrix parameter of this type:

  import flash.geom.*
  
  this.createEmptyMovieClip("gradient_mc", this.getNextHighestDepth());
  with (gradient_mc) 
  {
      colors = [0xFF0000, 0x0000FF];
      fillType = "radial"
      alphas = [100, 100];
      ratios = [0, 0xFF];
      spreadMethod = "reflect";
      interpolationMethod = "linearRGB";
      focalPointRatio = 0.9;
      matrix = new Matrix();
      matrix.createGradientBox(100, 100, Math.PI, 0, 0);
      beginGradientFill(fillType, colors, alphas, ratios, matrix, 
          spreadMethod, interpolationMethod, focalPointRatio);
      moveTo(100, 100);
      lineTo(100, 300);
      lineTo(300, 300);
      lineTo(300, 100);
      lineTo(100, 100);
      endFill();
  }
  

  This code draws the following image onscreen:

  
  
  

• You can use the properties a, b, c, d, e, f, g, h, and 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
  
  

  Note: For Flash Player 8 and later, Adobe recommends that you define the matrix parameter in the form of a flash.geom.Matrix object (as described in the first item in this list).

  The following example uses the beginGradientFill() method with a matrix parameter of this type:

  this.createEmptyMovieClip("gradient_mc", this.getNextHighestDepth());
  with (gradient_mc) 
  {
      colors = [0xFF0000, 0x0000FF];
      fillType = "radial"
      alphas = [100, 100];
      ratios = [0, 0xFF];
      spreadMethod = "reflect";
      interpolationMethod = "linearRGB";
      focalPointRatio = 0.9;
      matrix = {a:200, b:0, c:0, d:0, e:200, f:0, g:200, h:200, i:1};
      beginGradientFill(fillType, colors, alphas, ratios, matrix, spreadMethod, 
  interpolationMethod, focalPointRatio);
      moveTo(100, 100);
      lineTo(100, 300);
      lineTo(300, 300);
      lineTo(300, 100);
      lineTo(100, 100);
      endFill();
  }
      
  

  This code draws the following image onscreen:

  
  
  

• An object with the following properties: 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.

  Note: For Flash Player 8 and later, Adobe recommends that you define the matrix parameter in the form of a flash.geom.Matrix object (as described in the first item in this list).

  The following example uses the beginGradientFill() method with a matrix parameter of this type:

  this.createEmptyMovieClip("gradient_mc", this.getNextHighestDepth());
  with (gradient_mc) 
  {
      colors = [0xFF0000, 0x0000FF];
      fillType = "radial"
      alphas = [100, 100];
      ratios = [0, 0xFF];
      spreadMethod = "reflect";
      interpolationMethod = "linearRGB";
      focalPointRatio = 0.9;
      matrix = {matrixType:"box", x:100, y:100, w:200, h:200, r:(45/180)*Math.PI};
      beginGradientFill(fillType, colors, alphas, ratios, matrix, 
          spreadMethod, interpolationMethod, focalPointRatio);
      moveTo(100, 100);
      lineTo(100, 300);
      lineTo(300, 300);
      lineTo(300, 100);
      lineTo(100, 100);
      endFill();
  }
  

  This code draws the following image onscreen:

  
  
  

spreadMethod:String [optional] - Added in Flash Player 8. Either "pad", "reflect," or "repeat," which controls the mode of the gradient fill. The default value is "pad".

For example, consider a simple linear gradient between two colors:

import flash.geom.*;
var fillType:String = "linear"
var colors:Array = [0xFF0000, 0x0000FF];
var alphas:Array = [100, 100];
var ratios:Array = [0x00, 0xFF];
var matrix:Matrix = new Matrix();
matrix.createGradientBox(20, 20, 0, 0, 0);
var spreadMethod:String = "pad";
this.beginGradientFill(fillType, colors, alphas, ratios, matrix, spreadMethod); 
this.moveTo(0, 0);
this.lineTo(0, 100);
this.lineTo(100, 100);
this.lineTo(100, 0);
this.lineTo(0, 0);
this.endFill();

This example uses "pad" for the spread method, so the gradient fill looks like the following:

If you used "reflect" for the spread method, the gradient fill would look like the following:

If you used "repeat" for the spread method, the gradient fill would look like the following:

interpolationMethod:String [optional] - Added in Flash Player 8. Either "RGB" or "linearRGB". With "linearRGB", the colors are distributed linearly in the gradient. The default value is "RGB".

For example, consider a simple linear gradient between two colors (with the spreadMethod parameter set to "reflect"). The different interpoliation methods affect the appearance as follows:

focalPointRatio:Number [optional] - Added in Flash Player 8. A number that controls the location of the focal point of the gradient. The value 0 means the focal point is in the center. The value 1 means the focal point is at one border of the gradient circle. The value -1 means the focal point is at the other border of the gradient circle. A value less than -1 or greater than 1 is rounded to -1 or 1. For example, the following image shows a focalPointRatio set to 0.75:

Example

The following code creates a spherical shade effect:

import flash.geom.*
this.createEmptyMovieClip("gradient_mc", this.getNextHighestDepth());
with (gradient_mc) 
    {
        fillType = "radial"
    colors = [0x000000, 0xFFFFFF];
        alphas = [50, 90];
        ratios = [0, 0xFF];
        spreadMethod = "pad";
        interpolationMethod = "RGB";
    focalPointRatio = 0.3;
    matrix = new Matrix();
    matrix.createGradientBox(100, 100, 0, 0, 0);
    beginGradientFill(fillType, colors, alphas, ratios, matrix, 
        spreadMethod, interpolationMethod, focalPointRatio);
    moveTo(0, 0);
    lineTo(0, 100);
    lineTo(100, 100);
    lineTo(100, 0);
    lineTo(0, 0);
    endFill();
}

This draws the following image (the image is scaled by 50%):

If your SWF file includes a version 2 component, use the version 2 components' DepthManager class instead of the MovieClip.getNextHighestDepth() method, which is used in this example.

See also

createGradientBox (Matrix.createGradientBox method), beginFill (MovieClip.beginFill method), endFill (MovieClip.endFill method), lineStyle (MovieClip.lineStyle method), lineTo (MovieClip.lineTo method), moveTo (MovieClip.moveTo method)

Flash CS3