SuperFades reference guide

SuperFades class

Author Bob Donderwinkel
Website http://www.bdontwerp.nl/ | blog www.bdontwerp.nl/blog
Date August 7, 2004

Availability
Flash Player 7.

Version 1.1

Description
The SuperFades class lets perform smooth and powerfull color, tint and alpha fades on a MovieClip, using any given duration and framerate. You must use the constructor new SuperFades() to create a SuperFades object before calling its methods.

To download SuperFades, get more feedback and for any questions about superFades visit my blog:

Property summary for the SuperFades class
SuperFades.fps
SuperFades.updateAfterEvent
SuperFades.target

Method summary for the SuperFades class
SuperFades.alphaFade()
SuperFades.brightnessFade()
SuperFades.callFade()
SuperFades.colorTintFade()
SuperFades.clearFade()
SuperFades.fullColorFade()
SuperFades.getHex()
SuperFades.getRGB()
SuperFades.getTransform()
SuperFades.hexToRGB()
SuperFades.invertFade()
SuperFades.rgbToHex()
SuperFades.setBrightness()
SuperFades.setFadeCall()
SuperFades.setRGB()
SuperFades.setTransform()
SuperFades.setTint()
SuperFades.transformFade()

Event summary for the SuperFades class
SuperFades.onFadeStart
SuperFades.onFadeEnd

Constructor for the SuperFades class

Usage
new SuperFades(target_mc:MovieClip, framerate:Number, UpdateAfterEvent:Boolean) : SuperFades

Parameters
target_mc The instance name of a movie clip.
framerate (Optional, default: 24) specifies the framerate in with witch the fade should be displayed.
UpdateAfterEvent (Optional, default: false) specifies whether or not to use updateAfterEvent after each fading step. Using updateAfterEvent can give performance issues, especially dealing with multiple fades at the same time.

Returns
A reference to a SuperFades object.

Description
Constructor; creates a new SuperFades object for the MovieClip specified by the target_mc parameter. You can then use the methods of that SuperFades object to perform a certain fade on the target MovieClip, according to a given framerate.

Example
The following example import the SuperFades class, creates a SuperFades object called my_SF for the movie clip my_mc, which with a framerate of 30 and the use of updateAfterEvent after each fading step. Then an alpha fade to 0% is called on my_SF, with a duration of 500 milliseconds.

import com.bdontwerp.SuperFades;

var my_SF:SuperFades = new SuperFades(my_mc, 30, true);
my_SF.alphaFade(0, 500);

Note: The fps and updateAfterEvent properties can also be set in a specific fade call, temporarily overwritting those properties for that specific fade.

my_SF.alphaFade(0, 500, {fps:20, updateAfterEvent:false});

Property Summary for SuperFades

SuperFades.fps

Usage
my_SF.fps:Number

Description
The framerate used for fading. This property can be set through the SuperFades constructor, or directly on a SuperFades object

Example
The first example sets a new framerate through the constructor, the second on a SuperFades object.

var my_SF=new SuperFades(my_mc, 30);
my_SF.fps=24;

Note: fps can also be set in a specific fade call, temporarily overwritting this property for that specific fade.

SuperFades.updateAfterEvent

Usage
my_SF.updateAfterEvent:Boolean

Description
This property determens whether or not to use updateAfterEvent after each fading step. UpdateAfterEvent updates the screen independent of the main timeline framerate. Default value is false. This property can be set through the SuperFades constructor, or directly on a SuperFades object

Example
The first example sets updateAfterEvent through the constructor (false), the second on a SuperFades object (true).

var my_SF=new SuperFades(my_mc, 30, false);
my_SF.updateAfterEvent=true;

Note: updateAfterEvent can also be set in a specific fade call, temporarily overwritting this property for that specific fade.
Note: updateAfterEvent can cause performance issues, especially when dealing with multiple fades on multiple SuperFades Objects at the same time.

SuperFades.target

Usage
my_SF.target:MovieClip

Description
Property which determens the MovieClip to perform the fades upon. This property is automaticly set in the SuperFades constructor, and can be overwritten afterwards.

Example
This example initializes a SuperFades object with my_mc as the target, overwrites that with my_other_mc, and performs a full blue color fade on that MovieClip.

var my_SF=new SuperFades(my_mc, 30, false);
my_SF.target=my_other_mc;
my_SF.fullColorFade(0x0000FF);

Note: Setting a new target in the middle of a running fade, will cancel that fade.

Method Summary for SuperFades

SuperFades.alphaFade()

Usage
my_SF.alphaFade(alphaLevel:Number, fadeTime:Number, override:Object) : Void

Parameters
alphaLevel The alpha level to fade to.
fadeTime The duration of the fade.
override Optional, an object with fps and/or updateAfterEvent as properties, overriding the main framerate and updateAfterEvent settings of the SuperFades object.

Description
Method; fades an SuperFades instance to the specified alpha level, within a given duration. Starting point is the current alpha level of the target movieclip.

Returns
Nothing.

Example
This first example fades a movieclip, my_mc, to 50 % transparency in 500 miliseconds and with an framerate of 30. The second example fades with an extra override object, setting the framerate to 24, and updateAfterEvent to true..

var my_SF:SuperFades = new SuperFades(my_mc, 30);
my_SF.alphaFade(50, 500);
// with override object.
my_SF.alphaFade(50, 500, {fps:24, updateAfterEvent:true});

SuperFades.brightnessFade()

Usage
my_SF.brightnessFade(brightnesss:Number, fadeTime:Number, override:Object) : Void

Parameters
brightness The brightness of the image to fade to in %.
fadeTime The duration of the fade.
override Optional, an object with fps and/or updateAfterEvent as properties, overriding the main framerate and updateAfterEvent settings of the SuperFades object.

Description
Method; fades a SuperFades object to a certain brightness, within a given duration. The brighness is measured from -100 to 100, where 0 is the orginal startingpoint. The brightness will only appear on MovieClips which contain multicolor images or photos.

Returns
Nothing.

Example
This example fades a movieclip, my_mc, to a brightness of 75 procent in 500 miliseconds.

var my_SF:SuperFades = new SuperFades(my_mc, 30);
my_SF.brightnessFade(75, 500);

SuperFades.callFade()

Usage
my_SF.callFade(callID:String) : Void

Parameters
callID The id for the stored fade to be called

Description
Method; calles a fade stored with setFadeCall().

Returns
Nothing.

Example
This first example stores a brightnessFade (fade to 50& in 500 milliseconds), with the id "fadeCall1", and calls it with callFade.

var my_SF:SuperFades = new SuperFades(my_mc, 30);
my_SF.setFadeCall("fadeCall1", "brightnessFade", 50, 500);

// call the stored fade
my_SF.callFade("fadeCall1");

Note: See also setFadeCall().

SuperFades.colorTintFade()

Usage
my_SF.colorTintFade(0xRRGGBB:Number, fadeTime:Number, override:Object) : Void

Parameters
0xRRGGBB The hexadecimal or RGB color shade to fade to. RR, GG, and BB each consist of two hexadecimal digits that specify the offset of each color component. The 0x tells the ActionScript compiler that the number is a hexadecimal value.
fadeTime The duration of the fade.
override Optional, an object with fps and/or updateAfterEvent as properties, overriding the main framerate and updateAfterEvent settings of the SuperFades object.

Description
Method; specifies an RGB color tint for an SuperFades object to fade to. The tint will only appear on MovieClips which contain multicolor images or photos. Use fullColorFade() to fade a MovieClip to a full color.

Returns
Nothing.

Example
This example fades a movieclip, my_mc, to a red color shade (0xff0000) in 500 milliseconds.

var my_SF:SuperFades = new SuperFades(my_mc, 30);
my_SF.colorTintFade(0xff0000, 500);

SuperFades.clearFade()

Usage
my_SF.clearFade(fadeTime:Number, override:Object) : Void
my_SF.clearFade(Void) : Void

Parameters
fadeTime The duration of the fade.
override Optional, an object with fps and/or updateAfterEvent as properties, overriding the main framerate and updateAfterEvent settings of the SuperFades object.

Description
Method; clears any fade which has been run on a SuperFades object. This brings the target MovieClip back to it's orginal colorTransformObject, being{ra:100, rb:0, ga:100, gb:0, ba:100, bb:0, aa:100, ab:0}. If fadeTime parameter is supplied the clear will be performed as a fade within that duration, if no parameters are supplied, it clear will be instant

Returns
Nothing.

Example
The first example clears a movieclip, my_mc in 500 milliseconds with 24 frames per second. The seconds makes the clear instantly .

var my_SF:SuperFades = new SuperFades(my_mc, 30);
my_SF.setTint(0xff0000);

// clears the current applied color within 500 milliseconds, with a framerate of 21.
my_SF.clearFade(500, {framerate:21});
// clears instantly
my_SF.clearFade();

Note: This also clears any color values set on the target MovieClip with Color.

SuperFades.fullColorFade()

Usage
my_SF.fullColorFade(0xRRGGBB:Number, fadeTime:Number, override:Object) : Void

Description
Method; specifies an RGB color for an SuperFades instance to fade to. This color will appear as a shade, which will only be visibly on MovieClips if they contain an image or photo.

Returns
Nothing.

Example
This example fades a movieclip, my_mc, to a red color shade (0xff0000) in 500 miliseconds.

var my_SF:SuperFades = new SuperFades(my_mc, 30);
my_SF.fullColorFade(0xff0000, 500);

SuperFades.getHex()

Usage
my_SF.getHex(Void) : String

Parameters
None.

Returns
A String that represents the hexidecimal RGB numeric value currently apllied to a SuperFades object.

Description
Method; returns the color value currently apllied to a SuperFades object, as a string and in hexideciaml notation..

Example
The following code retrieves the RGB value for the SuperFades object my_SF, converts the value to a hexadecimal string, and assigns it to the myValue variable.

var my_SF:SuperFades = new SuperFades(my_mc);
my_SF.setRGB(0xff9933); // set the color
trace(trace.getHex()); // traces ff9933

Note: If you call getRGB() on a SuperFades object which is in the middle of a fade, the returned value will not present the final color.

SuperFades.getRGB()

Usage
my_SF.getRGB(Void) : Number

Parameters
None.

Returns
A number that represents the RGB numeric value currently apllied to a SuperFades object.

Description
Method; returns the numeric color value currently apllied to a SuperFades object. This method is a direct port of Color' getRGB() method.

Example
The following code retrieves the RGB value for the SuperFades object my_SF, converts the value to a hexadecimal string, and assigns it to the myValue variable. To see this code work, add a movie clip instance to the Stage, and give it the instance name my_mc:

var my_SF:SuperFades = new SuperFades(my_mc);
my_SF.setRGB(0xff9933); // set the color
var colorValue:String = my_SF.getRGB().toString(16);
trace(colorValue); // traces ff9933

Note: If you call getRGB() on a SuperFades object which is in the middle of a fade, the returned value will not present the final color.

SuperFades.getTransform()

Usage
my_SF.getTransform(Void) : Object

Parameters
None.

Returns
An object whose properties contain the current offset and percentage values for the color value currently apllied to a SuperFades object.. This method is a direct port of Color' getTransform() method.

Description
Method; returns the transform value currently apllied to a SuperFades object.

Example
The following example gets the transform object, and then sets new percentages for colors and alpha of my_mc relative to their current values. To see this code work, place a multicolored movie clip on the Stage with the instance name my_mc. Then place the following code on Frame 1 in the main Timeline and select Control > Test Movie:

var my_SF:SuperFades = new SuperFades(my_mc);
var myTransform:Object = my_SF.getTransform();
myTransform = { ra: 50, ba: 50, aa: 30};
my_color.setTransform(myTransform);

Note: If you call getTransform() on a SuperFades object which is in the middle of a fade, the returned value will not present the final transform object.
Note: For description of the parameters for a color transform object, see SuperFades.setTransform().

SuperFades.hexToRGB()

Usage
SuperFades.hexToRGB(0xRRGGBB:Number) : Object

Parameters
0xRRGGBB The hexadecimal color to be converted.

Returns
An object with r(red), g(green) and b(blue) properties.

Description
Method; A static method wich converts a hexadecimal color to an object with the corresponding red, green and blue properties.

Example
This example converts the color value 0xAB67F3 to corresponding r,g,b values

var rgbObj=SuperFades.hexToRGB(0xAB67F3);
trace(rgbObj.r); // traces '171'
trace(rgbObj.g); // traces '103'
trace(rgbObj.b); // traces 243''

SuperFades.invertFade()

Usage
my_SF.invertFade( fadeTime:Number, override:Object) : Void

Description
Method; Inverts the color of a SuperFades object. This will only be visible on MovieClips which contain multicolor images or photos.

Returns
Nothing.

Example
This example inverts a movieclip, my_mc, in 500 miliseconds.

var my_SF:SuperFades = new SuperFades(my_mc, 30);
my_SF.invertFade( 500);

SuperFades.rgbToHex()

Usage
SuperFades.rgbToHex(red:Number, green:Number, blue:Number) : Object

Parameters
red The hexadecimal color to be converted.
green The hexadecimal color to be converted.
blue The hexadecimal color to be converted.

Returns
An object with r(red), g(green) and b(blue) properties.

Description
Method; A static method wich converts red, green and blue values to their corresponding hexadecimal color value.

Example
This example converts the color value 0xAB67F3 to corresponding r,g,b values

var hexColor=SuperFades.rgbToHex(171, 103, 243);
trace(hexColor.toString(16)); // traces AB67F3

SuperFades.setBrightness()

Usage
my_SF.setBrightness(brightness:Number) : Void

Parameters
brightness The percentage of brightness to be apllied in %.

Description
Method; specifies an brightness in % for a SuperFades object to be applied. This can be a value from -100 (darkest) to 100 (brightest).

Returns
Nothing.

Example
This example sets the brightness for the MovieClip my_mc to 50%.

var my_SF:SuperFades = new SuperFades(my_mc, 30);
my_SF.setBrightness(50);

Note: Calling setBrightness() on a SuperFades object will cancel any running fade on that object.

SuperFades.setFadeCall()

Usage
my_SF.setFadeCall(callID:String, fadeMethod:String, fadeParameters, duration:Number, override:Object) : Void

Parameters
callID The id used to later call the stored fade, with callFade().
fadeMethod The fading method to use.
fadeParameters The parameter to fade with.
override Optional, an object with fps and/or updateAfterEvent as properties, overriding the main framerate and updateAfterEvent settings of the SuperFades object.

Description
Method; stores a fade, allong with the needed parameters, for later usage.

Returns
Nothing.

Example
This first example stores a brightnessFade (fade to 50& in 500 milliseconds), with the id "fadeCall1", and calls it with callFade.

var my_SF:SuperFades = new SuperFades(my_mc, 30);
my_SF.setFadeCall("fadeCall1", "brightnessFade", 50, 500);

// call the stored fade
my_SF.callFade("fadeCall1");

Note: See also callFade().

SuperFades.setRGB()

Usage
my_SF.setRGB(0xRRGGBB:Number) : Void

Parameters
0xRRGGBB The hexadecimal or RGB color to be set. RR, GG, and BB each consist of two hexadecimal digits that specify the offset of each color component. The 0x tells the ActionScript compiler that the number is a hexadecimal value.

Description
Method; specifies an RGB color for a SuperFades object to be set. This method is a direct port of Color' setRGB() method.

Returns
Nothing.

Example
This example sets the RGB color value 0xFF0000 (red) for the movie clip my_mc.

var my_SF:SuperFades = new SuperFades(my_mc);
my_SF.setRGB(0xFF0000); // my_mc turns red

Note: Calling setRGB() on a SuperFades object will cancel any running fade on that object.

SuperFades.setTransform()

Usage
my_SF.setTransform(colorTransformObject:Object) : Void

Returns
Nothing.

Description
Method; sets color transform information for a SuperFades object. The colorTransformObject parameter is a generic object that you create from the new Object constructor. It has parameters specifying the percentage and offset values for the red, green, blue, and alpha (transparency) components of a color, entered in the format 0xRRGGBBAA. This method is a direct port of Color' setTransform() method.

The parameters for a color transform object correspond to the settings in the Advanced Effect dialog box and are defined as follows:

ra is the percentage for the red component (-100 to 100).
rb is the offset for the red component (-255 to 255).
ga is the percentage for the green component (-100 to 100).
gb is the offset for the green component (-255 to 255).
ba is the percentage for the blue component (-100 to 100).
bb is the offset for the blue component (-255 to 255).
aa is the percentage for alpha (-100 to 100).
ab is the offset for alpha (-255 to 255).

You create a colorTransformObject parameter as follows:

var myColorTransform:Object = new Object();
myColorTransform.ra = 50;
myColorTransform.rb = 244;
myColorTransform.ga = 40;
myColorTransform.gb = 112;
myColorTransform.ba = 12;
myColorTransform.bb = 90;
myColorTransform.aa = 40;
myColorTransform.ab = 70;

You can also use the following syntax to create a colorTransformObject parameter:

var myColorTransform:Object = { ra: 50, rb: 244, ga: 40, gb: 112, ba: 12, bb: 90, aa: 40, ab: 70}

Example
This example creates a new SuperFades object for a target MovieClip, my_mc, creates a generic object called myColorTransform with the properties defined above, and uses the setTransform() method to pass the colorTransformObject to theSuperFades object.

// Create a color object called my_color for the target my_mc
var my_SF:SuperFades = new SuperFades(my_mc);
// Create a color transform object called myColorTransform, and sets initial values.
var myColorTransform:Object = { ra: 50, rb: 244, ga: 40, gb: 112, ba: 12, bb: 90, aa: 40, ab: 70};
// applies the color transform object to the SuperFades instance
my_SF.setTransform(myColorTransform);

Note: Calling setTransform() on a SuperFades object will cancel any running fade on that object.

SuperFades.setTint()

Usage
my_SF.setTint(0xRRGGBB:Number) : Void

Parameters
0xRRGGBB The hexadecimal color to be set as a tint. RR, GG, and BB each consist of two hexadecimal digits that specify the offset of each color component. The 0x tells the ActionScript compiler that the number is a hexadecimal value.

Description
Method; specifies an RGB color tint for a SuperFades object to be set. This tint will appear as a shade over a MovieClip, and will only be noticable on MovieClips with multicolored content.

Returns
Nothing.

Example
This example gives the MovieClip my_mc a green tint.

var my_SF:SuperFades = new SuperFades(my_mc);
my_SF.setTint(0x00FF00);

Note: Calling setTint() on a SuperFades object will cancel any running fade on that object.

SuperFades.transformFade()

Usage
my_SF.transformFade(transformObject:Object, fadeTime:Number, override:Object) : Void

Parameters
colorTransformObject An object created with the new Object constructor. This instance of the Object class must have the following properties that specify color transform values: ra, rb, ga, gb, ba, bb, aa, ab. See SuperFades.setTransform() for more details how to use a colorTransformObject.
fadeTime The duration of the fade.
override Optional, an object with fps and/or updateAfterEvent as properties, overriding the main framerate and updateAfterEvent settings of the SuperFades object.

Description
Method; fades an SuperFades to the supplied transformObject, within a given duration. The colorTransformObject parameter is a generic object that you create from the new Object constructor. It has parameters specifying the percentage and offset values for the red, green, blue, and alpha (transparency) components of a color, entered in the format 0xRRGGBBAA..

Returns
Nothing.

Example
This example fades a movieclip, my_mc, to a transformObject with some non specific values in 500 milliseconds.

var my_SF:SuperFades = new SuperFades(my_mc, 30);
my_SF.transformFade({ra:50, rb:244, ga:40, gb:112, ba:12, bb:90, aa:40, ab:70} , 500);

Event Summary for SuperFades

SuperFades.onFadeStart

Usage

listenerObject:Object = new Object();
listenerObject.onFadeStart = function(eventObject:Object){
...
}
SuperFadesInstance.addEventListener("onFadeStart", listenerObject) ;

Description
Event; broadcast when a SuperFades object has started a fade. Inside the onFade callback method an eventObject with two properties 'target' and 'fadeType', which give the SuperFades object on which the fade was performed, and the type of fade.

Example
This example fades a SuperFades object, my_SF, to 50% transparency in 500 milliseconds, and traces the target MovieClip and type of fade when finished.

var my_SF=new SuperFades(my_mc, 30);
var fadeListener:Object=new Object();

fadeListener.onFadeStart = function(eventObj){
trace(eventObj.target); // traces "my_mc"
trace(eventObj.fade); // traces "alphaFade"
}

my_SF.addEventListener("onFadeStart", fadeListener);
my_SF.alphaFade(50, 500);

SuperFades.onFadeEnd

Usage

listenerObject:Object = new Object();
listenerObject.onFadeEnd = function(eventObject:Object){
...
}
SuperFadesInstance.addEventListener("onFadeEnd", listenerObject) ;

Description
Event; broadcast when a SuperFades object has finished a fade. Inside the onFade callback method an eventObject with two properties 'target' and 'fadeType', which give the SuperFades object on which the fade was performed, and the type of fade.

Example
This example fades a SuperFades object, my_SF, to 50% transparency in 500 milliseconds, and traces the target MovieClip and type of fade when finished.

var my_SF=new SuperFades(my_mc, 30);
var fadeListener:Object=new Object();

fadeListener.onFadeEnd = function(eventObj){
trace(eventObj.target); // traces "my_mc"
trace(eventObj.fade); // traces "alphaFade"
}

my_SF.addEventListener("onFadeEnd", fadeListener);
my_SF.alphaFade(50, 500);