Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Re-merged in doc changes.

  • Loading branch information...
commit 47a09e25f7b2cff38cd163952c1b3a49797ef5d4 1 parent 874172b
@lannymcnie lannymcnie authored
Showing with 95 additions and 51 deletions.
  1. +95 −51 src/tweenjs/Tween.js
View
146 src/tweenjs/Tween.js
@@ -27,12 +27,12 @@
*/
/**
-* The TweenJS Javascript library provides a simple but powerful tweening interface. It allows you to chain tweens and
-* actions together to create complex sequences. For example:<br/>
-* Tween.get(target).wait(500).to({alpha:0,visible:false},1000).call(onComplete);<br/>
-* This tween will wait 0.5s, tween the target's alpha property to 0 over 1s, set it's visible to false, then call the onComplete function.
-* @module TweenJS
-**/
+ * The TweenJS Javascript library provides a simple but powerful tweening interface. It allows you to chain tweens and
+ * actions together to create complex sequences. For example:<br/>
+ * For example:<br/>Tween.get(target).wait(500).to({alpha:0,visible:false},1000).call(onComplete);<br/>
+ * This tween will wait 0.5s, tween the target's alpha property to 0 over 1s, set it's visible to false, then call the onComplete function.
+ * @module TweenJS
+ */
// TODO: possibly add a END actionsMode (only runs actions that == position)?
// TODO: evaluate a way to decouple paused from tick registration.
@@ -42,10 +42,10 @@ this.createjs = this.createjs||{};
(function() {
/**
-* Returns a new Tween instance. See Tween.get for param documentation.
-* @class Tween
-* @constructor
-**/
+ * Returns a new Tween instance. See Tween.get for param documentation.
+ * @class Tween
+ * @constructor
+ */
var Tween = function(target, props, pluginData) {
this.initialize(target, props, pluginData);
}
@@ -56,6 +56,7 @@ var p = Tween.prototype;
* Constant defining the none actionsMode for use with setPosition.
* @property NONE
* @type Number
+ * @default 0
* @static
**/
Tween.NONE = 0;
@@ -64,6 +65,7 @@ var p = Tween.prototype;
* Constant defining the loop actionsMode for use with setPosition.
* @property LOOP
* @type Number
+ * @default 1
* @static
**/
Tween.LOOP = 1;
@@ -72,6 +74,7 @@ var p = Tween.prototype;
* Constant defining the reverse actionsMode for use with setPosition.
* @property REVERSE
* @type Number
+ * @default 2
* @static
**/
Tween.REVERSE = 2;
@@ -105,8 +108,9 @@ var p = Tween.prototype;
* with the chained syntax of TweenJS.
* @method get
* @static
- * @param target The target object that will have its properties tweened.
- * @param props The configuration properties to apply to this tween instance (ex. {loop:true, paused:true}). All properties default to false. Supported props are:<UL>
+ * @param {Object} target The target object that will have its properties tweened.
+ * @param {Object} props The configuration properties to apply to this tween instance (ex. {loop:true, paused:true}).
+ * All properties default to false. Supported props are:<UL>
* <LI> loop: sets the loop property on this tween.</LI>
* <LI> useTicks: uses ticks for all durations instead of milliseconds.</LI>
* <LI> ignoreGlobalPause: sets the ignoreGlobalPause property on this tween.</LI>
@@ -115,8 +119,12 @@ var p = Tween.prototype;
* <LI> position: indicates the initial position for this tween.</LI>
* <LI> onChanged: specifies an onChange handler for this tween.</LI>
* </UL>
- * @param pluginData Optional. An object containing data for use by installed plugins. See individual plugins' documentation for details.
- * @param override If true, any previous tweens on the same target will be removed. This is the same as calling Tween.removeTweens(target).
+ * @param {Object} pluginData Optional. An object containing data for use by installed plugins. See individual
+ * plugins' documentation for details.
+ * @param {Boolean} override If true, any previous tweens on the same target will be removed. This is the same as
+ * calling Tween.removeTweens(target).
+ * @return {Tween} A reference to the created tween. Additional chained tweens, method calls, or callbacks can be
+ * applied to the returned tween instance.
**/
Tween.get = function(target, props, pluginData, override) {
if (override) { Tween.removeTweens(target); }
@@ -124,12 +132,14 @@ var p = Tween.prototype;
}
/**
- * Advances all tweens. This typically uses the Ticker class (available in the EaselJS library), but you can call it manually if you prefer to use
- * your own "heartbeat" implementation.
+ * Advances all tweens. This typically uses the Ticker class (available in the EaselJS library), but you can call it
+ * manually if you prefer to use your own "heartbeat" implementation.
* @method tick
* @static
- * @param delta The change in time in milliseconds since the last tick. Required unless all tweens have useTicks set to true.
- * @param paused Indicates whether a global pause is in effect. Tweens with ignoreGlobalPause will ignore this, but all others will pause if this is true.
+ * @param {Number} delta The change in time in milliseconds since the last tick. Required unless all tweens have
+ * useTicks set to true.
+ * @param {Boolean} paused Indicates whether a global pause is in effect. Tweens with ignoreGlobalPause will ignore
+ * this, but all others will pause if this is true.
**/
Tween.tick = function(delta, paused) {
var tweens = Tween._tweens.slice(); // to avoid race conditions.
@@ -146,7 +156,7 @@ var p = Tween.prototype;
* Removes all existing tweens for a target. This is called automatically by new tweens if the "override" prop is true.
* @method removeTweens
* @static
- * @param target The target object to remove existing tweens from.
+ * @param {Object} target The target object to remove existing tweens from.
**/
Tween.removeTweens = function(target) {
if (!target.tweenjs_count) { return; }
@@ -164,8 +174,9 @@ var p = Tween.prototype;
* Indicates whether there are any active tweens on the target object (if specified) or in general.
* @method hasActiveTweens
* @static
- * @param target Optional. If not specified, the return value will indicate if there are any active tweens on any target.
- * @return Boolean A boolean indicating whether there are any active tweens.
+ * @param {Object} target Optional. If not specified, the return value will indicate if there are any active tweens
+ * on any target.
+ * @return {Boolean} A boolean indicating whether there are any active tweens.
**/
Tween.hasActiveTweens = function(target) {
if (target) { return target.tweenjs_count; }
@@ -173,12 +184,12 @@ var p = Tween.prototype;
}
/**
- * Installs a plugin, which can modify how certain properties are handled when tweened.
- * See the CSSPlugin for an example of how to write TweenJS plugins.
+ * Installs a plugin, which can modify how certain properties are handled when tweened. See the CSSPlugin for an
+ * example of how to write TweenJS plugins.
* @method installPlugin
* @static
- * @param plugin
- * @param properties
+ * @param {Object} plugin
+ * @param {Array} properties
**/
Tween.installPlugin = function(plugin, properties) {
var priority = plugin.priority;
@@ -222,6 +233,7 @@ var p = Tween.prototype;
* See Tween.tick() for more info. Can be set via the props param.
* @property ignoreGlobalPause
* @type Boolean
+ * @default false
**/
p.ignoreGlobalPause = false;
@@ -229,6 +241,7 @@ var p = Tween.prototype;
* If true, the tween will loop when it reaches the end. Can be set via the props param.
* @property loop
* @type Boolean
+ * @default false
**/
p.loop = false;
@@ -238,6 +251,7 @@ var p = Tween.prototype;
* behaviour.
* @property duration
* @type Number
+ * @default 0
**/
p.duration = 0;
@@ -284,6 +298,7 @@ var p = Tween.prototype;
/**
* @property _paused
* @type Boolean
+ * @default false
* @protected
**/
p._paused = false;
@@ -320,6 +335,7 @@ var p = Tween.prototype;
* Raw position.
* @property _prevPosition
* @type Number
+ * @default 0
* @protected
**/
p._prevPosition = 0;
@@ -328,6 +344,7 @@ var p = Tween.prototype;
* The position within the current step.
* @property _stepPosition
* @type Number
+ * @default 0
* @protected
*/
p._stepPosition = 0;
@@ -336,6 +353,7 @@ var p = Tween.prototype;
* Normalized position.
* @property _prevPos
* @type Number
+ * @default -1
* @protected
**/
p._prevPos = -1;
@@ -350,6 +368,7 @@ var p = Tween.prototype;
/**
* @property _useTicks
* @type Boolean
+ * @default false
* @protected
**/
p._useTicks = false;
@@ -357,6 +376,9 @@ var p = Tween.prototype;
// constructor:
/**
* @method initialize
+ * @param {Object} target
+ * @param {Object} props
+ * @param {Object} pluginData
* @protected
**/
p.initialize = function(target, props, pluginData) {
@@ -383,8 +405,8 @@ var p = Tween.prototype;
/**
* Queues a wait (essentially an empty tween).
* @method wait
- * @param duration The duration of the wait in milliseconds (or in ticks if useTicks is true).
- * @return Tween This tween instance (for chaining calls).
+ * @param {Number} duration The duration of the wait in milliseconds (or in ticks if useTicks is true).
+ * @return {Tween} This tween instance (for chaining calls).
**/
p.wait = function(duration) {
if (duration == null || duration <= 0) { return this; }
@@ -397,10 +419,12 @@ var p = Tween.prototype;
* Numeric properties will be tweened from their current value in the tween to the target value. Non-numeric
* properties will be set at the end of the specified duration.
* @method to
- * @param props An object specifying property target values for this tween (Ex. {x:300} would tween the x property of the target to 300).
- * @param duration Optional. The duration of the wait in milliseconds (or in ticks if useTicks is true). Defaults to 0.
- * @param ease Optional. The easing function to use for this tween. Defaults to a linear ease.
- * @return Tween This tween instance (for chaining calls).
+ * @param {Object} props An object specifying property target values for this tween (Ex. {x:300} would tween the x
+ * property of the target to 300).
+ * @param {Number} duration Optional. The duration of the wait in milliseconds (or in ticks if useTicks is true).
+ * Defaults to 0.
+ * @param {Function} ease Optional. The easing function to use for this tween. Defaults to a linear ease.
+ * @return {Tween} This tween instance (for chaining calls).
**/
p.to = function(props, duration, ease) {
if (isNaN(duration) || duration < 0) { duration = 0; }
@@ -408,33 +432,38 @@ var p = Tween.prototype;
}
/**
- * Queues an action to call the specified function. For example: myTween.wait(1000).call(myFunction); would call myFunction() after 1s.
+ * Queues an action to call the specified function. For example: myTween.wait(1000).call(myFunction); would call
+ * myFunction() after 1s.
* @method call
- * @param callback The function to call.
- * @param params Optional. The parameters to call the function with. If this is omitted, then the function will be called with a single param pointing to this tween.
- * @param scope Optional. The scope to call the function in. If omitted, it will be called in the target's scope.
- * @return Tween This tween instance (for chaining calls).
+ * @param {Function} callback The function to call.
+ * @param {Array} params Optional. The parameters to call the function with. If this is omitted, then the function
+ * will be called with a single param pointing to this tween.
+ * @param {Object} scope Optional. The scope to call the function in. If omitted, it will be called in the target's
+ * scope.
+ * @return {Tween} This tween instance (for chaining calls).
**/
p.call = function(callback, params, scope) {
return this._addAction({f:callback, p:params ? params : [this], o:scope ? scope : this._target});
}
/**
- * Queues an action to set the specified props on the specified target. If target is null, it will use this tween's target. Ex. myTween.wait(1000).set({visible:false},foo);
+ * Queues an action to set the specified props on the specified target. If target is null, it will use this tween's
+ * target. Ex. myTween.wait(1000).set({visible:false},foo);
* @method set
- * @param props The properties to set (ex. {visible:false}).
- * @param target Optional. The target to set the properties on. If omitted, they will be set on the tween's target.
- * @return Tween This tween instance (for chaining calls).
+ * @param {Object} props The properties to set (ex. {visible:false}).
+ * @param {Object} target Optional. The target to set the properties on. If omitted, they will be set on the tween's target.
+ * @return {Tween} This tween instance (for chaining calls).
**/
p.set = function(props, target) {
return this._addAction({f:this._set, o:this, p:[props, target ? target : this._target]});
}
/**
- * Queues an action to to play (unpause) the specified tween. This enables you to sequence multiple tweens. Ex. myTween.to({x:100},500).play(otherTween);
+ * Queues an action to to play (unpause) the specified tween. This enables you to sequence multiple tweens.
+ * Ex. myTween.to({x:100},500).play(otherTween);
* @method play
- * @param tween The tween to play.
- * @return Tween This tween instance (for chaining calls).
+ * @param {Tween} tween The tween to play.
+ * @return {Tween} This tween instance (for chaining calls).
**/
p.play = function(tween) {
return this.call(tween.setPaused, [false], tween);
@@ -443,7 +472,8 @@ var p = Tween.prototype;
/**
* Queues an action to to pause the specified tween.
* @method pause
- * @param tween The tween to play. If null, it pauses this tween.
+ * @param {Tween} tween The tween to play. If null, it pauses this tween.
+ * @return {Tween} This tween instance (for chaining calls)
**/
p.pause = function(tween) {
if (!tween) { tween = this; }
@@ -453,9 +483,12 @@ var p = Tween.prototype;
/**
* Advances the tween to a specified position.
* @method setPosition
- * @param value The position to seek to in milliseconds (or ticks if useTicks is true).
- * @param actionsMode Optional parameter specifying how actions are handled (ie. call, set, play, pause): Tween.NONE (0) - run no actions. Tween.LOOP (1) - if new position is less than old, then run all actions between old and duration, then all actions between 0 and new. Defaults to LOOP. Tween.REVERSE (2) - if new position is less than old, run all actions between them in reverse.
- * @return Boolean Returns true if the tween is complete (ie. the full tween has run & loop is false).
+ * @param {Number} value The position to seek to in milliseconds (or ticks if useTicks is true).
+ * @param {Number} actionsMode Optional parameter specifying how actions are handled (ie. call, set, play, pause):
+ * Tween.NONE (0) - run no actions. Tween.LOOP (1) - if new position is less than old, then run all actions
+ * between old and duration, then all actions between 0 and new. Defaults to LOOP. Tween.REVERSE (2) - if new
+ * position is less than old, run all actions between them in reverse.
+ * @return {Boolean} Returns true if the tween is complete (ie. the full tween has run & loop is false).
**/
p.setPosition = function(value, actionsMode) {
if (value < 0) { value = 0; }
@@ -516,7 +549,7 @@ var p = Tween.prototype;
* Advances this tween by the specified amount of time in milliseconds (or ticks if useTicks is true).
* This is normally called automatically by the Tween engine (via Tween.tick), but is exposed for advanced uses.
* @method tick
- * @param delta The time to advance in milliseconds (or ticks if useTicks is true).
+ * @param {Number} delta The time to advance in milliseconds (or ticks if useTicks is true).
**/
p.tick = function(delta) {
if (this._paused) { return; }
@@ -526,7 +559,8 @@ var p = Tween.prototype;
/**
* Pauses or plays this tween.
* @method setPaused
- * @param value Indicates whether the tween should be paused (true) or played (false).
+ * @param {Boolean} value Indicates whether the tween should be paused (true) or played (false).
+ * @return {Tween} This tween instance (for chaining calls)
**/
p.setPaused = function(value) {
this._paused = !!value;
@@ -560,6 +594,8 @@ var p = Tween.prototype;
// private methods:
/**
* @method _updateTargetProps
+ * @param {Object} step
+ * @param {Number} ratio
* @protected
**/
p._updateTargetProps = function(step, ratio) {
@@ -592,13 +628,15 @@ var p = Tween.prototype;
}
}
if (!ignore) { this._target[n] = v; }
-
}
}
/**
* @method _runActions
+ * @param {Number} startPos
+ * @param {Number} endPos
+ * @param {Boolean} includeStart
* @protected
**/
p._runActions = function(startPos, endPos, includeStart) {
@@ -625,6 +663,7 @@ var p = Tween.prototype;
/**
* @method _appendQueueProps
+ * @param {Object} o
* @protected
**/
p._appendQueueProps = function(o) {
@@ -656,6 +695,7 @@ var p = Tween.prototype;
/**
* @method _cloneProps
+ * @param {Object} props
* @protected
**/
p._cloneProps = function(props) {
@@ -668,6 +708,7 @@ var p = Tween.prototype;
/**
* @method _addStep
+ * @param {Object} o
* @protected
**/
p._addStep = function(o) {
@@ -681,6 +722,7 @@ var p = Tween.prototype;
/**
* @method _addAction
+ * @param {Object} o
* @protected
**/
p._addAction = function(o) {
@@ -691,9 +733,11 @@ var p = Tween.prototype;
/**
* @method _set
+ * @param {Object} props
+ * @param {Object} o
* @protected
**/
- p._set = function(props,o) {
+ p._set = function(props, o) {
for (var n in props) {
o[n] = props[n];
}
Please sign in to comment.
Something went wrong with that request. Please try again.