Color Class | ActionScript for Flash MX: The Definitive Guide, Second Edition

	ActionScript for Flash MX: The Definitive Guide, 2nd Edition By Colin Moock

	Chapter 18. ActionScript Language Reference

Color Class

Flash 5

control over movie clip color values

Constructor

new Color(target)

Arguments

target: A string or reference indicating the path to the movie clip or document level whose color will be controlled by the new object (references are converted to paths when used in a string context).

Methods

getRGB( ): Retrieve the current offset values for Red, Green, and Blue.
getTransform( ): Retrieve the current offset and percentage values for Red, Green, Blue, and Alpha.
setRGB( ): Assign new offset values for Red, Green, and Blue, while reducing percentage values to 0.
setTransform( ): Assign new offset and/or percentage values for Red, Green, Blue, and Alpha.

Description

We use objects of the Color class to dictate the color and transparency of a movie clip or main movie programmatically. Once we've created an object of the Color class for a specific target, we can then invoke the methods of that Color object to affect its target's color and transparency. That is, there is no color property used to manipulate a movie clip's color; instead we create a Color object that targets the desired movie clip. For example, suppose we have a clip instance named ball that we want to color red. We first make a Color object with a target of ball, and store it in the variable ballColor. Then we can use ballColor.setRGB( ) to assign ball the color red, as follows:

var ballColor = new Color("ball"); ballColor.setRGB(0xFF0000);  // Pass setRGB( ) the hex value for red

For a custom example that adds a color-setting method directly to the MovieClip class, see the Color.setRGB( ) method.

The preceding example provides color control for simple applications. But to handle more complex scenarios, we need to know more about how color is represented in Flash. Every individual color displayed in a movie clip is defined by four separate components: Red, Green, Blue, and Alpha (or transparency). These four components are combined in different amounts to generate each color we see on screen. The amount of Red, Green, Blue, and Alpha in a given color is described as a number between 0 and 255. The higher the value of Red, Green, or Blue, the more each of those colors contributes to the final color. However, remember that computer color is additive, not subtractive like paint, so higher values tend to be brighter, not darker. If all three RGB components are equal, the result is a shade of gray; if they are all 0, the result is black; if they are all 255, the result is white. The higher the value of Alpha, the more opaque the final color will be. (A color with an Alpha of 0 is completely transparent, and a color with an Alpha of 255 is completely opaque.)

For example, pure red is described by the following values:

Red: 255, Green: 0, Blue: 0, Alpha: 255

whereas a partially transparent red might have the values:

Red: 255, Green: 0, Blue: 0, Alpha: 130

For the purposes of this discussion, we adopt the so-called RGB triplet notation (R: red, G: green, B: blue) when talking about color values. Although ActionScript doesn't support decimal RGB triplets such as (255, 0, 255), it does support the hexadecimal equivalent form 0xRRGGBB, where RR, GG, and BB are each two-digit hex numbers representing Red, Green and Blue. For example, the RGB triplet (R:51, G:51, B:102) is equivalent to the hexadecimal value 0x333366.

We'll also adopt the so-called RGBA quadlet notation (R: red, G: green, B: blue, A: alpha) for convenience during the following discussion. Note that although there is no color property for a movie clip, clips do have an _alpha property that represents the alpha channel setting.

The initial Red, Green, Blue, and Alpha values for each color in a movie clip are set in the Flash authoring tool using the Color Mixer panel. (In the Color Mixer panel, Alpha is shown as a percentage, not a number from 0 to 255.) To alter all the colors in a movie clip via ActionScript, we make universal adjustments (known as transformations) to the Red, Green, Blue, and Alpha components of the clip's color. Transformations can be applied at authoring time via the Property inspector (Flash MX) or Effect panel (Flash 5).

We have two means of setting transformations for each color component:

We can set the percentage of the component's original value to a number between -100 and 100. For example, we can say, "set all red used in this clip to 80% of its original value." Although negative percentages aren't meaningful in isolation, they are used to calculate the final transformation as shown later in this Description.
We can specify an amount to offset the component's original value. The offset is a number between -255 and 255. For example, we can say, "add 20 to all blue values in this clip," or, using a negative number, we can say, "subtract 30 from all blue values in this clip."

The final value of a color in a transformed clip is determined by combining its original (author-time) color component values with the transformation percentages and offsets set through the Color object, as follows:

R = originalRedValue   * (redTransformPercentage/100)   + redTransformOffset G = originalGreenValue * (greenTransformPercentage/100) + greenTransformOffset B = originalBlueValue  * (blueTransformPercentage/100)  + blueTransformOffset A = originalAlphaValue * (alphaTransformPercentage/100) + alphaTransformOffset

If no transformations have been performed through ActionScript, the initial transformation percentage for each component defaults to 100, while the initial offset defaults to 0.

Let's look at how color transformations work with a practical example. Suppose that a clip contains an opaque red triangle (R:255, G:0, B:0, A:255) and an opaque green circle (R:0, G:255, B:0, A:255). Also suppose that we apply a universal transformation to the clip, setting the percentage of Green to 50, the percentage of Alpha to 80, and the offset of Blue to 100, but leaving the other offsets and percentages at their defaults (0 or 100). Here's how the universal transformation affects our red triangle:

R =  = 255 * (100/100) +   0 =  = 255            // No change to Red G =  =   0 *  (50/100) +   0 =  = 0              // Green reduced to 50% B =  =   0 * (100/100) + 100 =  = 100            // Blue offset by 100 A =  = 255 *  (80/100) +   0 =  = 204            // Alpha reduced to 80%

The final transformed red triangle has the color value (R:255, G:0, B:100, A:204).

Now here's how the transformation affects our green circle:

R =  =   0 * (100/100) +   0 =  = 0              // No change to Red G =  = 255 *  (50/100) +   0 =  = 127.5          // Green reduced to 50% B =  =   0 * (100/100) + 100 =  = 100            // Blue offset by 100 A =  = 255 *  (80/100) +   0 =  = 204            // Alpha reduced to 80%

The final transformed green circle has the color value (R:0, G:127.5, B:100, A:204).

To apply our hypothetical color transformations to a real clip, we use a Color object as we saw earlier. To set a clip's universal color offset and percentage values we use the setRGB( ) and setTransform( ) methods (see the entries for those methods for example code). Conversely, to examine the current color transformations of a clip, we use the getRGB( ) and getTransform( ) methods. The Color class methods can produce animated color effects, such as fade-ins, fade-outs, and tinting. Furthermore, because we can apply tints to each clip instance individually, the Color class provides a very efficient way to create diverse graphics with minimal assets. For example, we can create a scene full of balloons from a single movie clip that we colorize and tint in myriad ways, as shown under the Example heading that follows.

Usage

Here are some points of interest for Color objects:

Changing the color of a movie clip with a Color object will cause author-time tweens applied to the clip to cease functioning.
Setting the _alpha property of a clip affects the clip's Alpha percentage, as reflected by the aa property of the object returned by getTransform( ).
Color transformations do not affect the background color of a movie or a movie clip. They apply only to solid shapes placed on the Stage. To change the background color, first fill the background with a shape and then colorize that shape.
Manual color transformations can be applied to movie clips in the Flash MX authoring tool via the Property inspector and in Flash 5 via the Effect panel (Window Panels Effect). All such transformations are reflected in the properties of the object returned by getTransform( ). The authoring tool serves as an excellent means of viewing and choosing color transformations.

Example

The first example shows how to generate a series of randomly colored balloon movie clips, based on an existing clip called balloon:

var balloonColor;     // Loop to make 20 duplicates of the clip balloon for (var i = 0; i < 20; i++) {   // Duplicate this balloon   balloon.duplicateMovieClip("balloon" + i, i);       // Position this balloon on stage   this["balloon" + i]._x = Math.floor(Math.random() * 550);   this["balloon" + i]._y = Math.floor(Math.random() * 400);       // Create a Color object for this balloon   balloonColor = new Color(this["balloon" + i]);   // Randomly assign this balloon's color using the setRGB() method   balloonColor.setRGB(Math.floor(Math.random() * 0xFFFFFF)); }     // We don't need the Color object anymore, so delete it delete balloonColor;

By setting the Red, Green, and Blue offsets to the same value, we can effectively brighten or darken a movie clip. For example, the following code darkens myClip:

brightness = new Color("myClip");  brightnessTransform = new Object(); brightnessTransform.rb = -30;  brightnessTransform.bb = -30; brightnessTransform.gb = -30; brightness.setTransform(brightnessTransform);

This last example adds a new method, MovieClip.doMouseFade( ), that brightens and darkens a clip according to the mouse position:

MovieClip.prototype.doMouseFade = function () {   var brightness = new Color(this);   var brightnessTransform = new Object();       this.onMouseMove = function () {     var brightnessAmount = -255 + (_level0._xmouse / Stage.width) * 510;     brightnessTransform.rb = brightnessAmount;     brightnessTransform.bb = brightnessAmount;     brightnessTransform.gb = brightnessAmount;     brightness.setTransform(brightnessTransform);     updateAfterEvent();   } }     box.doMouseFade();