Packagecom.greensock.motionPaths
Classpublic class LinePath2D
InheritanceLinePath2D Inheritance MotionPath Inheritance flash.display.Shape

A LinePath2D defines a path (using as many Points as you want) on which a PathFollower can be placed and animated. A PathFollower's position along the path is described using the PathFollower's 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. To tween a PathFollower along the path, simply tween its progress property. To tween ALL of the followers on the path at once, you can tween the LinePath2D's progress property which performs better than tweening every PathFollower's progress property individually. PathFollowers automatically wrap so that if the progress value exceeds 1 it continues at the beginning of the path, meaning that tweening its progress from 0 to 2 would have the same effect as tweening it from 0 to 1 twice (it would appear to loop).

Since LinePath2D 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 particularly helpful during the production phase. Use lineStyle() to adjust the color, thickness, and other attributes of the line that is drawn (or set the LinePath2D'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. 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.easing.*;
import com.greensock.motionPaths.*;
import flash.geom.Point;

//create a LinePath2D with 5 Points
var path:LinePath2D = new LinePath2D([new Point(0, 0), 
           new Point(100, 100), 
           new Point(350, 150),
           new Point(50, 200),
           new Point(550, 400)]);

//add it to the display list so we can see it (you can skip this if you prefer)
addChild(path);

//create an array containing 30 blue squares
var boxes:Array = [];
for (var i:int = 0; i < 30; i++) {
 boxes.push(createSquare(10, 0x0000FF));
}

//distribute the blue squares evenly across the entire path and set them to autoRotate
path.distribute(boxes, 0, 1, true);

//put a red square exactly halfway through the 2nd segment
path.addFollower(createSquare(10, 0xFF0000), path.getSegmentProgress(2, 0.5));

//tween all of the squares through the path once (wrapping when they reach the end)
TweenMax.to(path, 20, {progress:1});

//while the squares are animating through the path, tween the path's position and rotation too!
TweenMax.to(path, 3, {rotation:180, x:550, y:400, ease:Back.easeOut, delay:3});

//method for creating squares
function createSquare(size:Number, color:uint=0xFF0000):Shape {
 var s:Shape = new Shape();
 s.graphics.beginFill(color, 1);
 s.graphics.drawRect(-size * 0.5, -size * 0.5, size, size);
 s.graphics.endFill();
 this.addChild(s);
 return s;
}
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
  autoUpdatePoints : Boolean
If true, the LinePath2D will analyze every Point whenever it renders to see if any Point's x or y value has changed, thus making it possible to tween them dynamically.
LinePath2D
 Inheritedfollowers : Array
Returns an array of all PathFollower instances associated with this path
MotionPath
 Inheritedheight : Number
MotionPath
  points : Array
The array of Points through which the LinePath2D is drawn.
LinePath2D
 Inheritedprogress : Number
A value (typically between 0 and 1) that can be used to move all followers along the path.
MotionPath
 Inheritedrotation : Number
MotionPath
 InheritedscaleX : Number
MotionPath
 InheritedscaleY : Number
MotionPath
 Inheritedtargets : Array
Returns an array of all target instances associated with the PathFollowers of this path
MotionPath
  totalLength : Number
[read-only] Total length of the LinePath2D as though it were stretched out in a straight, flat line.
LinePath2D
 Inheritedvisible : Boolean
MotionPath
 Inheritedwidth : Number
MotionPath
 Inheritedx : Number
MotionPath
 Inheritedy : Number
MotionPath
Public Methods
 MethodDefined by
  
LinePath2D(points:Array = null, x:Number = 0, y:Number = 0, autoUpdatePoints:Boolean = false)
Constructor
LinePath2D
 Inherited
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
  
appendMultiplePoints(points:Array):void
Appends multiple Points to the end of the points array.
LinePath2D
  
appendPoint(point:Point):void
Adds a Point to the end of the current LinePath2D (essentially redefining its end point).
LinePath2D
 Inherited
distribute(targets:Array = null, min:Number = 0, max:Number = 1, autoRotate:Boolean = false, rotationOffset:Number = 0):void
Distributes objects evenly along the MotionPath.
MotionPath
  
getClosestProgress(target:Object):Number
Finds the closest overall progress value on the LinePath2D based on the target object's current position (x and y properties).
LinePath2D
 Inherited
getFollower(target:Object):PathFollower
Returns the PathFollower instance associated with a particular target or null if none exists.
MotionPath
  
getSegmentProgress(segment:uint, progress:Number):Number
Translates the progress along a particular segment of the LinePath2D to an overall progress value, making it easy to position an object like "halfway along the 2nd segment of the line".
LinePath2D
  
insertMultiplePoints(points:Array, index:uint = 0):void
Inserts multiple Points into the points array at a particular index/position.
LinePath2D
  
insertPoint(point:Point, index:uint = 0):void
Inserts a Point at a particular index value in the points array, similar to splice() in an array.
LinePath2D
 Inherited
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
 Inherited
Removes all followers.
MotionPath
 Inherited
removeFollower(target:*):void
Removes the target as a follower.
MotionPath
  
removePoint(point:Point):void
Removes a particular Point instance from the points array.
LinePath2D
  
removePointByIndex(index:uint):void
Removes the Point that resides at a particular index/position in the points array.
LinePath2D
  
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.
LinePath2D
  
snap(target:Object, autoRotate:Boolean = false, rotationOffset:Number = 0):PathFollower
Allows you to snap an object like a Sprite, Point, MovieClip, etc.
LinePath2D
Property detail
autoUpdatePointsproperty
public var autoUpdatePoints:Boolean

If true, the LinePath2D will analyze every Point whenever it renders to see if any Point's x or y value has changed, thus making it possible to tween them dynamically. Setting autoUpdatePoints to true increases the CPU load due to the extra processing, so only set it to true if you plan to change one or more of the Points' position.

pointsproperty 
points:Array  [read-write]

The array of Points through which the LinePath2D is drawn. IMPORTANT: Changes to the array are NOT automatically applied or reflected in the LinePath2D - just like the filters property of a DisplayObject, you must set the points property of a LinePath2D directly to ensure that any changes are applied internally.

Implementation
    public function get points():Array
    public function set points(value:Array):void
totalLengthproperty 
totalLength:Number  [read-only]

Total length of the LinePath2D as though it were stretched out in a straight, flat line.

Implementation
    public function get totalLength():Number
Constructor detail
LinePath2D()constructor
public function LinePath2D(points:Array = null, x:Number = 0, y:Number = 0, autoUpdatePoints:Boolean = false)

Constructor

Parameters
points:Array (default = null) — An array of Points that define the line
 
x:Number (default = 0) — The x coordinate of the origin of the line
 
y:Number (default = 0) — The y coordinate of the origin of the line
 
autoUpdatePoints:Boolean (default = false) — If true, the LinePath2D will analyze every Point whenever it renders to see if any Point's x or y value has changed, thus making it possible to tween them dynamically. Setting autoUpdatePoints to true increases the CPU load due to the extra processing, so only set it to true if you plan to change one or more of the Points' position.
Method detail
appendMultiplePoints()method
public function appendMultiplePoints(points:Array):void

Appends multiple Points to the end of the points array. Identical to the appendPoint() method, but accepts an array of Points instead of just one.

Parameters
points:Array — An array of Points to append.
appendPoint()method 
public function appendPoint(point:Point):void

Adds a Point to the end of the current LinePath2D (essentially redefining its end point).

Parameters
point:Point — A Point describing the local coordinates through which the line should be drawn.
getClosestProgress()method 
public function getClosestProgress(target:Object):Number

Finds the closest overall progress value on the LinePath2D based on the target object's current position (x and y properties). For example, to position the mc object on the LinePath2D at the spot that's closest to the Point x:100, y:50, you could do:

path.addFollower(mc, path.getClosestProgress(new Point(100, 50)));

Parameters
target:Object — The target object whose position (x/y property values) are analyzed for proximity to the LinePath2D.

Returns
Number — The overall progress value describing the position on the LinePath2D that is closest to the target's current position.
getSegmentProgress()method 
public function getSegmentProgress(segment:uint, progress:Number):Number

Translates the progress along a particular segment of the LinePath2D to an overall progress value, making it easy to position an object like "halfway along the 2nd segment of the line". For example:

path.addFollower(mc, path.getSegmentProgress(2, 0.5));

Parameters
segment:uint — The segment number of the line. For example, a line defined by 3 Points would have two segments.
 
progress:Number — The progress along the segment. For example, the midpoint of the second segment would be getSegmentProgress(2, 0.5);.

Returns
Number — The progress value (between 0 and 1) describing the overall progress on the entire LinePath2D.
insertMultiplePoints()method 
public function insertMultiplePoints(points:Array, index:uint = 0):void

Inserts multiple Points into the points array at a particular index/position. Identical to the insertPoint() method, but accepts an array of points instead of just one.

Parameters
points:Array — An array of Points to insert.
 
index:uint (default = 0) — The index value in the points array at which the Points should be inserted.
insertPoint()method 
public function insertPoint(point:Point, index:uint = 0):void

Inserts a Point at a particular index value in the points array, similar to splice() in an array. For example, if a LinePath2D instance has 3 Points already and you want to insert a new Point right after the first one, you would do:

var path:LinePath2D = new LinePath2D([new Point(0, 0),
new Point(100, 50),
new Point(200, 300)]);
path.insertPoint(new Point(50, 50), 1);

Parameters
point:Point — A Point describing the local coordinates through which the line should be drawn.
 
index:uint (default = 0) — The index value in the points array at which the Point should be inserted.
removePoint()method 
public function removePoint(point:Point):void

Removes a particular Point instance from the points array.

Parameters
point:Point — The Point object to remove from the points array.
removePointByIndex()method 
public function removePointByIndex(index:uint):void

Removes the Point that resides at a particular index/position in the points array. Just like in arrays, the index is zero-based. For example, to remove the second Point in the array, do removePointByIndex(1);

Parameters
index:uint — The index value of the Point that should be removed from the points array.
renderObjectAt()method 
public override 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.
snap()method 
public function snap(target:Object, autoRotate:Boolean = false, rotationOffset:Number = 0):PathFollower

Allows you to snap an object like a Sprite, Point, MovieClip, etc. to the LinePath2D by determining the closest position along the line to the current position of the object. It will automatically create a PathFollower instance for the target object and reposition it on the LinePath2D.

Parameters
target:Object — The target object that should be repositioned onto the LinePath2D.
 
autoRotate:Boolean (default = false) — When autoRotate is true, the follower will automatically be rotated so that it is oriented to the angle of the path that it is following. 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 that was created for the target.