SuperShape Documentation

SuperShape Documentation

Author: Alex Uhlmann
Last Modified: 09/24/05 19:03:28

Summary

SuperShape class:

SuperShape Properties:

SuperShape Methods:

SuperShape class

version: Documentation not provided.

description:

SuperShape allows you to draw many different shapes based on the Superformula developed by Johan Gielis. The Superformula used by SuperShape is one simple equation that can generate a vast diversity of natural shapes. It produces everything from simple triangles and pentagons, to stars, spirals and petals. More information on the Superformula: Paul Bourke. Based on the first Flash implementations of Flashforum members, Especially based on e2e4 and i++ contributions. If you specify a movieclip as first parameter, the shape will be drawn inside this movieclip. If you omit the mc parameter, the class will create a new movieclip in _root.apContainer_mc.

Here is an application that may help you testing different parameters of SuperShape: (Testing application)

Example 1: Some shape manipulations. (Example .swf)

			var mySuperShape:SuperShape = new SuperShape(300,300);
			//like the MovieClip lineStyle(), lineStyle in AnimationPackage also omits the line if you call it without a parameter.
			mySuperShape.lineStyle();
			mySuperShape.fillStyle(0xff0000);
			
			mySuperShape.animationStyle(3000,Sine.easeInOut,"onStart");
			mySuperShape.setPreset("burst");
			
			mySuperShape.addPreset({label:"rounded Polygon", data:{m:5, n1:1, n2:1.7, n3:1.7, range:2, scaling:2, detail:1000}});
			
			mySuperShape.morph("burst","rounded Polygon");
			
			myListener.onStart = function() {	
				mySuperShape.callback = "onRoundStar";
				mySuperShape.animateProps(["n1"],[0.09]);
			}
			myListener.onRoundStar = function() {	
				mySuperShape.callback = "onN1Out";
				mySuperShape.animateProps(["n1"],[1]);
			}
			myListener.onN1Out = function() {	
				mySuperShape.callback = "onN2In";
				mySuperShape.animateProps(["n2"],[6]);
			}
			myListener.onN2In = function() {	
				mySuperShape.callback = "onN2Out";
				mySuperShape.animateProps(["n2"],[1]);
			}
			myListener.onN2Out = function() {		
				mySuperShape.callback = "onN3In";
				mySuperShape.animateProps(["n2","n3"],[6,6]);
			}
			myListener.onN3In = function() {
				mySuperShape.callback = null;
				mySuperShape.animateProps(["n2","n3"],[1,1]);
			}

Example 2: Some other shape manipulations. (Example .swf)

			var mySuperShape:SuperShape = new SuperShape(300,300);
			mySuperShape.lineStyle(3,0xff0000);
			mySuperShape.fillStyle();
			mySuperShape.animationStyle(3000,Sine.easeInOut,"on01");
			mySuperShape.addPreset({label:"0", data:{m:10, n1:0, n2:1.7, n3:0, range:2, scaling:2, detail:1000}});
			mySuperShape.addPreset({label:"1", data:{m:10, n1:1, n2:1.7, n3:1.7, range:2, scaling:2, detail:1000}});
			mySuperShape.morph("0","1");
			myListener.on01 = function() {	
				mySuperShape.callback = "on23";
				mySuperShape.addPreset({label:"2", data:{m:10, n1:3, n2:1.3, n3:8, range:2, scaling:2, detail:1000}});
				mySuperShape.morph("1","2");
			}
			myListener.on23 = function() {	
				mySuperShape.callback = "on34";
				mySuperShape.addPreset({label:"3", data:{m:10, n1:.2, n2:1.3, n3:8, range:2, scaling:2, detail:1000}});
				mySuperShape.morph("2","3");
			}
			myListener.on34 = function() {	
				mySuperShape.callback = "on45";
				mySuperShape.addPreset({label:"4", data:{m:10, n1:1.1, n2:0.5, n3:8, range:2, scaling:2, detail:1000}});
				mySuperShape.morph("3","4");
			}
			myListener.on45 = function() {	
				mySuperShape.callback = "on56";
				mySuperShape.addPreset({label:"5", data:{m:10, n1:0.5, n2:0.1, n3:16.4, range:2, scaling:2, detail:1000}});
				mySuperShape.morph("4","5");
			}
			myListener.on56 = function() {		
				mySuperShape.callback = "on67";
				mySuperShape.addPreset({label:"6", data:{m:10, n1:0.5, n2:0.1, n3:1, range:2, scaling:2, detail:1000}});
				mySuperShape.morph("5","6");
			}
			myListener.on67 = function() {
				mySuperShape.callback = null;
				mySuperShape.addPreset({label:"7", data:{m:10, n1:0.5, n2:0.1, n3:.1, range:2, scaling:2, detail:2000}});
				mySuperShape.morph("6","7");
			}

Reader Exercise: Do some shape manipulations via the gradientStyle method.

usage:

var mySuperShape:SuperShape = SuperShape();

var mySuperShape:SuperShape = SuperShape(x, y, m, n1, n2, n3, range, scaling, detail);

var mySuperShape:SuperShape = SuperShape(mc, x, y, m, n1, n2, n3, range, scaling, detail);

parameters:

mc (MovieClip) existing movieclip to draw in.
x (Number) X position of the drawing. Center point.
y (Number) Y position of the drawing. Center point.
m (Number) 0 - 20. Defaults to 4.
n1 (Number) 0 - 10000. Defaults to 1.
n2 (Number) 0 - 10000. Defaults to 1.
n3 (Number) 0 - 10000. Defaults to 1.
range (Number) 0.5 - 20PI. Defaults to 12.
scaling (Number) 1 - 5. Defaults to 200.
detail (Number) 1000 - 50000. Defaults to 10000.

SuperShape Properties:

m_def

(Number)(static) default property. Defaults to 4.

n1_def

(Number)(static) default property. Defaults to 1.

n2_def

(Number)(static) default property. Defaults to 1.

n3_def

(Number)(static) default property. Defaults to 1.

range_def

(Number)(static) default property. Defaults to 12.

scaling_def

(Number)(static) default property. Defaults to 200.

detail_def

(Number)(static) default property. Defaults to 10000.

m

(Number) Property of Superformula.

n1

(Number) Property of Superformula.

n2

(Number) Property of Superformula.

n3

(Number) Property of Superformula.

range

(Number) Property of Superformula.

scaling

(Number) Property of Superformula.

detail

(Number) Property of Superformula.

animateFromCenter

(Boolean) Causes the shape to be animated from the center. Default is set to false.

movieclip

(MovieClip)(read only) Movieclip that contains the drawing.

lineThickness

(Number) Outline thickness.

lineRGB

(Number) Outline color of the drawing as hex number.

lineAlpha

(Number) Outline transparency (alpha).

fillRGB

(Number) Fill color of the drawing.

fillAlpha

(Number) Fill transparency.

SuperShape Methods:

draw

description: Draws supershape.

usage:

mySuperShape.draw();

mySuperShape.draw(start, end);

parameters:

start (Number) optional. value to beginn the drawing.
end (Number) optional. value to end the drawing.

returns: Void.

animate

description: Draws an animated supershape.

Example 1: (Example .swf) draw a circle backwards with default parameters.

				var mySuperShape:SuperShape = new SuperShape(275,200);
				mySuperShape.setPreset("circle");
				mySuperShape.fillStyle(0xff0000);	
				mySuperShape.animate(100,0);

Example 2: (Example .swf) draw a more complex star with custom parameters.

				var mySuperShape:SuperShape = new SuperShape(200, 200, 19/6, .3, .3, .3, 12, 2, 5000);
				mySuperShape.fillStyle();
				mySuperShape.animationStyle(10000);
				mySuperShape.animate(0,100);

usage:

mySuperShape.animate(start, end);

parameters:

start (Number) Value to beginn the drawing.
end (Number) Value to end the drawing.

returns: Void.

animateProps

description: Animates a property or properies specified as a String in propArr to the specified number value or values in endArr.

Example 1: (Example .swf) manipulate the border of a circle.

					var mySuperShape:SuperShape = new SuperShape(275,200);
					mySuperShape.lineStyle(6);
					mySuperShape.fillStyle(0xff0000);
					mySuperShape.animationStyle(6000,Circ.easeOut,"onDetailOut");
					mySuperShape.setPreset("circle");
					mySuperShape.animateProps(["detail"],[3]);
					myListener.onDetailOut = function() {
						mySuperShape.animationStyle(6000,Circ.easeIn,null);
						mySuperShape.animateProps(["detail"],[1000]);
					}

See class documentation for another example.

usage:

mySuperShape.animateProps(propArr, endArr);

parameters:

propArr (Array) Array of Strings. See class properties for available properties.
endArr (Array) Array of Numbers.

returns: Void.

morph

description: Morphs a shape from a specified preset to another. To read about presets, take a look at addPreset() and setPreset(). See class documentation for an example.

usage:

mySuperShape.morph(presetStart, presetEnd);

parameters:

presetStart (String) preset label to start mophing.
presetEnd (String) preset label to moph to.

returns: Void.

addPreset

description: Adds a new preset object to SuperShape. Overwrites an existing preset with the same label. A preset is an object that contains parameters that represent a shape.

Example 1: (Example .swf) Add the the german military logo as a preset and draw it with default parameters.

				var mySuperShape:SuperShape = new SuperShape(275,200);
				mySuperShape.addPreset({label:"Bundeswehr", data:{m:4, n1:10000, n2:8000, n3:8000, range:2, scaling:2, detail:1000}});
				mySuperShape.setPreset("Bundeswehr");
				mySuperShape.draw();

usage:

mySuperShape.addPreset(item);

parameters:

item (Object) the object that defines the preset. Like an item of the Macromedia DataProvider, item needs to have another label and data object inside.

returns: Void.

getPreset

description: Returns the preset object. A preset is an object that contains parameters that represent a shape. If you specify the label of an available preset as a parameter, only the chosen preset is return. If you don't send a parameter, all presets will be returned.

usage:

mySuperShape.getPreset();

mySuperShape.getPreset(preset);

parameters:

preset (String) the label of an available preset.

returns: Object that contains the preset.

setPreset

description: Sets the preset object. A preset is an object that contains parameters that represent a shape. There are predefined presets available. You can add further presets with addPreset().

Example 1: (Example .swf) draw a circle with default parameters.

				var mySuperShape:SuperShape = new SuperShape(275,200);
				mySuperShape.setPreset("circle");
				mySuperShape.draw();

Example 2: (Example .swf) draw an animated square with custom parameters.

				var mySuperShape:SuperShape = new SuperShape(275,200);
				mySuperShape.lineStyle(0);
				mySuperShape.fillStyle(0xff0000);
				mySuperShape.animationStyle(10000,Sine.easeOut);
				mySuperShape.setPreset("square");
				mySuperShape.animate(0,100);

usage:

mySuperShape.setPreset(preset);

parameters:

preset (String) the label of an available preset.

returns: Void.

lineStyle

description: define outline.

usage:

mySuperShape.lineStyle();

mySuperShape.lineStyle(lineThickness, lineRGB, lineAlpha);

parameters:

lineThickness (Number) Outline thickness.
lineRGB (Number) Outline color of the drawing as hex number.
lineAlpha (Number) Outline transparency (alpha).

returns: Void.

fillStyle

description: define fill.

usage:

mySuperShape.fillStyle();

mySuperShape.fillStyle(fillRGB, fillAlpha);

parameters:

fillRGB (Number) Fill color of the drawing.
fillAlpha (Number) Fill transparency.

returns: Void.

gradientStyle

description: Same interface as MovieClip.beginGradientFill(). See manual.

usage:

mySuperShape.gradientStyle(fillType, colors, alphas, ratios, matrix);

parameters:

fillType (String) Gradient property. See MovieClip.beginGradientFill().
colors (Array) Gradient property. See MovieClip.beginGradientFill().
alphas (Array) Gradient property. See MovieClip.beginGradientFill().
ratios (Array) Gradient property. See MovieClip.beginGradientFill().
matrix (Object) Gradient property. See MovieClip.beginGradientFill().

returns: Void.

animationStyle

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.:

				var myRotation:Rotation = new Rotation(mc);
				myRotation.animationStyle(2000,[Back.easeOut,4]);
				myRotation.run(360);

See also "Customizable easing equations" in readme for more information.

usage:

mySuperShape.animationStyle(duration);

mySuperShape.animationStyle(duration, callback);

mySuperShape.animationStyle(duration, easing, callback);

parameters:

duration (Number) Duration of animation in milliseconds or frames. Default is milliseconds.
easing (Object) Easing equation in Robert Penner style. Default equation is Linear.easeNone. www.robertpenner.com/easing/
callback (String) Function to invoke after animation. See APCore class.

returns: Void.

clear

description: removes all drawings. Identical to myInstance.movieclip.clear();

usage:

myInstance.clear();

returns: Void.

roundResult

description: rounds animation results to integers. (might be usefull for animating pixelfonts). Default is false.

usage:

myInstance.roundResult(rounded);

parameters:

rounded (Boolean) true rounds the result. Animates with integers. Less accuracy. false animates with floating point numbers.

returns: Void.

forceEnd

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:

forceEndVal (Boolean) true or false.

returns: Void.

getOptimizationMode

description: returns the optimization mode. See setOptimizationMode for more information.

usage: getOptimizationMode();

returns: Boolean

setOptimizationMode

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:

optimize (Boolean)

returns: Void.

getTweenMode

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.

setTweenMode

description: sets the current tween mode used by the instance. Please check with AnimationCore.setTweenModes for more information.

usage: setTweenMode();

parameters:

t (String) Either AnimationCore.INTERVAL for time-based tweening or AnimationCore.FRAMES for frame-based tweening.

returns: true if setting tween mode was successful, false if not successful.

getDurationMode

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.

setDurationMode

description: sets the current duration mode used by the instance. Please check with AnimationCore.setTweenModes for more information.

usage: setDurationMode();

parameters:

d (String) Either AnimationCore.MS for milliseconds or AnimationCore.FRAMES.

returns: true if setting duration mode was successful, false if not successful.

stop

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.

pause

description: pauses the animation if not locked. Call resume() to continue animation.

usage: myInstance.pause();

parameters:

duration (Number) optional property. Number of milliseconds or frames to pause before continuing animation.

returns: true if instance was successfully paused. false if instance could not be paused, because it was locked.

resume

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.

lock

description: locks the animation to prevent pausing, resuming and stopping. Default is unlocked.

usage: myInstance.lock();

returns: Void.

unlock

description: unlocks the animation to allow pausing, resuming and stopping. Default is unlocked.

usage: myInstance.unlock();

returns: Void.

isTweening

description: checks if the instance is currently animated.

usage: myInstance.isTweening();

returns: true if instance is tweening, false if instance is not tweening.

getStartValue

description: returns the original, starting value of the current tween. Percentage.

usage: myInstance.getStartValue();

returns: Number

getEndValue

description: returns the targeted value of the current tween. Percentage.

usage: myInstance.getEndValue();

returns: Number

getCurrentValue

description: returns the current value of the current tween. Percentage.

usage: myInstance.getCurrentValue();

returns: Number

getCurrentPercentage

description: returns the current state of the animation in percentage. Especially usefull in combination with goto().

usage: myInstance.getCurrentPercentage();

returns: Number

getDurationElapsed

description: returns the elapsed time or frames since the current tween started tweening.

usage: myInstance.getDurationElapsed();

returns: Number

getDurationRemaining

description: returns the remaining time or frames since the current tween started tweening.

usage: myInstance.getDurationRemaining();

returns: Number

addEventListener

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 (Number) value to animate.

usage:

mySuperShape.addEventListener(event, listener);

mySuperShape.addEventListener(event, listener, handler);

parameters:

event (String) Event to subscribe listener to. GDispatcher specific feature allows to subscribe to all events from an event source if the string "ALL" is passed.
listener (Object) The listener object to subscribe to the specified event.
handler (String) Optional. GDispatcher specific feature. The name of a function to call. This function will be called within the scope of the object specified in the second parameter.

returns: Void.

removeEventListener

description: Removes a listener from a subscribed event.

usage:

mySuperShape.removeEventListener(event, listener);

mySuperShape.removeEventListener(event, listener, handler);

parameters:

event (String) Event to remove subscribed listener from. GDispatcher specific feature allows to remove subscribtion to all events if the string "ALL" is passed. Works only if listener has been subscribed via the "ALL" string in addEventListener.
listener (Object) The listener object to unsubscribe from the specified event.
handler (String) Optional. GDispatcher specific feature. Only needed if the listener has been subscribed with a handler function.

returns: Void.

removeAllEventListeners

description: GDispatcher specific feature. Removes all listeners for a specific event, or for all events.

usage:

mySuperShape.removeAllEventListeners();

mySuperShape.removeAllEventListeners(event);

parameters:

event (String) Event to remove all subscribed listeners from. If not specified, all listeners to any event will be removed.

returns: Void.

eventListenerExists

description: GDispatcher specific feature. Checks if a listener is already subscribed to a certain event.

usage:

mySuperShape.eventListenerExists(event, listener);

mySuperShape.eventListenerExists(event, listener, handler);

parameters:

event (String) Event to check subscription.
listener (Object) The listener object to check subscription.
handler (String) The handler function to check subscription.

returns: true if event exists on listener. false if event doesn't exist on listener.

getID

description: returns a unique ID of the instance. Usefull for associative arrays.

usage: myInstance.getID();

returns: Number

toString

description: returns the name of the class.

usage: myInstance.toString();

returns: String