MaskScaleFX Documentation
Author: Alex Uhlmann, Ben Jackson
Last Modified: 09/24/05 19:04:34
Summary
MaskScaleFX class:
MaskScaleFX Properties:
MaskScaleFX Methods:
version: Documentation not provided.
description:
Animates a mask using scale effects. 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. You can also send the animationStyle properties via the run() method or via the constructor. See the following examples. The scale effect needs to be specified as a string abbreviation. Available mask scale effects are:
"CENTER" = scales the mask proportional. "HORIZ" = horizontal, stretches the mask horizontally. Scales the _xscale property. "VERT" = vertical, stretches the mask vertically. Scales the _yscale property. "CUSTOM" = scales the mask according to the adjustmentObj parameter.
Example 1: Draw a circle and use it as a mask over movieclip mc.
var myEllipse:Ellipse = new Ellipse();
myEllipse.draw();
var myMaskScaleFX:MaskScaleFX = new MaskScaleFX(mc,myEllipse.movieclip);
myMaskScaleFX.animationStyle(2000,Circ.easeInOut);
myMaskScaleFX.run("CENTER",0,100);
Example 2: (Example .swf) Draw a star and use it as a mask over movieclip mc.
var myStar:Star = new Star();
myStar.draw();
var myMaskScaleFX:MaskScaleFX = new MaskScaleFX(mc,myStar.movieclip);
myMaskScaleFX.animationStyle(2000,Circ.easeInOut);
myMaskScaleFX.run("CENTER",500,0);
You can alter a predefined scale effect or you can define a custom scale effect via the adjustmentObj. The adjustmentObj of MaskScaleFX is an Object that contains six optional properties.
startX = Start point to begin animation. Coordinate point x. startY = Start point to begin animation. Coordinate point y. startXScale = Specifies the starting _xscale property. startYScale = Specifies the starting _yscale property. endXScale = Specifies the ending _xscale property. endYScale = Specifies the ending _yscale property.
Example 3: Modify example 1. Overwrite the center starting points.
var myEllipse:Ellipse = new Ellipse();
myEllipse.draw();
var myMaskScaleFX:MaskScaleFX = new MaskScaleFX(mc,myEllipse.movieclip);
myMaskScaleFX.animationStyle(2000,Circ.easeInOut);
myMaskScaleFX.run("CENTER",0,200,{
startX:mc._x+10,
startY:mc._y+10});
Example 4: (Example .swf) You can define an entire different scale animation, using the CUSTOM effect.
var myRect:Rectangle = new Rectangle();
myRect.draw();
myRect.movieclip._rotation = 45;
var myMaskScaleFX:MaskScaleFX = new MaskScaleFX(mc,myRect.movieclip);
myMaskScaleFX.animationStyle(2000,Circ.easeInOut);
myMaskScaleFX.run("CUSTOM",0,100,{
startX:340,
startY:350,
startXScale:200,
startYScale:200,
endXScale:450,
endYScale:450});
Note that the start and end values (0 and 100) in example 4 have no effect when using the CUSTOM scale effect.
Note that all examples above created a mask movieclip above the masked mc. If you want to manipulate physical movieclip properties of the masked movieclip, and at the same time animate the movieclip with a mask effect, the mask effect would be disturbed. Here is a workaround:
Example 5: (Example .swf) Using the Parallel class we use a mask effect and manipulate many physical properties of movieclip "mc" at the same time.
var myMoveOnQuadCurve:MoveOnQuadCurve = new MoveOnQuadCurve(mc,100,100,300,300,500,100); var myScale:Scale = new Scale(mc,50,50); var myRotation:Rotation = new Rotation(mc,360); var myColorTransform:ColorTransform = new ColorTransform(mc,0xff0000,50); //create the mask movieclip inside the movieclip mc to reflect all manipulations to mc. var mask_mc:MovieClip = mc.createEmptyMovieClip("mask_mc",1); var myRect:Rectangle = new Rectangle(mask_mc,50,50,100,50); myRect.draw(); //since the mask is inside mc you have to mask a movieclip inside mc. var myMaskScaleFX:MaskScaleFX = new MaskScaleFX(mc.inner_mc,myRect.movieclip,"CENTER"); var myParallel:Parallel = new Parallel(); myParallel.addChild(myMoveOnQuadCurve); myParallel.addChild(myScale); myParallel.addChild(myRotation); myParallel.addChild(myColorTransform); myParallel.addChild(myMaskScaleFX); myParallel.animationStyle(2000,Circ.easeInOut,"onCallback"); myParallel.animate(0,100); myListener.onCallback = function(source) { source.callback = "onCallback2"; source.animate(100,0); } myListener.onCallback2 = function(source) { source.callback = "onCallback"; source.animate(0,100); }
usage:
var myMaskScaleFX:MaskScaleFX = new MaskScaleFX(mc);
var myMaskScaleFX:MaskScaleFX = new MaskScaleFX(mc, mask_mc);
var myMaskScaleFX:MaskScaleFX = new MaskScaleFX(mc, mask_mc, effect);
var myMaskScaleFX:MaskScaleFX = new MaskScaleFX(mc, mask_mc, effect, duration);
var myMaskScaleFX:MaskScaleFX = new MaskScaleFX(mc, mask_mc, effect, duration, callback);
var myMaskScaleFX:MaskScaleFX = new MaskScaleFX(mc, mask_mc, effect, duration, easing, callback);
var myMaskScaleFX:MaskScaleFX = new MaskScaleFX(mc, mask_mc, effect, adjustmentObj);
var myMaskScaleFX:MaskScaleFX = new MaskScaleFX(mc, mask_mc, effect, adjustmentObj, duration);
var myMaskScaleFX:MaskScaleFX = new MaskScaleFX(mc, mask_mc, effect, adjustmentObj, duration, callback);
var myMaskScaleFX:MaskScaleFX = new MaskScaleFX(mc, mask_mc, effect, adjustmentObj, duration, easing, callback);
parameters:
(MovieClip) Movieclip to be masked.
(MovieClip) Movieclip to use as a mask.
(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: Animates a mask using scale effects from and to a specified amount in a specified time and easing equation. See class description for details. in global scope. If you want to use a mask effect on a movieclip which is manipulated during
usage:
myMaskScaleFX.run(effect, start, end);
myMaskScaleFX.run(effect, start, end, duration);
myMaskScaleFX.run(effect, start, end, duration, callback);
myMaskScaleFX.run(effect, start, end, duration, easing, callback);
myMaskScaleFX.run(effect, start, end, adjustmentObj);
myMaskScaleFX.run(effect, start, end, adjustmentObj, duration);
myMaskScaleFX.run(effect, start, end, adjustmentObj, duration, callback);
myMaskScaleFX.run(effect, start, end, adjustmentObj, duration, easing, callback);
parameters:
returns: void
description: similar to the run() method. Offers start and end parameters.
usage:
myMaskScaleFX.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: 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. _xscale and _yscale properties.
usage: myInstance.getStartValues();
returns: (Array) First value is _xscale, second is _yscale.
description: returns the targeted values of the current tween. _xscale and _yscale properties.
usage: myInstance.getEndValues();
returns: (Array) First value is _xscale, second is _yscale.
description: returns the current values of the current tween. _xscale and _yscale properties.
usage: myInstance.getCurrentValues();
returns: (Array) First value is _xscale, second is _yscale.
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.
usage:
myMaskScaleFX.addEventListener(event, listener);
myMaskScaleFX.addEventListener(event, listener, handler);
parameters:
returns: Void.
description: Removes a listener from a subscribed event.
usage:
myMaskScaleFX.removeEventListener(event, listener);
myMaskScaleFX.removeEventListener(event, listener, handler);
parameters:
returns: Void.
description: GDispatcher specific feature. Removes all listeners for a specific event, or for all events.
usage:
myMaskScaleFX.removeAllEventListeners();
myMaskScaleFX.removeAllEventListeners(event);
parameters:
returns: Void.
description: GDispatcher specific feature. Checks if a listener is already subscribed to a certain event.
usage:
myMaskScaleFX.eventListenerExists(event, listener);
myMaskScaleFX.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