ColorTransform Documentation
Author: Alex Uhlmann
Last Modified: 09/24/05 19:04:43
Summary
ColorTransform class:
ColorTransform Properties:
ColorTransform Methods:
version: Documentation not provided.
description:
Manipulates the colors of a movieclip or a number of movieclips with help of the ColorToolkit class, which extends the build-in Color class via the ColorCore class. ColorTransform accepts two kinds of color input values.
Way no. 1 "easy way": One offset and one percentage value.
A number in the range 0 to 16777215 (0xFFFFFF), representing the new RGB offsets of the movieclip. Can be a decimal integer or a hexadecimal integer. Another number to specify the color transformation percentages of the movieclip. Does not allow the manipulation of alpha components and of single color percentage values. Use "the complex way" for that.
Way no. 2 "complex way": A transform object like the one returned by Color.getTransform().
Takes one object with both, the offset and percentage values for a movieclip's red, green, blue and alpha components. The properties can be: ra, rb, ga, gb, ba, bb, aa, ab. Take a look into the Color class of your Flash manual for more information about the properties of the Color transformObject or get Colin Moock's ASDG for an in depth discussion. The transformationObject doesn't need to be complete. If you haven't specified some of the eight properties, ColorTransform will retrieve the missing color properties from the current color of your movieclip. Way no. 2 offers more complex color manipulations than way no. 1, since you have access to all single offset and percentage values of the movieclip including the alpha components.
You can specify the duration, easing equation and callback properties either with setting the properies directly or with the animationStyle() method like it is used in de.alex_uhlmann.animationpackage.drawing.
Example 1a: Way no. 1
Example 1b: Way no. 2var myCT:ColorTransform = new ColorTransform(mc); myCT.animationStyle(3000,Quad.easeOut,"onCallback"); myCT.run(0xff0000,50);
var myCT:ColorTransform = new ColorTransform(mc);
myCT.animationStyle(3000,Quad.easeOut,"onCallback");
var brightRed:Object = {ra:50,rb:255,ga:50,gb:0,ba:50,bb:0,aa:100,ab:0};
myCT.run(brightRed);
is just another syntax forvar brightRed:Object = {ra:50,rb:255,ga:50,gb:0,ba:50,bb:0,aa:100,ab:0};
Example 2: The alternative way is shorter. The same like above in one line.var brightRed:Object = new Object(); brightRed.ra = 50; brightRed.rb = 255; brightRed.ga = 50; brightRed.gb = 0; brightRed.ba = 50; brightRed.bb = 0; brightRed.aa = 100; brightRed.ab = 0;
Example 3: You can also specify the properties via the constructor. This might come in handy if you're using the Sequence or Parallel class. Take a look at their class documentations for more information. The animate() method and its start and end paremeters might also be useful.new ColorTransform(mc).run(0xff0000,50,3000,Quad.easeOut,"onCallback");
Example 4: By default, the start value of your animation is the current value. You can explicitly define the start values either via the setStartValues or run method or via the constructor. Here is one example for the constructor solution. This also might come in handy using composite classes, like Sequence.var myColorTransform:ColorTransform = new ColorTransform(mc,0xff0000,50,2000,Circ.easeInOut,"onCallback"); myColorTransform.animate(0,100);
var myCT:ColorTransform = new ColorTransform(mc,[0x0000ff,20,0xff0000,20],3000,Quad.easeOut); myCT.run();
Example 5: Transform the color of a movieclip to an opaque red tone using default animationStyle properties (1 second, using linear easing).
var myCT:ColorTransform = new ColorTransform(mc); myCT.run(0xff0000,0);
Example 6: (Example .swf) Colorize a movieclip to red with 50 percentage and then to green with 50 percentage in 6 seconds using Quad easing. Note that I nullify the callback property, which would call the onCallback method again.
var myCT:ColorTransform = new ColorTransform(mc);
myCT.animationStyle(3000,Quad.easeOut,"onCallback");
myCT.run(0xff0000,50);
myListener.onCallback = function() {
myCT.callback = null;
myCT.run(0x00ff00,50);
}
Example 7: Use the transformationObject to fade a movieclip from opaque red to opaque green in 3 seconds.
var myCT:ColorTransform = new ColorTransform(mc);
myCT.animationStyle(3000);
//Note that you don't have to specify all of the possible properties in the tansformationObject.
//ColorTransform will retrieve the missing properties from your current movieclip.
var red:Object = {ra:0,rb:255,ga:0,gb:0,ba:0,bb:0};
var green:Object = {ra:0,rb:0,ga:0,gb:255,ba:0,bb:0};
myCT.setStartValues([red]);
myCT.setEndValues([green]);
myCT.run();
Example 8: Do the same like in example 7 just use way no. 1. Notice that I listen to all events from ColorTransform (onStart, onUpdate and onEnd). Inside the handler methods you can access the color values of the current state of the animation. There are two ways to accomblish this. One way is to ask the "value" property of the eventObject send by EventDispatcher. See addEventListener documentation. Another way is to ask the getStartValues, getCurrentValues and getEndValues methods of ColorTransform. This way you can access the color values depending on how you initialized ColorTransform. See getStartValues documentation for more information. Notice that in this example I modify the result of getCurrentValues method inside the onUpdate handler in order to trace hexadecimal numbers instead of decimal numbers.
var myCT:ColorTransform = new ColorTransform(mc);
myCT.animationStyle(3000);
myCT.setStartValues([0xff0000,0]);
myCT.setEndValues([0x00ff00,0]);
myCT.addEventListener("onStart",this);
myCT.addEventListener("onUpdate",this);
myCT.addEventListener("onEnd",this);
myCT.run();
function onStart(eventObject:Object){
trace("onStart "+eventObject.value);
trace("getStartValues "+myCT.getStartValues());
}
function onUpdate(eventObject:Object){
trace("onUpdate "+eventObject.value);
var currentValues:Array = myCT.getCurrentValues();
var rgbNumber:Number = currentValues[0];
var hexrgb:String = rgbNumber.toString(16);
trace("getCurrentValues "+hexrgb);
}
function onEnd(eventObject:Object){
trace("onEnd "+eventObject.value);
trace("getEndValues "+myCT.getEndValues());
}
var mcs:Array = new Array(mc1,mc2,mc3);
var myCT:ColorTransform = new ColorTransform(mcs);
myCT.setOptimizationMode(true);
myCT.animationStyle(3000);
var red:Object = {ra:0,rb:255,ga:0,gb:0,ba:0,bb:0};
var green:Object = {ra:0,rb:0,ga:0,gb:255,ba:0,bb:0};
myCT.setStartValues([red]);
myCT.setEndValues([green]);
myCT.run();
usage:
var myCT:ColorTransform = new ColorTransform(mc);
var myCT:ColorTransform = new ColorTransform(mc, rgb, percentage);
var myCT:ColorTransform = new ColorTransform(mc, rgb, percentage, duration);
var myCT:ColorTransform = new ColorTransform(mc, rgb, percentage, duration, callback);
var myCT:ColorTransform = new ColorTransform(mc, rgb, percentage, duration, easing, callback);
var myCT:ColorTransform = new ColorTransform(mc, transformationObject);
var myCT:ColorTransform = new ColorTransform(mc, transformationObject, duration);
var myCT:ColorTransform = new ColorTransform(mc, transformationObject, duration, callback);
var myCT:ColorTransform = new ColorTransform(mc, transformationObject, duration, easing, callback);
var myCT:ColorTransform = new ColorTransform(mc, values);
var myCT:ColorTransform = new ColorTransform(mc, values, duration, callback);
var myCT:ColorTransform = new ColorTransform(mc, values, duration, easing, callback);
var myCT:ColorTransform = new ColorTransform(mcs);
var myCT:ColorTransform = new ColorTransform(mcs, rgb, percentage);
var myCT:ColorTransform = new ColorTransform(mcs, rgb, percentage, duration);
var myCT:ColorTransform = new ColorTransform(mcs, rgb, percentage, duration, callback);
var myCT:ColorTransform = new ColorTransform(mcs, rgb, percentage, duration, easing, callback);
var myCT:ColorTransform = new ColorTransform(mcs, transformationObject);
var myCT:ColorTransform = new ColorTransform(mcs, transformationObject, duration);
var myCT:ColorTransform = new ColorTransform(mcs, transformationObject, duration, callback);
var myCT:ColorTransform = new ColorTransform(mcs, transformationObject, duration, easing, callback);
var myCT:ColorTransform = new ColorTransform(mcs, values);
var myCT:ColorTransform = new ColorTransform(mcs, values, duration, callback);
var myCT:ColorTransform = new ColorTransform(mcs, values, duration, easing, callback);
parameters:
(MovieClip) Movieclip to animate.
(Array) Array of Movieclips to animate.
(Number) Duration of animation in milliseconds or frames. Default is milliseconds.
(Object) Easing equation in Robert Penner style. Default equation is Linear.easeNone. www.robertpenner.com/easing/
(String) Function to invoke after animation. See AnimationCore class.
description: manipulates the color of a movieclip in a specified time and easing equation. See class documentation.
usage:
myCT.run();
myCT.run(rgb, percentage);
myCT.run(rgb, percentage, duration);
myCT.run(rgb, percentage, duration, callback);
myCT.run(rgb, percentage, duration, easing, callback);
myCT.run(transformationObject);
myCT.run(transformationObject, duration);
myCT.run(transformationObject, duration, callback);
myCT.run(transformationObject, duration, easing, callback);
myCT.run(values, duration);
myCT.run(values, duration, callback);
myCT.run(values, duration, easing, callback);
parameters:
returns: void
description: similar to the run() method. Offers start and end parameters.
usage:
myCT.animate(start, end);
parameters:
returns: void
description: jumps to a specific step of the animation and stays there.
usage:
instance.goto(percentage);
parameters:
returns: void
description: set the animation style properties for your animation. Notice that if your easing equation supports additional parameters you can send those parameters with the easing parameter in animationStyle. You have to send an Array as easing parameter. The first element has to be the easing equation in Robert Penner style. The following parameters can be your additional parameters. i.e.:
See also "Customizable easing equations" in readme for more information.var myRotation:Rotation = new Rotation(mc); myRotation.animationStyle(2000,[Back.easeOut,4]); myRotation.run(360);
usage:
myInstance.animationStyle(duration);
myInstance.animationStyle(duration, callback);
myInstance.animationStyle(duration, easing, callback);
parameters:
returns: Void.
description: rounds animation results to integers. (might be usefull for animating pixelfonts). Default is false.
usage:
myInstance.roundResult(rounded);
parameters:
true rounds the result. Animates with integers. Less accuracy. false animates with floating point numbers.returns: Void.
description: Flash does not guaranteed that time-based tweening will reach the end value(s) of your animation. By default AnimationPackage guarantees that the end value(s) will be reached. The forceEnd method allows you to disable this guarantee and only accept the values from your easing equation. In certain situations this can lead to a smoother ending of the animation. Notice that in frame-based tweening the end value(s) will always be reached.
usage:
myInstance.forceEnd(forceEndVal);
parameters:
true or false.returns: Void.
description: returns the optimization mode. See setOptimizationMode for more information.
usage: getOptimizationMode();
returns: Boolean
description:
Allows to explicitly remove parts of the animation that don't change during
the animation.
This can add additional performance to your animation. Note that
setting this method to true has side effects. If all start and end values match,
the animation won't start and will immediatly invoke an onEnd event.
The order of values returned by getStartValue(s), getCurrentValue(s),
getEndValue(s) and the value property of the eventObject returned
by EventDispatcher might change if you set this method to true. You can
still retrieve the parts of the animation that are actually animated
if you access the Animator instance of your animation class via
myAnimator. Ask myInstance.myAnimator.setter to retrieve
all currently animated parts of the animation. See Animator
documentation. Of cource, if you know your input values you would
probably look at them.
Note that the AnimationCore class offers a static setOptimizationModes method (note the last "s" at the end) that allows you to remove parts of 'all' your animations that don't change during the animation.
usage:
myInstance.setOptimizationMode(optimize);
parameters:
returns: Void.
description: returns the current tween mode used by the instance. Please check with AnimationCore.setTweenModes for more information.
usage: getTweenMode();
returns: String that specifies the tween mode. Either AnimationCore.INTERVAL or AnimationCore.FRAMES.
description: sets the current tween mode used by the instance. Please check with AnimationCore.setTweenModes for more information.
usage: setTweenMode();
parameters:
returns: true if setting tween mode was successful,
false if not successful.
description: returns the current duration mode used by the instance. Please check with AnimationCore.setTweenModes for more information.
usage: getDurationMode();
returns: String that specifies the duration mode. Either AnimationCore.MS or AnimationCore.FRAMES.
description: sets the current duration mode used by the instance. Please check with AnimationCore.setTweenModes for more information.
usage: setDurationMode();
parameters:
returns: true if setting duration mode was successful,
false if not successful.
description: stops the animation if not locked..
usage: myInstance.stop();
returns: true if instance was successfully stopped.
false if instance could not be stopped, because it was locked.
description: pauses the animation if not locked. Call resume() to continue animation.
usage: myInstance.pause();
parameters:
returns: true if instance was successfully paused.
false if instance could not be paused, because it was locked.
description: continues the animation if not locked.
usage: myInstance.resume();
returns: true if instance was successfully resumed.
false if instance could not be resumed, because it was locked.
description: locks the animation to prevent pausing, resuming and stopping. Default is unlocked.
usage: myInstance.lock();
returns: Void.
description: unlocks the animation to allow pausing, resuming and stopping. Default is unlocked.
usage: myInstance.unlock();
returns: Void.
description: checks if the instance is currently animated.
usage: myInstance.isTweening();
returns: true if instance is tweening,
false if instance is not tweening.
description: returns the original, starting values of the current tween. The values returned depend on how you used/started the ColorTransform class. If you used one offset value (i.e. in form of a hexadecimal number) and one percentage number to initialize ColorTransform, the offset and percentage numbers will be returned by this method. If you've used a transformObject to initialize ColorTransform, the values returned are all properties of the transformObject of the Color class. They are returned in an array of the following order: From 0 - 7: ra, rb, ga, gb, ba, bb, aa, ab. Take a look into the Color class of your Flash manual for more information about the properties of the Color transformObject or get Colin Moock's ASDG for an in depth discussion.
usage: myInstance.getStartValues();
returns: (Array)
description: sets the original, starting values of the current tween. See class documentation.
usage: myInstance.setStartValues(startValues);
parameters:
returns: Boolean, indicates if the assignment was performed.
description: returns the targeted values of the current tween. The values returned depend on how you used/started the ColorTransform class. See getStartValues for more information.
usage: myInstance.getEndValues();
returns: (Array)
description: sets the targeted value of the current tween. See class documentation.
usage: myInstance.setEndValues(endValues);
parameters:
returns: Boolean, indicates if the assignment was performed.
description: returns the current values of the current tween. The values returned depend on how you used/started the ColorTransform class. See getStartValues for more information.
usage: myInstance.getCurrentValues();
returns: (Array)
description: returns the current state of the animation in percentage. Especially usefull in combination with goto().
usage: myInstance.getCurrentPercentage();
returns: Number
description: returns the elapsed time or frames since the current tween started tweening.
usage: myInstance.getDurationElapsed();
returns: Number
description: returns the remaining time or frames since the current tween started tweening.
usage: myInstance.getDurationRemaining();
returns: Number
description: Subscribe to a predefined event. The following standard EventDispatcher events are broadcasted
onStart, broadcasted when animation starts.
onUpdate, broadcasted when animation updates.
onEnd, broadcasted when animation ends.
The even object returned, contains the following properties:
type (String) event broadcasted.
target (Object) event source.
value (Array) values to animate. See getStartValues and class documentation.
usage:
myCT.addEventListener(event, listener);
myCT.addEventListener(event, listener, handler);
parameters:
returns: Void.
description: Removes a listener from a subscribed event.
usage:
myCT.removeEventListener(event, listener);
myCT.removeEventListener(event, listener, handler);
parameters:
returns: Void.
description: GDispatcher specific feature. Removes all listeners for a specific event, or for all events.
usage:
myCT.removeAllEventListeners();
myCT.removeAllEventListeners(event);
parameters:
returns: Void.
description: GDispatcher specific feature. Checks if a listener is already subscribed to a certain event.
usage:
myCT.eventListenerExists(event, listener);
myCT.eventListenerExists(event, listener, handler);
parameters:
returns: true if event exists on listener.
false if event doesn't exist on listener.
description: returns a unique ID of the instance. Usefull for associative arrays.
usage: myInstance.getID();
returns: Number
description: returns the name of the class.
usage: myInstance.toString();
returns: String