webgui/www/extras/yui/docs/animation/overview-summary-Anim.js.html
JT Smith 4f68a0933c added YUI and YUI-ext
fixed the resizable text area with IE problem
fixed the ad space with IE problem
merged the 7.2.0 and 7.1.4 change logs
2006-11-07 23:15:57 +00:00

624 lines
24 KiB
HTML

<html>
<head>
<title>
JavaScript Documentation -
Anim.js
</title>
<link href="stylesheet.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="header">
<h1>JavaScript Documentation</h1>
<h3><a href="./index.html">Animation Utility</a></h3>
<div class="breadcrumbs">
<a href="javascript: alert('This location is TBD');">Home</a>
&gt;
<a href="./index.html">Animation Utility</a>
&gt;
<strong>Anim.js</strong>
</div>
</div>
<div id="body">
<div class="nav">
<div class="module resources">
<ul class="content">
<li><a href="overview-tree.html">Tree View</a></li>
<li><a href="index-all.html">Element Index</a></li>
</ul>
</div>
<div class="module">
<h4><a href="./allclasses-noframe.html">Classes</a></h4>
<ul class="content">
<li>
<a href="YAHOO.util.html">
YAHOO.util</a>
</li>
<li>
<a href="YAHOO.util.Anim.html">
YAHOO.util.Anim</a>
</li>
<li>
<a href="YAHOO.util.AnimMgr.html">
YAHOO.util.AnimMgr</a>
</li>
<li>
<a href="YAHOO.util.Bezier.html">
YAHOO.util.Bezier</a>
</li>
</ul>
</div>
<div class="module">
<h4><a href="./overview-summary.html">Files</a></h4>
<ul class="content">
<li>
<a href="overview-summary-Anim.js.html">
Anim.js</a>
</li>
<li>
<a href="overview-summary-AnimMgr.js.html">
AnimMgr.js</a>
</li>
<li>
<a href="overview-summary-Bezier.js.html">
Bezier.js</a>
</li>
<li>
<a href="overview-summary-ColorAnim.js.html">
ColorAnim.js</a>
</li>
<li>
<a href="overview-summary-Easing.js.html">
Easing.js</a>
</li>
<li>
<a href="overview-summary-Motion.js.html">
Motion.js</a>
</li>
<li>
<a href="overview-summary-Scroll.js.html">
Scroll.js</a>
</li>
</ul>
</div>
</div>
<div class="main">
<h2>Anim.js</h2>
<div class="meta">
</div>
<div class="quick-links">
<strong>Quick Links:</strong>&nbsp;
<a href="#classSummary">Class Summary</a> |
<a href="#source">Source Code</a>
</div>
<div class="section class summaries">
<h3><a name="classSummary">Class Summary</a> <span class="top">[<a href="#top">top</a>]</span></h3>
<div class="content">
<table border="1" cellpadding="3" cellspacing="0">
<tr>
<td class="name">
<a href="YAHOO.util.Anim.html">YAHOO.util.Anim</a>
</td>
<td class="overview">Base animation class that provides the interface for building animated effects.</td>
</tr>
</table>
</div>
</div>
<div class="section source">
<h3><a name="source">Souce Code</a> <span class="top">[<a href="#top">top</a>]</span></h3>
<pre class="sourceview"><span class="comment">/*
Copyright (c) 2006, Yahoo! Inc. All rights reserved.
Code licensed under the BSD License:
http://developer.yahoo.net/yui/license.txt
Version: 0.10.0
*/</span>
<span class="comment">/**
*
* Base class for animated DOM objects.
* <span class="attrib">@class</span> Base animation class that provides the interface for building animated effects.
* &lt;p&gt;Usage: var myAnim = new YAHOO.util.Anim(el, { width: { from: 10, to: 100 } }, 1, YAHOO.util.Easing.easeOut);&lt;/p&gt;
* <span class="attrib">@requires</span> YAHOO.util.AnimMgr
* <span class="attrib">@requires</span> YAHOO.util.Easing
* <span class="attrib">@requires</span> YAHOO.util.Dom
* <span class="attrib">@requires</span> YAHOO.util.Event
* <span class="attrib">@requires</span> YAHOO.util.CustomEvent
* <span class="attrib">@constructor</span>
* <span class="attrib">@param</span> {String or HTMLElement} el Reference to the element that will be animated
* <span class="attrib">@param</span> {Object} attributes The attribute(s) to be animated.
* Each attribute is an object with at minimum a "to" or "by" member defined.
* Additional optional members are "from" (defaults to current value), "units" (defaults to "px").
* All attribute names use camelCase.
* <span class="attrib">@param</span> {Number} duration (optional, defaults to 1 second) Length of animation (frames or seconds), defaults to time-based
* <span class="attrib">@param</span> {Function} method (optional, defaults to YAHOO.util.Easing.easeNone) Computes the values that are applied to the attributes per frame (generally a YAHOO.util.Easing method)
*/</span>
YAHOO.util.Anim = <span class="reserved">function</span>(el, attributes, duration, method) {
<span class="reserved">if</span> (el) {
<span class="reserved">this</span>.init(el, attributes, duration, method);
}
};
YAHOO.util.Anim.<span class="reserved">prototype</span> = {
<span class="comment">/**
* toString method
* <span class="attrib">@return</span> {String} string represenation of anim obj
*/</span>
toString: <span class="reserved">function</span>() {
var el = <span class="reserved">this</span>.getEl();
var id = el.id || el.tagName;
<span class="reserved">return</span> (<span class="literal">"Anim "</span> + id);
},
patterns: { <span class="comment">// cached for performance</span>
noNegatives: /width|height|opacity|padding/i, <span class="comment">// keep at zero or above</span>
offsetAttribute: /^((width|height)|(top|left))$/, <span class="comment">// use offsetValue as default</span>
defaultUnit: /width|height|top$|bottom$|left$|right$/i, <span class="comment">// use 'px' by default</span>
offsetUnit: /\d+(em|%|en|ex|pt|in|cm|mm|pc)$/i <span class="comment">// IE may return these, so convert these to offset</span>
},
<span class="comment">/**
* Returns the value computed by the animation's "method".
* <span class="attrib">@param</span> {String} attr The name of the attribute.
* <span class="attrib">@param</span> {Number} start The value this attribute should start from for this animation.
* <span class="attrib">@param</span> {Number} end The value this attribute should end at for this animation.
* <span class="attrib">@return</span> {Number} The Value to be applied to the attribute.
*/</span>
doMethod: <span class="reserved">function</span>(attr, start, end) {
<span class="reserved">return</span> <span class="reserved">this</span>.method(<span class="reserved">this</span>.currentFrame, start, end - start, <span class="reserved">this</span>.totalFrames);
},
<span class="comment">/**
* Applies a value to an attribute
* <span class="attrib">@param</span> {String} attr The name of the attribute.
* <span class="attrib">@param</span> {Number} val The value to be applied to the attribute.
* <span class="attrib">@param</span> {String} unit The unit ('px', '%', etc.) of the value.
*/</span>
setAttribute: <span class="reserved">function</span>(attr, val, unit) {
<span class="reserved">if</span> ( <span class="reserved">this</span>.patterns.noNegatives.test(attr) ) {
val = (val &gt; 0) ? val : 0;
}
YAHOO.util.Dom.setStyle(<span class="reserved">this</span>.getEl(), attr, val + unit);
},
<span class="comment">/**
* Returns current value of the attribute.
* <span class="attrib">@param</span> {String} attr The name of the attribute.
* <span class="attrib">@return</span> {Number} val The current value of the attribute.
*/</span>
getAttribute: <span class="reserved">function</span>(attr) {
var el = <span class="reserved">this</span>.getEl();
var val = YAHOO.util.Dom.getStyle(el, attr);
<span class="reserved">if</span> (val !== <span class="literal">'auto'</span> &amp;&amp; !<span class="reserved">this</span>.patterns.offsetUnit.test(val)) {
<span class="reserved">return</span> parseFloat(val);
}
var a = <span class="reserved">this</span>.patterns.offsetAttribute.exec(attr) || [];
var pos = ( typeof a[1] !== <span class="literal">'undefined'</span> ) ? true : false; <span class="comment">// top or left</span>
var box = ( typeof a[2] !== <span class="literal">'undefined'</span> ) ? true : false; <span class="comment">// width or height</span>
<span class="comment">// use offsets for width/height and abs pos top/left</span>
<span class="reserved">if</span> ( box || (YAHOO.util.Dom.getStyle(el, <span class="literal">'position'</span>) == <span class="literal">'absolute'</span> &amp;&amp; pos) ) {
val = el[<span class="literal">'offset'</span> + a[0].charAt(0).toUpperCase() + a[0].substr(1)];
}
<span class="reserved">return</span> val;
},
<span class="comment">/**
* Returns the unit to use when none is supplied.
* Applies the "defaultUnit" test to decide whether to use pixels or not
* <span class="attrib">@param</span> {attr} attr The name of the attribute.
* <span class="attrib">@return</span> {String} The default unit to be used.
*/</span>
getDefaultUnit: <span class="reserved">function</span>(attr) {
<span class="reserved">if</span> ( <span class="reserved">this</span>.patterns.defaultUnit.test(attr) ) {
<span class="reserved">return</span> <span class="literal">'px'</span>;
}
<span class="reserved">return</span> <span class="literal">''</span>;
},
<span class="comment">/**
* Sets the actual values to be used during the animation.
* Should only be needed for subclass use.
* <span class="attrib">@param</span> {Object} attr The attribute object
* <span class="attrib">@private</span>
*/</span>
setRuntimeAttribute: <span class="reserved">function</span>(attr) {
var start;
var end;
var attributes = <span class="reserved">this</span>.attributes;
<span class="reserved">this</span>.runtimeAttributes[attr] = {};
var isset = <span class="reserved">function</span>(prop) {
<span class="reserved">return</span> (typeof prop !== <span class="literal">'undefined'</span>);
};
<span class="reserved">if</span> ( !isset(attributes[attr][<span class="literal">'to'</span>]) &amp;&amp; !isset(attributes[attr][<span class="literal">'by'</span>]) ) {
<span class="reserved">return</span> false; <span class="comment">// note return; nothing to animate to</span>
}
start = ( isset(attributes[attr][<span class="literal">'from'</span>]) ) ? attributes[attr][<span class="literal">'from'</span>] : <span class="reserved">this</span>.getAttribute(attr);
<span class="comment">// To beats by, per SMIL 2.1 spec</span>
<span class="reserved">if</span> ( isset(attributes[attr][<span class="literal">'to'</span>]) ) {
end = attributes[attr][<span class="literal">'to'</span>];
} <span class="reserved">else</span> <span class="reserved">if</span> ( isset(attributes[attr][<span class="literal">'by'</span>]) ) {
<span class="reserved">if</span> (start.constructor == Array) {
end = [];
<span class="reserved">for</span> (var i = 0, len = start.length; i &lt; len; ++i) {
end[i] = start[i] + attributes[attr][<span class="literal">'by'</span>][i];
}
} <span class="reserved">else</span> {
end = start + attributes[attr][<span class="literal">'by'</span>];
}
}
<span class="reserved">this</span>.runtimeAttributes[attr].start = start;
<span class="reserved">this</span>.runtimeAttributes[attr].end = end;
<span class="comment">// set units if needed</span>
<span class="reserved">this</span>.runtimeAttributes[attr].unit = ( isset(attributes[attr].unit) ) ? attributes[attr][<span class="literal">'unit'</span>] : <span class="reserved">this</span>.getDefaultUnit(attr);
},
<span class="comment">/**
* <span class="attrib">@param</span> {String or HTMLElement} el Reference to the element that will be animated
* <span class="attrib">@param</span> {Object} attributes The attribute(s) to be animated.
* Each attribute is an object with at minimum a "to" or "by" member defined.
* Additional optional members are "from" (defaults to current value), "units" (defaults to "px").
* All attribute names use camelCase.
* <span class="attrib">@param</span> {Number} duration (optional, defaults to 1 second) Length of animation (frames or seconds), defaults to time-based
* <span class="attrib">@param</span> {Function} method (optional, defaults to YAHOO.util.Easing.easeNone) Computes the values that are applied to the attributes per frame (generally a YAHOO.util.Easing method)
*/</span>
init: <span class="reserved">function</span>(el, attributes, duration, method) {
<span class="comment">/**
* Whether or not the animation is running.
* <span class="attrib">@private</span>
* <span class="attrib">@type</span> Boolean
*/</span>
var isAnimated = false;
<span class="comment">/**
* A Date object that is created when the animation begins.
* <span class="attrib">@private</span>
* <span class="attrib">@type</span> Date
*/</span>
var startTime = null;
<span class="comment">/**
* The number of frames this animation was able to execute.
* <span class="attrib">@private</span>
* <span class="attrib">@type</span> Int
*/</span>
var actualFrames = 0;
<span class="comment">/**
* The element to be animated.
* <span class="attrib">@private</span>
* <span class="attrib">@type</span> HTMLElement
*/</span>
el = YAHOO.util.Dom.get(el);
<span class="comment">/**
* The collection of attributes to be animated.
* Each attribute must have at least a "to" or "by" defined in order to animate.
* If "to" is supplied, the animation will end with the attribute at that value.
* If "by" is supplied, the animation will end at that value plus its starting value.
* If both are supplied, "to" is used, and "by" is ignored.
* <span class="attrib">@member</span> YAHOO#util#Anim
* Optional additional member include "from" (the value the attribute should start animating from, defaults to current value), and "unit" (the units to apply to the values).
* <span class="attrib">@type</span> Object
*/</span>
<span class="reserved">this</span>.attributes = attributes || {};
<span class="comment">/**
* The length of the animation. Defaults to "1" (second).
* <span class="attrib">@type</span> Number
*/</span>
<span class="reserved">this</span>.duration = duration || 1;
<span class="comment">/**
* The method that will provide values to the attribute(s) during the animation.
* Defaults to "YAHOO.util.Easing.easeNone".
* <span class="attrib">@type</span> Function
*/</span>
<span class="reserved">this</span>.method = method || YAHOO.util.Easing.easeNone;
<span class="comment">/**
* Whether or not the duration should be treated as seconds.
* Defaults to true.
* <span class="attrib">@type</span> Boolean
*/</span>
<span class="reserved">this</span>.useSeconds = true; <span class="comment">// default to seconds</span>
<span class="comment">/**
* The location of the current animation on the timeline.
* In time-based animations, this is used by AnimMgr to ensure the animation finishes on time.
* <span class="attrib">@type</span> Int
*/</span>
<span class="reserved">this</span>.currentFrame = 0;
<span class="comment">/**
* The total number of frames to be executed.
* In time-based animations, this is used by AnimMgr to ensure the animation finishes on time.
* <span class="attrib">@type</span> Int
*/</span>
<span class="reserved">this</span>.totalFrames = YAHOO.util.AnimMgr.fps;
<span class="comment">/**
* Returns a reference to the animated element.
* <span class="attrib">@return</span> {HTMLElement}
*/</span>
<span class="reserved">this</span>.getEl = <span class="reserved">function</span>() { <span class="reserved">return</span> el; };
<span class="comment">/**
* Checks whether the element is currently animated.
* <span class="attrib">@return</span> {Boolean} current value of isAnimated.
*/</span>
<span class="reserved">this</span>.isAnimated = <span class="reserved">function</span>() {
<span class="reserved">return</span> isAnimated;
};
<span class="comment">/**
* Returns the animation start time.
* <span class="attrib">@return</span> {Date} current value of startTime.
*/</span>
<span class="reserved">this</span>.getStartTime = <span class="reserved">function</span>() {
<span class="reserved">return</span> startTime;
};
<span class="reserved">this</span>.runtimeAttributes = {};
var logger = {};
logger.log = <span class="reserved">function</span>() {YAHOO.log.apply(window, arguments)};
logger.log(<span class="literal">'creating new instance of '</span> + <span class="reserved">this</span>);
<span class="comment">/**
* Starts the animation by registering it with the animation manager.
*/</span>
<span class="reserved">this</span>.animate = <span class="reserved">function</span>() {
<span class="reserved">if</span> ( <span class="reserved">this</span>.isAnimated() ) { <span class="reserved">return</span> false; }
<span class="reserved">this</span>.currentFrame = 0;
<span class="reserved">this</span>.totalFrames = ( <span class="reserved">this</span>.useSeconds ) ? Math.ceil(YAHOO.util.AnimMgr.fps * <span class="reserved">this</span>.duration) : <span class="reserved">this</span>.duration;
YAHOO.util.AnimMgr.registerElement(<span class="reserved">this</span>);
};
<span class="comment">/**
* Stops the animation. Normally called by AnimMgr when animation completes.
*/</span>
<span class="reserved">this</span>.stop = <span class="reserved">function</span>() {
YAHOO.util.AnimMgr.stop(<span class="reserved">this</span>);
};
var onStart = <span class="reserved">function</span>() {
<span class="reserved">this</span>.onStart.fire();
<span class="reserved">for</span> (var attr in <span class="reserved">this</span>.attributes) {
<span class="reserved">this</span>.setRuntimeAttribute(attr);
}
isAnimated = true;
actualFrames = 0;
startTime = new Date();
};
<span class="comment">/**
* Feeds the starting and ending values for each animated attribute to doMethod once per frame, then applies the resulting value to the attribute(s).
* <span class="attrib">@private</span>
*/</span>
var onTween = <span class="reserved">function</span>() {
var data = {
duration: new Date() - <span class="reserved">this</span>.getStartTime(),
currentFrame: <span class="reserved">this</span>.currentFrame
};
data.toString = <span class="reserved">function</span>() {
<span class="reserved">return</span> (
<span class="literal">'duration: '</span> + data.duration +
<span class="literal">', currentFrame: '</span> + data.currentFrame
);
};
<span class="reserved">this</span>.onTween.fire(data);
var runtimeAttributes = <span class="reserved">this</span>.runtimeAttributes;
<span class="reserved">for</span> (var attr in runtimeAttributes) {
<span class="reserved">this</span>.setAttribute(attr, <span class="reserved">this</span>.doMethod(attr, runtimeAttributes[attr].start, runtimeAttributes[attr].end), runtimeAttributes[attr].unit);
}
actualFrames += 1;
};
var onComplete = <span class="reserved">function</span>() {
var actual_duration = (new Date() - startTime) / 1000 ;
var data = {
duration: actual_duration,
frames: actualFrames,
fps: actualFrames / actual_duration
};
data.toString = <span class="reserved">function</span>() {
<span class="reserved">return</span> (
<span class="literal">'duration: '</span> + data.duration +
<span class="literal">', frames: '</span> + data.frames +
<span class="literal">', fps: '</span> + data.fps
);
};
isAnimated = false;
actualFrames = 0;
<span class="reserved">this</span>.onComplete.fire(data);
};
<span class="comment">/**
* Custom event that fires after onStart, useful in subclassing
* <span class="attrib">@private</span>
*/</span>
<span class="reserved">this</span>._onStart = new YAHOO.util.CustomEvent(<span class="literal">'_start'</span>, <span class="reserved">this</span>, true);
<span class="comment">/**
* Custom event that fires when animation begins
* Listen via subscribe method (e.g. myAnim.onStart.subscribe(someFunction)
*/</span>
<span class="reserved">this</span>.onStart = new YAHOO.util.CustomEvent(<span class="literal">'start'</span>, <span class="reserved">this</span>);
<span class="comment">/**
* Custom event that fires between each frame
* Listen via subscribe method (e.g. myAnim.onTween.subscribe(someFunction)
*/</span>
<span class="reserved">this</span>.onTween = new YAHOO.util.CustomEvent(<span class="literal">'tween'</span>, <span class="reserved">this</span>);
<span class="comment">/**
* Custom event that fires after onTween
* <span class="attrib">@private</span>
*/</span>
<span class="reserved">this</span>._onTween = new YAHOO.util.CustomEvent(<span class="literal">'_tween'</span>, <span class="reserved">this</span>, true);
<span class="comment">/**
* Custom event that fires when animation ends
* Listen via subscribe method (e.g. myAnim.onComplete.subscribe(someFunction)
*/</span>
<span class="reserved">this</span>.onComplete = new YAHOO.util.CustomEvent(<span class="literal">'complete'</span>, <span class="reserved">this</span>);
<span class="comment">/**
* Custom event that fires after onComplete
* <span class="attrib">@private</span>
*/</span>
<span class="reserved">this</span>._onComplete = new YAHOO.util.CustomEvent(<span class="literal">'_complete'</span>, <span class="reserved">this</span>, true);
<span class="reserved">this</span>._onStart.subscribe(onStart);
<span class="reserved">this</span>._onTween.subscribe(onTween);
<span class="reserved">this</span>._onComplete.subscribe(onComplete);
}
};
</pre>
</div>
</div>
</div>
<div id="footer">
<hr />
Copyright &copy; 2004 - 2005 Yahoo! Inc. All rights reserved.
<br />
Yahoo! Confidential.
<br /><br />
Documentation generated by <a href="http://jsdoc.sourceforge.net/">JSDoc</a>
version 1.9.5.8
</div>
</body>
</html>