Packagecom.greensock.motionPaths
Classpublic class CirclePath2D
InheritanceCirclePath2D Inheritance MotionPath Inheritance flash.display.Shape

A CirclePath2D defines a circular path on which a PathFollower can be placed, making it simple to tween objects along a circle or oval (make an oval by altering the width/height/scaleX/scaleY properties). 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 CirclePath2D'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 CirclePath2D 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 CirclePath2D'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 radius, 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.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, 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
 Inheritedfollowers : Array
Returns an array of all PathFollower instances associated with this path
MotionPath
 Inheritedheight : Number
MotionPath
 Inheritedprogress : Number
A value (typically between 0 and 1) that can be used to move all followers along the path.
MotionPath
  radius : Number
radius of the circle (does not factor in any transformations like scaleX/scaleY)
CirclePath2D
 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
 Inheritedvisible : Boolean
MotionPath
 Inheritedwidth : Number
MotionPath
 Inheritedx : Number
MotionPath
 Inheritedy : Number
MotionPath
Public Methods
 MethodDefined by
  
CirclePath2D(x:Number, y:Number, radius:Number)
Constructor
CirclePath2D
 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
  
anglesToProgressChange(startAngle:Number, endAngle:Number, direction:String = "clockwise", extraRevolutions:uint = 0, useRadians:Boolean = false):Number
Returns the amount of progress change between two angles on the CirclePath2D, allowing special parameters like direction and extraRevolutions.
CirclePath2D
  
angleToProgress(angle:Number, useRadians:Boolean = false):Number
Translates an angle (in degrees or radians) to the associated progress value on the CirclePath2D.
CirclePath2D
 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
  
followerTween(follower:*, endAngle:Number, direction:String = "clockwise", extraRevolutions:uint = 0, useRadians:Boolean = false):String
Simplifies tweening by determining a relative change in the progress value of a follower based on the endAngle, direction, and extraRevolutions that you define.
CirclePath2D
 Inherited
getFollower(target:Object):PathFollower
Returns the PathFollower instance associated with a particular target or null if none exists.
MotionPath
 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
  
progressToAngle(progress:Number, useRadians:Boolean = false):Number
Translates a 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) to the associated angle on the CirclePath2D.
CirclePath2D
 Inherited
removeAllFollowers():void
Removes all followers.
MotionPath
 Inherited
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.
CirclePath2D
Property detail
radiusproperty
radius:Number  [read-write]

radius of the circle (does not factor in any transformations like scaleX/scaleY)

Implementation
    public function get radius():Number
    public function set radius(value:Number):void
Constructor detail
CirclePath2D()constructor
public function CirclePath2D(x:Number, y:Number, radius:Number)

Constructor

Parameters
x:Number — The x coordinate of the origin (center) of the circle
 
y:Number — The y coordinate of the origin (center) of the circle
 
radius:Number — The radius of the circle
Method detail
anglesToProgressChange()method
public function anglesToProgressChange(startAngle:Number, endAngle:Number, direction:String = "clockwise", extraRevolutions:uint = 0, useRadians:Boolean = false):Number

Returns the amount of progress change between two angles on the CirclePath2D, allowing special parameters like direction and extraRevolutions.

Parameters
startAngle:Number — The starting angle
 
endAngle:Number — The ending angle
 
direction:String (default = "clockwise") — The direction in which to travel - options are Direction.CLOCKWISE ("clockwise"), Direction.COUNTER_CLOCKWISE ("counterClockwise"), or Direction.SHORTEST ("shortest").
 
extraRevolutions:uint (default = 0) — If instead of going directly to the endAngle, you want the target to travel one or more extra revolutions around the path before going to the endAngle, define that number of revolutions here.
 
useRadians:Boolean (default = false) — If you prefer to define the angle in radians instead of degrees, set this to true (it is false by default)

Returns
Number — A Number representing the amount of change in the progress value.
angleToProgress()method 
public function angleToProgress(angle:Number, useRadians:Boolean = false):Number

Translates an angle (in degrees or radians) to the associated progress value on the CirclePath2D. For example, to position mc on the CirclePath2D at 90 degrees (bottom), you'd do:

var follower:PathFollower = myCircle.addFollower(mc, myCircle.angleToProgress(90));

Parameters
angle:Number — The angle whose progress value you want to determine
 
useRadians:Boolean (default = false) — If you prefer to define the angle in radians instead of degrees, set this to true (it is false by default)

Returns
Number — The progress value associated with the angle
followerTween()method 
public function followerTween(follower:*, endAngle:Number, direction:String = "clockwise", extraRevolutions:uint = 0, useRadians:Boolean = false):String

Simplifies tweening by determining a relative change in the progress value of a follower based on the endAngle, direction, and extraRevolutions that you define. For example, to tween myFollower from wherever it is currently to the position at 315 degrees, moving in the COUNTER_CLOCKWISE direction and going 2 extra revolutions, you could do:

TweenLite.to(myFollower, 2, {progress:myCircle.followerTween(myFollower, 315, Direction.COUNTER_CLOCKWISE, 2)});

Parameters
follower:* — The PathFollower (or its associated target) that will be tweened (determines the start angle)
 
endAngle:Number — The destination (end) angle
 
direction:String (default = "clockwise") — The direction in which to travel - options are Direction.CLOCKWISE ("clockwise"), Direction.COUNTER_CLOCKWISE ("counterClockwise"), or Direction.SHORTEST ("shortest").
 
extraRevolutions:uint (default = 0) — If instead of going directly to the endAngle, you want the target to travel one or more extra revolutions around the path before going to the endAngle, define that number of revolutions here.
 
useRadians:Boolean (default = false) — If you prefer to define the angle in radians instead of degrees, set this to true (it is false by default)

Returns
String — A String representing the amount of change in the progress value (feel free to cast it as a Number if you want, but it returns a String because TweenLite/Max/Nano recognize Strings as relative values.
progressToAngle()method 
public function progressToAngle(progress:Number, useRadians:Boolean = false):Number

Translates a 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) to the associated angle on the CirclePath2D. For example, to find out what angle a particular PathFollower is at, you'd do:

var angle:Number = myCircle.progressToAngle(myFollower.progress, false);

Parameters
progress:Number — The progress value to translate into an angle
 
useRadians:Boolean (default = false) — If you prefer that the angle be described in radians instead of degrees, set this to true (it is false by default)

Returns
Number — The angle (in degrees or radians depending on the useRadians value) associated with the progress value.
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.