Packagecom.greensock.motionPaths
Classpublic class MotionPath
InheritanceMotionPath Inheritance flash.display.Shape
SubclassesCirclePath2D, LinePath2D, RectanglePath2D

A MotionPath defines a path along which a PathFollower can travel, making it relatively simple to do things like tween an object in a circular path. A PathFollower's position along the path is described using its progress property, a value between 0 and 1 where 0 is at the beginning of the path, 0.5 is in the middle, and 1 is at the very end of the path. So to tween a PathFollower along the path, you can simply tween its progress property. To tween ALL of the followers on the path at once, you can tween the MotionPath's progress property. PathFollowers automatically wrap so that if the progress value exceeds 1 or drops below 0, it shows up on the other end of the path.

Since MotionPath extends the Shape class, you can add an instance to the display list to see a line representation of the path drawn which can be helpful especially during the production phase. Use lineStyle() to adjust the color, thickness, and other attributes of the line that is drawn (or set the MotionPath's visible property to false or don't add it to the display list if you don't want to see the line at all). You can also adjust all of its properties like scaleX, scaleY, rotation, width, height, x, and y just like any DisplayObject. That means you can tween those values as well to achieve very dynamic, complex effects with ease.


Example
Example AS3 code:
import com.greensock.*;
import com.greensock.plugins.*;
import com.greensock.motionPaths.*;
TweenPlugin.activate([CirclePath2DPlugin]); //only needed once in your swf, and only if you plan to use the circlePath2D tweening feature for convenience

//create a circle motion path at coordinates x:150, y:150 with a radius of 100
var circle:CirclePath2D = new CirclePath2D(150, 150, 100);

//tween mc along the path from the bottom (90 degrees) to 315 degrees in the counter-clockwise direction and make an extra revolution
TweenLite.to(mc, 3, {circlePath2D:{path:circle, startAngle:90, endAngle:315, autoRotate:true, direction:Direction.COUNTER_CLOCKWISE, extraRevolutions:1}});

//tween the circle's rotation, scaleX, scaleY, x, and y properties:
TweenLite.to(circle, 3, {rotation:180, scaleX:0.5, scaleY:2, x:250, y:200});

//show the path visually by adding it to the display list (optional)
this.addChild(circle);


//--- Instead of using the plugin, you could manually manage followers and tween their "progress" property...
 
//make the MovieClip "mc2" follow the circle and start at a position of 90 degrees (this returns a PathFollower instance)
var follower:PathFollower = circle.addFollower(mc2, circle.angleToProgress(90));

//tween the follower clockwise along the path to 315 degrees
TweenLite.to(follower, 2, {progress:circle.followerTween(follower, 315, Direction.CLOCKWISE)});

//tween the follower counter-clockwise to 200 degrees and add an extra revolution
TweenLite.to(follower, 2, {progress:circle.followerTween(follower, 200, Direction.COUNTER_CLOCKWISE, 1)});
NOTES
Copyright 2010, GreenSock. All rights reserved. This work is subject to the terms in http://www.greensock.com/terms_of_use.html or for corporate Club GreenSock members, the software agreement that was issued with the corporate membership.



Public Properties
 PropertyDefined by
  followers : Array
[read-only] Returns an array of all PathFollower instances associated with this path
MotionPath
  height : Number
MotionPath
  progress : Number
A value (typically between 0 and 1) that can be used to move all followers along the path.
MotionPath
  rotation : Number
MotionPath
  scaleX : Number
MotionPath
  scaleY : Number
MotionPath
  targets : Array
[read-only] Returns an array of all target instances associated with the PathFollowers of this path
MotionPath
  visible : Boolean
MotionPath
  width : Number
MotionPath
  x : Number
MotionPath
  y : Number
MotionPath
Public Methods
 MethodDefined by
  
addFollower(target:*, progress:Number = 0, autoRotate:Boolean = false, rotationOffset:Number = 0):PathFollower
Adds a follower to the path, optionally setting it to a particular progress position.
MotionPath
  
distribute(targets:Array = null, min:Number = 0, max:Number = 1, autoRotate:Boolean = false, rotationOffset:Number = 0):void
Distributes objects evenly along the MotionPath.
MotionPath
  
getFollower(target:Object):PathFollower
Returns the PathFollower instance associated with a particular target or null if none exists.
MotionPath
  
lineStyle(thickness:Number = 1, color:uint = 0x666666, alpha:Number = 1, pixelHinting:Boolean = false, scaleMode:String = "none", caps:String = null, joints:String = null, miterLimit:Number = 3, skipRedraw:Boolean = false):void
Sets the line style for the path which you will only see if you add the path to the display list with something like addChild() and make sure the visible property is true.
MotionPath
  
Removes all followers.
MotionPath
  
removeFollower(target:*):void
Removes the target as a follower.
MotionPath
  
renderObjectAt(target:Object, progress:Number, autoRotate:Boolean = false, rotationOffset:Number = 0):void
Positions any object with x and y properties on the path at a specific progress position.
MotionPath
Property detail
followersproperty
followers:Array  [read-only]

Returns an array of all PathFollower instances associated with this path

Implementation
    public function get followers():Array
heightproperty 
height:Number  [read-write]

Implementation
    public function get height():Number
    public function set height(value:Number):void
progressproperty 
progress:Number  [read-write]

A value (typically between 0 and 1) that can be used to move all followers along the path. Unlike a PathFollower's progress, this value is not absolute - it simply facilitates movement of followers together along the path in a way that performs better than tweening each follower independently (plus it's easier). You can tween to values that are greater than 1 or less than 0 but the values are simply wrapped. So, for example, setting progress to 1.2 is the same as setting it to 0.2 and -0.2 is the same as 0.8. If your goal is to tween all followers around a CirclePath2D twice completely, you could just add 2 to the progress value or use a relative value in the tween, like:

TweenLite.to(myCircle, 5, {progress:"2"}); //or myCircle.progress + 2

Implementation
    public function get progress():Number
    public function set progress(value:Number):void
rotationproperty 
rotation:Number  [read-write]

Implementation
    public function get rotation():Number
    public function set rotation(value:Number):void
scaleXproperty 
scaleX:Number  [read-write]

Implementation
    public function get scaleX():Number
    public function set scaleX(value:Number):void
scaleYproperty 
scaleY:Number  [read-write]

Implementation
    public function get scaleY():Number
    public function set scaleY(value:Number):void
targetsproperty 
targets:Array  [read-only]

Returns an array of all target instances associated with the PathFollowers of this path

Implementation
    public function get targets():Array
visibleproperty 
visible:Boolean  [read-write]

Implementation
    public function get visible():Boolean
    public function set visible(value:Boolean):void
widthproperty 
width:Number  [read-write]

Implementation
    public function get width():Number
    public function set width(value:Number):void
xproperty 
x:Number  [read-write]

Implementation
    public function get x():Number
    public function set x(value:Number):void
yproperty 
y:Number  [read-write]

Implementation
    public function get y():Number
    public function set y(value:Number):void
Method detail
addFollower()method
public function addFollower(target:*, progress:Number = 0, autoRotate:Boolean = false, rotationOffset:Number = 0):PathFollower

Adds a follower to the path, optionally setting it to a particular progress position. If the target isn't a PathFollower instance already, one will be created for it. The target can be any object that has x and y properties.

Parameters
target:* — Any object that has x and y properties that you'd like to follow the path. Existing PathFollower instances are allowed.
 
progress:Number (default = 0) — The progress position at which the target should be placed initially (0 by default)
 
autoRotate:Boolean (default = false) — When autoRotate is true, the target will automatically be rotated so that it is oriented to the angle of the path. To offset this value (like to always add 90 degrees for example), use the rotationOffset property.
 
rotationOffset:Number (default = 0) — When autoRotate is true, this value will always be added to the resulting rotation of the target.

Returns
PathFollower — A PathFollower instance associated with the target (you can tween this PathFollower's progress property to move it along the path).
distribute()method 
public function distribute(targets:Array = null, min:Number = 0, max:Number = 1, autoRotate:Boolean = false, rotationOffset:Number = 0):void

Distributes objects evenly along the MotionPath. You can optionally define minimum and maximum progress values between which the objects will be distributed. For example, if you want them distributed from the very beginning of the path to the middle, you would do:

path.distribute([mc1, mc2, mc3], 0, 0.5);

As it loops through the targets array, if a target is found for which a PathFollower doesn't exist, one will automatically be created and added to the path. The targets array can be populated with PathFollowers or DisplayObjects or Points or pretty much any object.

Parameters
targets:Array (default = null) — An array of targets (PathFollowers, DisplayObjects, Points, or pretty much any object) that should be distributed evenly along the MotionPath. As it loops through the targets array, if a target is found for which a PathFollower doesn't exist, one will automatically be created and added to the path.
 
min:Number (default = 0) — The minimum progress value at which the targets will begin being distributed. This value will always be between 0 and 1. For example, if the targets should be distributed from the midpoint of the path through the end, the min parameter would be 0.5 and the max parameter would be 1.
 
max:Number (default = 1) — The maximum progress value where the targets will end distribution. This value will always be between 0 and 1. For example, if the targets should be distributed from the midpoint of the path through the end, the min parameter would be 0.5 and the max parameter would be 1.
 
autoRotate:Boolean (default = false) — When autoRotate is true, the target will automatically be rotated so that it is oriented to the angle of the path. To offset this value (like to always add 90 degrees for example), use the rotationOffset property.
 
rotationOffset:Number (default = 0) — When autoRotate is true, this value will always be added to the resulting rotation of the target. For example, to always add 90 degrees to the autoRotation, rotationOffset would be 90.
getFollower()method 
public function getFollower(target:Object):PathFollower

Returns the PathFollower instance associated with a particular target or null if none exists.

Parameters
target:Object — The target whose PathFollower instance you want returned.

Returns
PathFollower — PathFollower instance
lineStyle()method 
public function lineStyle(thickness:Number = 1, color:uint = 0x666666, alpha:Number = 1, pixelHinting:Boolean = false, scaleMode:String = "none", caps:String = null, joints:String = null, miterLimit:Number = 3, skipRedraw:Boolean = false):void

Sets the line style for the path which you will only see if you add the path to the display list with something like addChild() and make sure the visible property is true. For example, to make a CirclePath2D visible with a red line red that's 3 pixels thick, you could do:

var myCircle:CirclePath2D = new CirclePath2D(150, 150, 100);
myCircle.lineStyle(3, 0xFF0000);
addChild(myCircle);

Parameters
thickness:Number (default = 1) — line thickness
 
color:uint (default = 0x666666) — line color
 
alpha:Number (default = 1) — line alpha
 
pixelHinting:Boolean (default = false) — pixel hinting
 
scaleMode:String (default = "none") — scale mode
 
caps:String (default = null) — caps
 
joints:String (default = null) — joints
 
miterLimit:Number (default = 3) — miter limit
 
skipRedraw:Boolean (default = false) — if true, the redraw will be skipped.
removeAllFollowers()method 
public function removeAllFollowers():void

Removes all followers.

removeFollower()method 
public function removeFollower(target:*):void

Removes the target as a follower. The target can be a PathFollower instance or the target associated with one of the PathFollower instances.

Parameters
target:* — the target or PathFollower instance to remove.
renderObjectAt()method 
public function renderObjectAt(target:Object, progress:Number, autoRotate:Boolean = false, rotationOffset:Number = 0):void

Positions any object with x and y properties on the path at a specific progress position. For example, to position mc in the middle of the path, you would do:

myPath.renderObjectAt(mc, 0.5);

Some paths have methods to translate other meaningful information into a progress value, like for a CirclePath2D you can get the progress associated with the 90-degree position with the angleToPosition() method like this:

myCircle.renderObjectAt(mc, myCircle.angleToProgress(90));

Parameters
target:Object — The target object to position
 
progress:Number — The progress value (typically between 0 and 1 where 0 is the beginning of the path, 0.5 is in the middle, and 1 is at the end)
 
autoRotate:Boolean (default = false) — When autoRotate is true, the target will automatically be rotated so that it is oriented to the angle of the path. To offset this value (like to always add 90 degrees for example), use the rotationOffset property.
 
rotationOffset:Number (default = 0) — When autoRotate is true, this value will always be added to the resulting rotation of the target.