diff --git a/examples/CssExample.html b/examples/CssExample.html index 329e092..24db126 100644 --- a/examples/CssExample.html +++ b/examples/CssExample.html @@ -5,7 +5,8 @@ - + + @@ -24,7 +25,7 @@ createjs.CSSPlugin.install(createjs.Tween); createjs.Ticker.setFPS(20); - var count = 200; + var count = 600; while (--count >= 0) { var box = document.createElement("div"); box.style.width = "6px"; diff --git a/examples/Example.html b/examples/Example.html index bf10571..d844579 100644 --- a/examples/Example.html +++ b/examples/Example.html @@ -6,6 +6,7 @@ + @@ -34,17 +35,17 @@ // set up a tween that tweens between scale 0.3 and 1 every second. createjs.Tween.get(circle,{loop:true}) .wait(1000) // wait for 1 second - .to({scaleX:0.2,scaleY:0.2},500) // jump to the new scale properties (default duration of 0) + .to({scaleX:0.2,scaleY:0.2}) // jump to the new scale properties (default duration of 0) .wait(1000) - .to({scaleX:1,scaleY:1},1000,createjs.Ease.bounceOut); // tween to scaleX/Y of 1 with ease bounce out + .to({scaleX:1,scaleY:1},1000,createjs.Ease.bounceOut) // tween to scaleX/Y of 1 with ease bounce out - // for demonstration purposes, try setting the override (fourth) parameter to true + // for demonstration purposes, try setting the override (third) parameter to true // this will override any previous tweens on the circle and replace them with this tween // resulting in the scaling tween above being cleared. - createjs.Tween.get(circle, {loop:true}, null, false) // get a new tween targeting circle + createjs.Tween.get(circle, {loop:true}, true) // get a new tween targeting circle .to({x:500,y:200,alpha:0.1},1000,createjs.Ease.get(1)) // tween x/y/alpha properties over 1s (1000ms) with ease out - .to({x:0},1000,createjs.Ease.get(-1)) // tween x over 1s with ease in - .to({y:300}) // jump to new y property (defaults to a duration of 0) + .to({x:0},1000,createjs.Ease.get(-1)) // tween x over 0.5s with ease in + .to({y:400}) // jump to new y property (defaults to a duration of 0) .call(console.log, ["wait..."], console) // call console.log("wait...") .wait(800) // wait for 0.8s .to({y:0,alpha:1},300) // tween y/alpha over 0.3s @@ -83,6 +84,6 @@

TweenJS TweenJS Example
- + diff --git a/examples/MotionGuideBlitz.html b/examples/MotionGuideBlitz.html new file mode 100644 index 0000000..e2c4bd0 --- /dev/null +++ b/examples/MotionGuideBlitz.html @@ -0,0 +1,76 @@ + + + + TweenJS: Simple Tween Demo + + + + + + + + + + + + + + + + +
+ + + + + +
+ + + \ No newline at end of file diff --git a/examples/MotionGuideDemo.html b/examples/MotionGuideDemo.html index f6eaf34..8efb563 100644 --- a/examples/MotionGuideDemo.html +++ b/examples/MotionGuideDemo.html @@ -6,6 +6,7 @@ + @@ -28,33 +29,33 @@ stage = new createjs.Stage(canvas); stage.autoClear = true; - // create the visual path - var pathVisuals = new createjs.Shape(); - pathVisuals.graphics.setStrokeStyle(5, 'round', 'round'); - pathVisuals.graphics.beginStroke(('#222')); - pathVisuals.graphics.moveTo(100,100).curveTo(860,100, 860,300); - pathVisuals.graphics.endStroke(); - - // create the square - var square = new createjs.Shape(); - square.graphics.setStrokeStyle(5, 'round', 'round'); - square.graphics.beginStroke(('#000000')); - square.graphics.beginFill("#20D020"); - square.graphics.drawRect(-33,-20,66,40); - square.graphics.endStroke(); - square.graphics.endFill(); - - // animate the square along the path - var tween = createjs.Tween.get(square, {loop:true}, true) - .to({guide:{path:[100,100, 860,100, 860,300]}}, 6000); - - // add the objects to the stage - stage.addChild(pathVisuals); - stage.addChild(square); + var ball = new createjs.Shape(); + ball.graphics.setStrokeStyle(5, 'round', 'round'); + ball.graphics.beginStroke(('#000000')); + ball.graphics.beginFill("#FF0000").drawCircle(0,0,50); + ball.graphics.endStroke(); + ball.graphics.endFill(); + ball.graphics.setStrokeStyle(1, 'round', 'round'); + ball.graphics.beginStroke(('#000000')); + ball.graphics.moveTo(0,0); + ball.graphics.lineTo(50,0); + ball.graphics.endStroke(); + + var tween = createjs.Tween.get(ball, {loop:true}, true) + .to({guide:{path:[100,100, 800,100, 800,300], orient:true}}, 5000) + .wait(1000) + .to({guide:{path:[800,300, 100,300, 100,100], end:0.75, orient:true}}, 3750) + ; + + stage.addChild(ball); createjs.Ticker.addListener(window); } + function handleComplete(tween) { + var ball = tween._target; + + } function tick() { stage.update(); } @@ -68,7 +69,7 @@
diff --git a/examples/MultiMotionDemo.html b/examples/MultiMotionDemo.html index 4308827..8ba654b 100644 --- a/examples/MultiMotionDemo.html +++ b/examples/MultiMotionDemo.html @@ -1,11 +1,12 @@ - TweenJS: Complex Motion Guide Demo + TweenJS: Simple Motion Guide Demo + @@ -16,8 +17,6 @@ + diff --git a/examples/SparkTable.html b/examples/SparkTable.html index 996e2e5..27770e6 100644 --- a/examples/SparkTable.html +++ b/examples/SparkTable.html @@ -6,6 +6,7 @@ + - - - - - - - - -
- - - diff --git a/examples/Tween_Circles.html b/examples/Tween_Circles.html index 93d2fe9..686084d 100644 --- a/examples/Tween_Circles.html +++ b/examples/Tween_Circles.html @@ -6,6 +6,7 @@ + diff --git a/examples/Tween_SparkTable.html b/examples/Tween_SparkTable.html index 6266ed7..36b4634 100644 --- a/examples/Tween_SparkTable.html +++ b/examples/Tween_SparkTable.html @@ -6,6 +6,7 @@ + diff --git a/src/easeljs/events/EventDispatcher.js b/src/easeljs/events/EventDispatcher.js new file mode 100644 index 0000000..6025564 --- /dev/null +++ b/src/easeljs/events/EventDispatcher.js @@ -0,0 +1,173 @@ +/* +* EventDispatcher +* Visit http://createjs.com/ for documentation, updates and examples. +* +* Copyright (c) 2010 gskinner.com, inc. +* +* Permission is hereby granted, free of charge, to any person +* obtaining a copy of this software and associated documentation +* files (the "Software"), to deal in the Software without +* restriction, including without limitation the rights to use, +* copy, modify, merge, publish, distribute, sublicense, and/or sell +* copies of the Software, and to permit persons to whom the +* Software is furnished to do so, subject to the following +* conditions: +* +* The above copyright notice and this permission notice shall be +* included in all copies or substantial portions of the Software. +* +* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES +* OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +* NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT +* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +* WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +* FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +* OTHER DEALINGS IN THE SOFTWARE. +*/ + +// namespace: +this.createjs = this.createjs||{}; + +(function() { + +/** + * Provides methods for managing prioritized queues of event listeners and dispatching events. You can either extend + * this class or mix its methods into an existing prototype or instance by using EventDispatcher.initialize(target). + * @class EventDispatcher + * @constructor + **/ +var EventDispatcher = function() { + this.initialize(); +}; +var p = EventDispatcher.prototype; + + + /** + * Static initializer to mix in EventDispatcher methods. + * @method initialize + * @static + * @param {Object} target The target object to inject EventDispatcher methods into. This can be an instance or a + * prototype. + **/ + EventDispatcher.initialize = function(target) { + target.addEventListener = p.addEventListener; + target.removeEventListener = p.removeEventListener; + target.removeAllEventListeners = p.removeAllEventListeners; + target.hasEventListener = p.hasEventListener; + target.dispatchEvent = p.dispatchEvent; + }; + +// private properties: + /** + * @protected + * @property _listeners + * @type Object + **/ + p._listeners = null; + +// constructor: + /** + * Initialization method. + * @method initialize + * @protected + **/ + p.initialize = function() {}; + +// public methods: + /** + * Adds the specified event listener. + * @method addEventListener + * @param {String} type The string type of the event. + * @param {Function | Object} listener An object with a handleEvent method, or a function that will be called when + * the event is dispatched. + * @return {Function | Object} Returns the listener for chaining or assignment. + **/ + p.addEventListener = function(type, listener) { + var listeners = this._listeners; + if (!listeners) { listeners = this._listeners = {}; } + var arr = listeners[type]; + if (!arr) { arr = listeners[type] = []; } + else { this.removeEventListener(type, listener); } + arr.push(listener); + return listener; + }; + + /** + * Removes the specified event listener. + * @method removeEventListener + * @param {String} type The string type of the event. + * @param {Function | Object} listener The listener function or object. + **/ + p.removeEventListener = function(type, listener) { + var listeners = this._listeners; + if (!listeners) { return; } + var arr = listeners[type]; + if (!arr) { return; } + for (var i=0,l=arr.length; icssSuffixMap property. Currently, + * the top, left, bottom, right, width, height have a "px" suffix appended. * @class CSSPlugin * @constructor **/ diff --git a/src/tweenjs/Ease.js b/src/tweenjs/Ease.js index 19b8ccf..8ac9f41 100644 --- a/src/tweenjs/Ease.js +++ b/src/tweenjs/Ease.js @@ -33,17 +33,21 @@ this.createjs = this.createjs||{}; // constructor: /** - * The Ease class provides a collection of easing functions for use with TweenJS. - * It does not use the standard 4 param easing signature. Instead it uses a single param - * which indicates the current linear ratio (0 to 1) of the tween.
- *
- * Most methods on Ease can be passed directly as easing functions:
- * Tween.get(target).to({x:100}, 500, Ease.linear);
- *
- * However, methods beginning with "get" will return an easing function based on parameter values:
- * Tween.get(target).to({y:200}, 500, Ease.getPowIn(2.2));
- *
- * Equations derived from work by Robert Penner. + * The Ease class provides a collection of easing functions for use with TweenJS. It does not use the standard 4 param + * easing signature. Instead it uses a single param which indicates the current linear ratio (0 to 1) of the tween. + * + * Most methods on Ease can be passed directly as easing functions: + * + * Tween.get(target).to({x:100}, 500, Ease.linear); + * + * However, methods beginning with "get" will return an easing function based on parameter values: + * + * Tween.get(target).to({y:200}, 500, Ease.getPowIn(2.2)); + * + * Please see the spark table demo for an overview + * of the different ease types on TweenJS.com. + * + * Equations derived from work by Robert Penner. * @class Ease * @static **/ diff --git a/src/tweenjs/MotionGuidePlugin.js b/src/tweenjs/MotionGuidePlugin.js index e5297eb..55478ca 100644 --- a/src/tweenjs/MotionGuidePlugin.js +++ b/src/tweenjs/MotionGuidePlugin.js @@ -31,18 +31,25 @@ this.createjs = this.createjs||{}; (function() { /** - * A TweenJS plugin for working with motion guides. To use run MotionGuidePlugin.install() after TweenJS has - * loaded. Next tween the 'guide' property with an object as detailed below. @example - * // Using a Motion Guide - * Tween.get(target).to({guide:{ path:[0,0, 0,200,200,200, 200,0,0,0] }},7000);
- * // Visualizing the line - * graphics.moveTo(0,0).curveTo(0,200,200,200).curveTo(200,0,0,0); + * A TweenJS plugin for working with motion guides. + * + * To use, install the plugin after TweenJS has loaded. Next tween the 'guide' property with an object as detailed below. + * + * createjs.MotionGuidePlugin.install(); + * + *

Example

+ * + * // Using a Motion Guide + * Tween.get(target).to({guide:{ path:[0,0, 0,200,200,200, 200,0,0,0] }},7000); + * // Visualizing the line + * graphics.moveTo(0,0).curveTo(0,200,200,200).curveTo(200,0,0,0); + * * Each path needs pre-computation to ensure there's fast performance. Because of the pre-computation there's no * built in support for path changes mid tween. These are the Guide Object's properties:
    - *
  • path: Required, Array : The x/y points used to draw the path with a moveTo and 1 to n curveTo calls.
    • - *
  • start: Optional, 0-1 : Initial position, default 0 except for when continuing along the same path.
    • - *
  • end: Optional, 0-1 : Final position, default 1 if not specified.
    • - *
  • orient: Optional, bool : Set the target's rotation parallel to the curve at its position.
    • + *
  • path: Required, Array : The x/y points used to draw the path with a moveTo and 1 to n curveTo calls.
    • + *
  • start: Optional, 0-1 : Initial position, default 0 except for when continuing along the same path.
    • + *
  • end: Optional, 0-1 : Final position, default 1 if not specified.
    • + *
  • orient: Optional, bool : Set the target's rotation parallel to the curve at its position.
    • *
* Guide objects should not be shared between tweens even if all properties are identical, the library stores * information on these objects in the background and sharing them can cause unexpected behaviour. Values diff --git a/src/tweenjs/SamplePlugin.js b/src/tweenjs/SamplePlugin.js index 9111145..cfda4f2 100644 --- a/src/tweenjs/SamplePlugin.js +++ b/src/tweenjs/SamplePlugin.js @@ -31,12 +31,11 @@ this.createjs = this.createjs||{}; (function() { /** - * A sample TweenJS plugin. This plugin does not actually affect tweens in any way, it's - * merely intended to document how to build TweenJS plugins. Please look at the code for - * inline comments.

- * A TweenJS plugin is simply an object that exposes one property (priority), and three - * methods (init, step, and tween). Generally a plugin will also expose an install method - * as well, though this is not strictly necessary. + * A sample TweenJS plugin. This plugin does not actually affect tweens in any way, it's merely intended to document + * how to build TweenJS plugins. Please look at the code for inline comments. + * + * A TweenJS plugin is simply an object that exposes one property (priority), and three methods (init, step, and tween). + * Generally a plugin will also expose an install method as well, though this is not strictly necessary. * @class SamplePlugin * @constructor **/ @@ -46,18 +45,16 @@ var SamplePlugin = function() { // static interface: /** - * Used by TweenJS to determine when to call this plugin. Plugins with higher priority - * have their methods called before plugins with lower priority. The priority value - * can be any positive or negative number. + * Used by TweenJS to determine when to call this plugin. Plugins with higher priority have their methods called + * before plugins with lower priority. The priority value can be any positive or negative number. * @property priority * @static **/ SamplePlugin.priority = 0; /** - * Installs this plugin for use with TweenJS, and registers for a list of properties - * that this plugin will operate with. Call this once after TweenJS is loaded - * to enable this plugin. + * Installs this plugin for use with TweenJS, and registers for a list of properties that this plugin will operate + * with. Call this once after TweenJS is loaded to enable this plugin. * @method install * @static **/ @@ -67,9 +64,8 @@ var SamplePlugin = function() { }; /** - * Called by TweenJS when a new tween property initializes that this plugin is - * registered for. Generally, the call to Plugin.init will be immediately followed by a - * call to Plugin.to. + * Called by TweenJS when a new tween property initializes that this plugin is registered for. Generally, the call + * to Plugin.init will be immediately followed by a call to Plugin.to. * @method init * @param {Tween} tween The related tween instance. * @param {String} prop The name of the property that is being initialized. @@ -86,8 +82,8 @@ var SamplePlugin = function() { }; /** - * Called by TweenJS when a new step is added to a tween that includes a property the - * plugin is registered for (ie. a new "to" action is added to a tween). + * Called by TweenJS when a new step is added to a tween that includes a property the plugin is registered for (ie. + * a new "to" action is added to a tween). * @method init * @param {Tween} tween The related tween instance. * @param {String} prop The name of the property being tweened. diff --git a/src/tweenjs/Timeline.js b/src/tweenjs/Timeline.js index e5f365d..4adeb7f 100644 --- a/src/tweenjs/Timeline.js +++ b/src/tweenjs/Timeline.js @@ -31,13 +31,15 @@ this.createjs = this.createjs||{}; (function() { - /** - * The Timeline class synchronizes multiple tweens and allows them to be controlled as a group. + * The Timeline class synchronizes multiple tweens and allows them to be controlled as a group. Please note that if a + * timeline is looping, the tweens on it may appear to loop even if the "loop" property of the tween is false. * @class Timeline * @param tweens An array of Tweens to add to this timeline. See addTween for more info. - * @param labels An object defining labels for using gotoAndPlay/Stop. See setLabels for details. - * @param props The configuration properties to apply to this tween instance (ex. {loop:true}). All properties default to false. Supported props are:
    + * @param labels An object defining labels for using gotoAndPlay/Stop. See {{#crossLink "Timeline/setLabels"}}{{/crossLink}} + * for details. + * @param props The configuration properties to apply to this tween instance (ex. {loop:true}). All properties default to + * false. Supported props are:
      *
    • loop: sets the loop property on this tween.
      • *
    • useTicks: uses ticks for all durations instead of milliseconds.
      • *
    • ignoreGlobalPause: sets the ignoreGlobalPause property on this tween.
      • diff --git a/src/tweenjs/Tween.js b/src/tweenjs/Tween.js index c8defee..eebe45f 100644 --- a/src/tweenjs/Tween.js +++ b/src/tweenjs/Tween.js @@ -27,13 +27,32 @@ */ /** - * 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:
      - * For example:
      Tween.get(target).wait(500).to({alpha:0,visible:false},1000).call(onComplete);
      - * 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. + * The TweenJS Javascript library provides a simple but powerful tweening interface. It supports tweening of both + * numeric object properties & CSS style properties, and allows you to chain tweens and actions together to create + * complex sequences. + * + *

      Simple Tween

      + * This tween will tween the target's alpha property from 0 to 1 for 1s then call the onComplete function. + * + * target.alpha = 0; + * Tween.get(target).to({alpha:1}, 1000).call(onComplete); + * function onComplete() { + * //Tween complete + * } + * + *

      Chainable Tween

      + * 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. + * + * target.alpha = 1; + * Tween.get(target).wait(500).to({alpha:0, visible:false}, 1000).call(onComplete); + * function onComplete() { + * //Tween complete + * } + * * @module TweenJS */ - + // TODO: possibly add a END actionsMode (only runs actions that == position)? // TODO: evaluate a way to decouple paused from tick registration. @@ -42,7 +61,33 @@ this.createjs = this.createjs||{}; (function() { /** - * Returns a new Tween instance. See Tween.get for param documentation. + * A Tween instance tweens properties for a single target. Instance methods can be chained for easy construction and sequencing: + * + *

      Example

      + * + * target.alpha = 1; + * Tween.get(target) + * .wait(500) + * .to({alpha:0, visible:false}, 1000) + * .call(onComplete); + * function onComplete() { + * //Tween complete + * } + * + * Multiple tweens can point to the same instance, however if they affect the same properties there could be unexpected + * behaviour. To stop all tweens on an object, use {{#crossLink "Tween/removeTweens"}}{{/crossLink}} or pass override:true + * in the props argument. + * + * Tween.get(target, {override:true}).to({x:100}); + * + * Subscribe to the "change" event to get notified when a property of the target is changed. + * + * Tween.get(target, {override:true}).to({x:100}).addEventListener("change", handleChange); + * function handleChange(event) { + * // The tween changed. + * } + * + * See the Tween {{#crossLink "Tween/get"}}{{/crossLink}} method for additional param documentation. * @class Tween * @constructor */ @@ -106,10 +151,12 @@ var p = Tween.prototype; /** * Returns a new tween instance. This is functionally identical to using "new Tween(...)", but looks cleaner * with the chained syntax of TweenJS. + * @example + * var tween = createjs.Tween.get(target); * @method get * @static * @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}). + * @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:
        *
      • loop: sets the loop property on this tween.
        • *
      • useTicks: uses ticks for all durations instead of milliseconds.
        • @@ -117,14 +164,15 @@ var p = Tween.prototype; *
      • override: if true, Tween.removeTweens(target) will be called to remove any other tweens with the same target. *
      • paused: indicates whether to start the tween paused.
        • *
      • position: indicates the initial position for this tween.
        • - *
      • onChanged: specifies an onChange handler for this tween.
        • + *
      • onChange: specifies an onChange handler for this tween. Note that this is deprecated in favour of the + * "change" event.
        • *
      - * @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). + * @param {Object} [pluginData] An object containing data for use by installed plugins. See individual + * plugins' documentation for details. + * @param {Boolean} [override=false] 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. + * applied to the returned tween instance. **/ Tween.get = function(target, props, pluginData, override) { if (override) { Tween.removeTweens(target); } @@ -137,9 +185,9 @@ var p = Tween.prototype; * @method tick * @static * @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. + * 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. @@ -153,7 +201,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. + * Removes all existing tweens for a target. This is called automatically by new tweens if the override prop is true. * @method removeTweens * @static * @param {Object} target The target object to remove existing tweens from. @@ -175,7 +223,7 @@ var p = Tween.prototype; * @method hasActiveTweens * @static * @param {Object} target Optional. If not specified, the return value will indicate if there are any active tweens - * on any target. + * on any target. * @return {Boolean} A boolean indicating whether there are any active tweens. **/ Tween.hasActiveTweens = function(target) { @@ -188,8 +236,8 @@ var p = Tween.prototype; * example of how to write TweenJS plugins. * @method installPlugin * @static - * @param {Object} plugin - * @param {Array} properties + * @param {Object} plugin The plugin class to install + * @param {Array} properties An array of properties that the plugin will handle. **/ Tween.installPlugin = function(plugin, properties) { var priority = plugin.priority; @@ -225,11 +273,22 @@ var p = Tween.prototype; if (i != -1) { Tween._tweens.splice(i,1); } } } + + // mix-ins: + // EventDispatcher methods: + p.addEventListener = null; + p.removeEventListener = null; + p.removeAllEventListeners = null; + p.dispatchEvent = null; + p.hasEventListener = null; + p._listeners = null; + + createjs.EventDispatcher.initialize(p); // inject EventDispatcher methods. // public properties: /** * Causes this tween to continue playing when a global pause is active. For example, if TweenJS is using Ticker, - * then setting this to true (the default) will cause this tween to be paused when Ticker.setPaused(true) is called. + * then setting this to true (the default) will cause this tween to be paused when Ticker.setPaused(true) is called. * See Tween.tick() for more info. Can be set via the props param. * @property ignoreGlobalPause * @type Boolean @@ -240,7 +299,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 + * @type {Boolean} * @default false **/ p.loop = false; @@ -250,38 +309,47 @@ var p = Tween.prototype; * This value is automatically updated as you modify the tween. Changing it directly could result in unexpected * behaviour. * @property duration - * @type Number + * @type {Number} * @default 0 **/ p.duration = 0; /** * Allows you to specify data that will be used by installed plugins. Each plugin uses this differently, but in general - * you specify data by setting it to a property of pluginData with the same name as the plugin class.
      - * Ex. myTween.pluginData.PluginClassName = data;
      + * you specify data by setting it to a property of pluginData with the same name as the plugin class. + * @example + * myTween.pluginData.PluginClassName = data; *
      * Also, most plugins support a property to enable or disable them. This is typically the plugin class name followed by "_enabled".
      - * Ex. myTween.pluginData.PluginClassName_enabled = false;
      + * @example + * myTween.pluginData.PluginClassName_enabled = false;
      *
      * Some plugins also store instance data in this object, usually in a property named _PluginClassName. * See the documentation for individual plugins for more details. * @property pluginData - * @type Object + * @type {Object} **/ p.pluginData = null; /** * Called whenever the tween's position changes with a single parameter referencing this tween instance. * @property onChange - * @type Function + * @type {Function} **/ p.onChange = null; + + /** + * Called whenever the tween's position changes with a single parameter referencing this tween instance. + * @event change + * @since 0.4.0 + **/ + p.change = null; /** * Read-only. The target of this tween. This is the object on which the tweened properties will be changed. Changing * this property after the tween is created will not have any effect. * @property target - * @type Object + * @type {Object} **/ p.target = null; @@ -289,7 +357,7 @@ var p = Tween.prototype; * Read-only. The current normalized position of the tween. This will always be a value between 0 and duration. * Changing this property directly will have no effect. * @property position - * @type Object + * @type {Object} **/ p.position = null; @@ -297,7 +365,7 @@ var p = Tween.prototype; /** * @property _paused - * @type Boolean + * @type {Boolean} * @default false * @protected **/ @@ -305,28 +373,28 @@ var p = Tween.prototype; /** * @property _curQueueProps - * @type Object + * @type {Object} * @protected **/ p._curQueueProps = null; /** * @property _initQueueProps - * @type Object + * @type {Object} * @protected **/ p._initQueueProps = null; /** * @property _steps - * @type Array + * @type {Array} * @protected **/ p._steps = null; /** * @property _actions - * @type Array + * @type {Array} * @protected **/ p._actions = null; @@ -334,7 +402,7 @@ var p = Tween.prototype; /** * Raw position. * @property _prevPosition - * @type Number + * @type {Number} * @default 0 * @protected **/ @@ -343,7 +411,7 @@ var p = Tween.prototype; /** * The position within the current step. * @property _stepPosition - * @type Number + * @type {Number} * @default 0 * @protected */ @@ -352,7 +420,7 @@ var p = Tween.prototype; /** * Normalized position. * @property _prevPos - * @type Number + * @type {Number} * @default -1 * @protected **/ @@ -360,14 +428,14 @@ var p = Tween.prototype; /** * @property _target - * @type Object + * @type {Object} * @protected **/ p._target = null; /** * @property _useTicks - * @type Boolean + * @type {Boolean} * @default false * @protected **/ @@ -404,8 +472,11 @@ var p = Tween.prototype; // public methods: /** * Queues a wait (essentially an empty tween). + * @example + * //This tween will wait 1s before alpha is faded to 0. + * createjs.Tween.get(target).wait(1000).to({alpha:0}, 1000); * @method wait - * @param {Number} duration The duration of the wait in milliseconds (or in ticks if useTicks is true). + * @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) { @@ -418,10 +489,12 @@ var p = Tween.prototype; * Queues a tween from the current values to the target properties. Set duration to 0 to jump to these value. * 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. + * @example + * createjs.Tween.get(target).to({alpha:0}, 1000); * @method to - * @param {Object} props An object specifying property target values for this tween (Ex. {x:300} would tween the x + * @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). + * @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). @@ -432,8 +505,10 @@ 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. + * @example + * //would call myFunction() after 1s. + * myTween.wait(1000).call(myFunction); * @method call * @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 @@ -449,9 +524,11 @@ var p = Tween.prototype; // TODO: add clarification between this and a 0 duration .to: /** * 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); + * target. + * @example + * myTween.wait(1000).set({visible:false},foo); * @method set - * @param {Object} props The properties to set (ex. {visible:false}). + * @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). **/ @@ -461,7 +538,8 @@ var p = Tween.prototype; /** * 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); + * @example + * myTween.to({x:100},500).play(otherTween); * @method play * @param {Tween} tween The tween to play. * @return {Tween} This tween instance (for chaining calls). @@ -486,8 +564,8 @@ var p = Tween.prototype; * @method setPosition * @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 + * 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). **/ @@ -543,14 +621,15 @@ var p = Tween.prototype; if (end) { this.setPaused(true); } this.onChange&&this.onChange(this); + this.dispatchEvent("change"); return end; } /** - * 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. + * 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 {Number} 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; }