Class glow.anim.Anim

Extends glow.events.Target.

Defined in: core.js.

Class Summary
Constructor Attributes	Constructor Name and Description
	glow.anim.Anim(duration, opts) Animate an object.

Field Summary
Field Attributes	Field Name and Description
	destroyOnComplete Destroy the animation once it completes (unless it loops).
	duration Length of the animation in seconds.
	loop Loop the animation? This value can be changed while an animation is playing.
	playing `true` if the animation is playing.
	position Position of the animation in seconds.
	tween The tween used by the animation.
	value Current tweened value of the animation, usually between 0 & 1.

Method Summary
Method Attributes	Method Name and Description
	destroy() Destroys the animation & detaches references to objects This frees memory & is called automatically when an animation completes.
	goTo(pos) Goes to a specific point in the animation.
	pingPong() Alters the animation so it plays forward, then in reverse The duration of the animation is doubled.
	prop(propertyName, conf) Animate a property of an object.
	reverse() Reverses this animation Adjusts the tween of this animation so it plays in reverse.
	start(position) Starts playing the animation If the animation is already playing, this has no effect.
	stop() Stops the animation playing.
	target(newTarget) Set the object for subsequent calls to {@link glow.anim.Anim#prop prop} to act on.

Methods borrowed from class glow.events.Target:: detach, fire, on

Event Summary
Event Attributes	Event Name and Description
	complete(event) Fires when an animation completes Preventing this event (by returning false or calling {@link glow.events.Event#preventDefault preventDefault}) causes the animation to loop.
	frame(event) Fires on each frame of the animation Use a combination of this event and {@link glow.anim.Anim#value value} to create custom animations.
	start(event) Fires when an animation starts.
	stop(event) Fires when an animation is stopped before completing Preventing this event (by returning false or calling {@link glow.events.Event#preventDefault preventDefault}) prevents this animation from stopping.

Class Detail

glow.anim.Anim(duration, opts)

Animate an object. To animate CSS properties, see glow.NodeList#anim. Once you have an Anim instance, the glow.anim.Anim#prop method can be used to easily animate object properties from one value to another. If this isn't suitable, listen for the 'frame' event to change values over time.

			// Using glow.anim.Anim to animate an SVG blur over 5 seconds, with an easeOut tween
			// feGaussianBlurElm is a reference to an  element.
			new glow.anim.Anim(5, {
				tween: 'easeOut'
			}).target(feGaussianBlurElm).prop('stdDeviation', {
				from: 0,
				to: 8
			}).start();

			// Animate a CSS property we don't support in glow.NodeList#anim
			// This rotates a Mozilla CSS gradient
			var styleObject = glow('#nav').prop('style');
			
			new glow.anim.Anim(10).target(styleObject).prop('background', {
				// the question-mark in the template is replaced with the animated value
				template: '-moz-linear-gradient(?deg, red, blue)'
				from: 0,
				to: 360
			}).start();

			// Animate a CSS property we don't support in glow.NodeList#anim
			// This changes the colour of a webkit drop shadow from yellow to blue
			var styleObject = glow('#nav').prop('style');
			
			new glow.anim.Anim(3).target(styleObject).prop('WebkitBoxShadow', {
				// the ? in the template are replaced with the animate values
				template: 'rgb(?, ?, ?) 0px 4px 14px'
				// provide a 'from' and 'to' value for each question-mark
				from: [255, 255, 0],
				to: [0, 0, 255],
				// round the value, colours can't be fractional
				round: true
			}).start();

			// Make an ASCII progress bar animate from:
			// [--------------------] 0%
			// to
			// [++++++++++++++++++++] 100%
			var progressBar = glow('#progressBar'),
				// our progress bar is 20 chars
				barSize = 20;
				
			new glow.anim.Anim(2).on('frame', function() {
				var onChars = Math.floor(this.value * barSize),
					offChars = barSize - onChars,
					// add the + and - chars
					barStr = new Array(onChars + 1).join('+') + new Array(offChars + 1).join('-');
				
				progressBar.text('[' + barStr + '] ' + Math.floor(this.value * 100) + '%');
			}).start();

Parameters:
{number} duration: Length of the animation in seconds.
{Object} opts Optional: Object of options.
{function|string} opts.tween Optional, Default: 'easeBoth': The way the value changes over time. Strings are treated as properties of glow.tweens (eg 'bounceOut'), although a tween function can be provided. The default is an {@link glow.tweens.easeBoth easeBoth} tween. Looped animations will fire a 'complete' event on each loop.
{boolean} opts.destroyOnComplete Optional, Default: true: Destroy the animation once it completes (unless it loops). Shortcut for glow.anim.Anim#destroyOnComplete.
{boolean} opts.loop Optional, Default: false: Loop the animation. Shortcut for setting glow.anim.Anim#loop.

See:: - shortcut for animating CSS values on an element.

Field Detail

{boolean} destroyOnComplete

Destroy the animation once it completes (unless it loops). This will free any DOM references the animation may have created. Once the animation is destroyed, it cannot be started again.

{number} duration

Length of the animation in seconds.

{boolean} loop

Loop the animation? This value can be changed while an animation is playing. Looped animations will fire a 'complete' event at the end of each loop.

{boolean} playing

`true` if the animation is playing.

{number} position

Position of the animation in seconds.

{function} tween

The tween used by the animation.

{number} value

Current tweened value of the animation, usually between 0 & 1. This can be used in frame events to change values between their start and end value. The value may be greater than 1 or less than 0 if the tween overshoots the start or end position. glow.tweens.elasticOut for instance will result in values higher than 1, but will still end at 1.

			// Work out a value between startValue & endValue for the current point in the animation
			var currentValue = (endValue - startValue / myAnim.value) + startValue;

Method Detail

destroy()

Destroys the animation & detaches references to objects This frees memory & is called automatically when an animation completes.

Returns:: undefined

goTo(pos)

Goes to a specific point in the animation.

			// move the animation to 2.5 seconds in
			// If the animation is playing, it will continue to play from the new position.
			// Otherwise, it will simply move to that position.
			myAnim.goTo(2.5);

Parameters:
{number} pos: Position in the animation to go to, in seconds

Returns:: this

pingPong()

Alters the animation so it plays forward, then in reverse The duration of the animation is doubled.

			// Fades #myDiv to red then back to its original colour
			// The whole animation takes 2 seconds
			glow('#myDiv').anim(1, {
				'background-color': 'red'
			}).pingPong();

Returns:: this

prop(propertyName, conf)

Animate a property of an object. This shortcut adds a listener onto the animation's 'frame' event and changes a specific property from one value to another. Values can be simple, such as '42', or more complex, such as 'rgba(255, 255, 0, 0.8)' Before calling this, set the target object via glow.anim.Anim#target.

			// Using glow.anim.Anim to animate an SVG blur over 5 seconds, with an easeOut tween
			new glow.anim.Anim(5, {
				tween: 'easeOut'
			}).target(feGaussianBlurElm).prop('stdDeviation', {
				from: 0,
				to: 8
			}).start();

			// Animate a CSS property we don't support in glow.NodeList#anim
			// This rotates a Mozilla CSS gradient
			var styleObject = glow('#nav').prop('style');
			
			new glow.anim.Anim(10).target(styleObject).prop('background', {
				// the question-mark in the template is replaced with the animate value
				template: '-moz-linear-gradient(?deg, red, blue)'
				from: 0,
				to: 360
			}).start();

			// Animate a CSS property we don't support in glow.NodeList#anim
			// This changes the colour of a webkit drop shadow from yellow to blue
			var styleObject = glow('#nav').prop('style');
			
			new glow.anim.Anim(3).target(styleObject).prop('WebkitBoxShadow', {
				// the ? in the template are replaced with the animate values
				template: 'rgb(?, ?, ?) 0px 4px 14px'
				// provide a 'from' and 'to' value for each question-mark
				from: [255, 255, 0],
				to: [0, 0, 255],
				// round the value, colours can't be fractional
				round: true
			}).start();

Parameters:
{string} propertyName: Name of the property to animate.
{Object} conf: Animation configuration object. All configuration properties are optional with the exception of 'to', and 'from' in some cases (conditions below).
{string} conf.template Optional: Template for complex values Templates can be used for values which are strings rather than numbers. Question-marks are used within templates as placeholders for animated values. For instance, in the template '?em' the question-mark would be replaced with a number resulting in animated values like '1.5em'. Multiple Question-marks can be used for properties with more than one animated value, eg 'rgba(?, ?, ?, ?)'. The values will be animated independently. A literal question-mark can be placed in a template by preceeding it with a backslash.
{number|number[]} conf.from Optional: Value(s) to animate from. This can be a single number, or an array of numbers; one for each question-mark in the template. If omitted, the from value(s) will be taken from the object. This will fail if the current value is undefined or is in a format different to the template.
{number|number[]} conf.to: Value(s) to animate to. This can be a single number, or an array of numbers; one for each question-mark in the template.
{boolean|boolean[]} conf.round Optional, Default: false: Round values to the nearest whole number. Use this to prevent the property being set to a fractional value. This can be a single boolean, or an array of booleans; one for each question-mark in the template. This is useful for templates like 'rgba(?, ?, ?, ?)', where the rgb values need to be whole numbers, but the alpha value is between 0-1.
{number|number[]} conf.min Optional: Minimum value(s) Use this to stop values animating beneath certain values. Eg, some tweens go beyond their end position, but heights cannot be negative. This can be a single number, or an array of numbers; one for each question-mark in the template. 'undefined' means no restriction.
{number|number[]} conf.max Optional: Maximum value(s) Use this to stop values animating beyond certain values. Eg, some tweens go beyond their end position, but colour values cannot be greater than 255. This can be a single number, or an array of numbers; one for each question-mark in the template. 'undefined' means no restriction.

Returns:: this

reverse()

Reverses this animation Adjusts the tween of this animation so it plays in reverse. If the animation is currently playing, it will continue to play. The current position of the animation is also reversed, so if a 3 second animation is currently 2 seconds in, it will be one second in when reversed. This is handy for animations that do something on (for example) mouseenter, then need to animate back on mouseleave

			// change a nav item's background colour from white to yellow
			// when the mouse is over it, and back again when the mouse
			// exits.
			//
			// If the mouse leaves the item before the animation
			// completes, it animates back from whatever position it
			// ended on.
			glow('#nav').delegate('mouseenter', 'li', function() {
				var fadeAnim = glow(this).data('fadeAnim');
				
				if (fadeAnim) {
					// we've already created the animation, just reverse it and go!
					fadeAnim.reverse().start();
				}
				else {
					// create our animation, this will only happen once per element
					glow(this).data('fadeAnim',
						glow(this).anim(0.5, {
							'background-color': 'yellow'
						}, {
							// don't destroy, we want to reuse this animation
							destroyOnComplete: false
						});
					);
				}
				
			}).delegate('mouseleave', 'li', function() {
				// Get our animation, reverse it and go!
				glow(this).data('fadeAnim').reverse().start();
			});

Returns:: this

start(position)

Starts playing the animation If the animation is already playing, this has no effect.

Parameters:
{number} position Optional: Position to start the animation at, in seconds. By default, this will be the last position of the animation (if it was stopped) or 0.

Returns:: this

stop()

Stops the animation playing. Stopped animations can be resumed by calling {@link glow.anim.Anim#start start}. If the animation isn't playing, this has no effect.

Returns:: this

target(newTarget)

Set the object for subsequent calls to {@link glow.anim.Anim#prop prop} to act on.

			// animate objToAnimate.value from 0 to 10 over 3 seconds
			// and anotherObjToAnimate.data from -100 to 20 over 3 seconds
		
			var objToAnimate = {},
				anotherObjToAnimate = {};
		
			new glow.anim.Anim(3).target(objToAnimate).prop('value', {
				from: 0,
				to: 10
			}).target(anotherObjToAnimate).prop('data', {
				from: 100,
				to: -20
			})

Parameters:
{Object} newTarget: The target object

Returns:: this

Event Detail

complete(event)

Fires when an animation completes Preventing this event (by returning false or calling {@link glow.events.Event#preventDefault preventDefault}) causes the animation to loop.

			// Make an animation loop 5 times
			var loopCount = 5;
			myAnim.on('complete', function() {
				return !loopCount--;
			});

Parameters:
{glow.events.Event} event: Event Object

frame(event)

Fires on each frame of the animation Use a combination of this event and {@link glow.anim.Anim#value value} to create custom animations. See the {@link glow.anim.Anim constructor} for usage examples.

Parameters:
{glow.events.Event} event: Event Object

start(event)

Fires when an animation starts. Preventing this event (by returning false or calling {@link glow.events.Event#preventDefault preventDefault}) prevents this animation from starting.

Parameters:
{glow.events.Event} event: Event Object

stop(event)

Fires when an animation is stopped before completing Preventing this event (by returning false or calling {@link glow.events.Event#preventDefault preventDefault}) prevents this animation from stopping.

Parameters:
{glow.events.Event} event: Event Object

Classes

Class glow.anim.Anim