back to Overview

.animate()

Animates the items of the list by modifying their properties, CSS styles and attributes.
Web module only.

Syntax Variants

list.animate(properties)
list.animate(properties, durationMs)
list.animate(properties, durationMs, linearity)
list.animate(properties, durationMs, interpolationFunc)

Parameters

properties
a property map describing the end values of the corresponding properties. The names can use the set() syntax ('@' prefix for attributes, '$' for styles, '$$fade' for fading, '$$slide' for slide effects, '$$scrollX' and '$$scrollY' for scroll coordinates). Values must be either numbers, numbers with units (e.g. "2 px") or colors ('rgb(r,g,b)', '#rrggbb' or '#rgb') or a function(oldValue, index, obj) to determine the new value. The function will be invoked for each list element to evaluate the new value:
oldValue
The old value of the property to be changed, as returned by get(). For the CSS style names, this is the computed style of the property
index
The list index of the object owning the property
obj
The list element owning the property.
(callback return value)
The destination value to be set.
durationMs (optional)
the duration of the animation in milliseconds. Default: 500ms.
linearity (optional)
defines whether the animation should be linear (1), very smooth (0) or something in between. Default: 0.
interpolationFunc (optional)
an interpolation function(startValue, endValue, t) which will be called every time an interpolated value is required:
startValue
The start value of the transition.
endValue
The end value of the transition.
t
A value between 0 and 1 that specifies the state of the transition.
(callback return value)
The value at the time t.
(return value)
a Promise object to monitor the animation's progress. It is fulfilled when the animation ended, and rejected if the animation had been stopped. The fulfillment handler will be called as function(list):
list
A reference to the animated list.
The rejection handler is called as function() without arguments. The returned promise also has property 'stop', which is a function. Invoke the function without arguments to interrupt a running animation. It will return the animations actual duration in ms.

Description

Animates the items of the list by modifying their properties, CSS styles and attributes. animate() can work with numbers, strings that contain exactly one number, and with colors in the CSS notations 'rgb(r,g,b)', '#rrggbb' or '#rgb'.

When you invoke the function, it will first read all old values from the object and extract their numbers and colors. These start values will be compared to the destination values that have been specified in the given properties. Then animate() will create a background task using $.loop() that updates the specified properties in frequent intervals so that they transition to their destination values.

The start values will be obtained using get(). It is recommended to set the start values using set() before you start the animation, even if this is not always required.

You can define the kind of transition using the linearity parameter. If you omit it or pass 0, animate's default algorithm will cause a smooth transition from the start value to the end value. If you pass 1, the transition will be linear, with a sudden start and end of the animation. Any value between 0 and 1 is also allowed and will give you a transition that is 'somewhat smooth'.

Instead of the linearity function you can provide your own interpolation function(startValue, endValue, t) which will be called every time an interpolated value is required. startValue and endValue define the start and end values. t is a value between 0 and 1 that specifies the current state of the transition. The function must return the startValue for 0 and the endValue for 1. For values between 0 and 1, the function should return a transitional value.

If the start value of a property is a string containing a number, animate() will always ignore all the surrounding text and use the destination value as a template for the value to write. This can cause problems if you mix units in CSS. For example, if the start value is '10%' and you specify an end value of '20px', animate will do an animation from '10px' to '20px'. It is not able to convert units.

animate() does not only support strings with units, but any string containing exactly one number. This allows you, among other things, to work with IE-specific CSS properties. For example, you can transition from a start value 'alpha(opacity = 0)' to 'alpha(opacity = 100)'.

When you animate colors, animate() is able to convert between the three notations rgb(r,g,b), #rrggbb or #rgb. You can use them interchangeably, but you can not use color names such as 'red'.

Instead of the end value, you can also specify a function(oldValue, index, obj) to calculate the actual end value.

To allow more complex animation, animate() returns a Promise that is fulfilled when the animation has finished. You can also stop a running animation by calling the promise's stop() function. If you only use the Web module, stop() is only available in the promise returned by animate(). If you have the full package, the stop function will be propagated and can be called at any point of a promise chain.

Example

Move an element: 

$('#myMovingDiv').set({$left: '0px', $top: '0px'})                // start values
                 .animate({$left: '50px', $top: '100px'}, 1000);  // animation

Example

Change the color of an element: 

$('#myBlushingDiv').set({$backgroundColor: '#000000'})
                   .animate({$backgroundColor: '#ff0000'}, 1000);

Example

Using a function to calulate the values for animation: 

$('#myMovingDiv').animate({$left: function(v) { return (parseFloat(v) + 100) + 'px'; }}, 1000);

Example

Fade-out effect: 

$('#myFadingDiv').animate({$$fade: 0}, 1000);

Example

Slide-in effect: 

$('#myInvisibleDiv').animate({$$show:1, $$slide: 1}, 1000);

Example

Stopping a simple animation. This requires only the Web module. 

var div = $('#myMovingDiv').set({$left: '0px', $top: '0px'});
var p = div.animate({$left: '800px', $top: '0px'}, 5000, 0);
$('#stopButton').on('click', p.stop);
});

Example

Chained animation using Promise callbacks. The element is first moved to the position 200/0, then to 200/200 and finally moves to 100/100. A stop button allows you to interrupt the animation.
Please note that while chaining animations requires only the Web module, stopping a chained animation requires the full distribution with both Web and Util module. Only the complete Promises implementation supports this. 

var div = $('#myMovingDiv').set({$left: '0px', $top: '0px'});
var p = div.animate({$left: '200px', $top: '0px'}, 600, 0)
   .then(function() {
          return div.animate({$left: '200px', $top: '200px'}, 800, 0);
   }).then(function() {
          return div.animate({$left: '100px', $top: '100px'}, 400);
   });

 $('#stopButton').on('click', p.stop); // stopping requires Web+Util modules!
});

See also..

  • toggle() can be used to define animations between two states.
  • $.loop() allows you to write more complex animations.

Comments

comments powered by Disqus

back to Overview

Functions