# Mojo.Animation

## Namespace Detail

Holds the infrastructure for coordinating timers for multiple animations, and animating DOM element styles & numeric values over time. Since the overhead associated with timers can be significant, an animation queue allows multiple periodic tasks to be run at the standard frequency of 40 fps while using only a single timer.

The other public methods are for animating style properties of DOM elements (visually animating elements on screen), or generally animating numeric values over time.

## Summary

- Mojo.Animation.easeIn
- Mojo.Animation.easeInOut
- Mojo.Animation.easeOut

## Method Summary

- Mojo.Animation.animateClip(element, side, animationType, details)
- Mojo.Animation.animateStyle(element, attr, animationType, details)
- Mojo.Animation.animateValue(q, animationType, callback, details)
- Mojo.Animation.queueForElement(element)

## Detail

### Mojo.Animation.easeIn

An animation curve that starts slowly, and speeds up.

### Mojo.Animation.easeInOut

An animation curve that is quick in the middle, and slow at both ends.

### Mojo.Animation.easeOut

An animation curve that starts quickly, and slows down.

## Method Detail

### Mojo.Animation.animateClip(element, side, animationType, details)

This is used to animate the 'clip' style property of DOM elements. Only one side may be animated at a time. Any existing clip animation on the indicated node is canceled when the new one is applied, and this generally behaves like animateStyle().

In addition, animateStyle() is used to provide underlying functionality, so its details are generally supported as well.

#### Example Use

This is used to animate the clipping rectangle for ProgressPill widgets.

>     clipStyleAnimator = Mojo.Animation.animateClip(
>       this.progressDiv,
>       'left',
>       this.oldWidth,
>       width,
>       0.2,
>       {
>           clip: {
>               top: 0,
>               left: this.oldWidth,
>               bottom: 12,
>               right: 0
>           },
>           curve: 'ease-in-out'
>       }
>     );

#### 'details' properties

clip | A required hash of numbers indicating current values for clip rect. The indicated side is modified as the animation progresses.

#### Parameters

- {Object} element DOM element whose style should be animated.
- {String} side Which side to animate. top, left, bottom, or right.
- {String} animationType Can be linear/bezier/zeno. This determines the speed of the animation at various times.
- {Object} details Various animation details. May NOT be undefined, since 'clip' is required (see above description).

### Mojo.Animation.animateStyle(element, attr, animationType, details)

This is used to animate style properties of DOM elements. The implementation will animate a given attribute to the given value over the given duration. Any existing animation on the indicated node for the indicated style attribute is canceled when the new one is applied. The animator will override external changes made to the animated attribute while the animation is in progress. Currently, only integer valued attributes are supported, so colors and opacity cannot be animated (except using the styleSetter detail property).

One difference between this animator and CSS transitions is that both a 'fromValue' and a 'toValue' must be specified. This allows us to keep the animation speed "correct" when an attribute is being animated back and forth between two values, and we need to run the 'back' animation while the 'forth' animation is only partially complete.

#### Example Use

This code is used to animate the spacers to 0 height when doing drag'n'drop reordering in lists. Note the use of an onComplete function to remove the 0-height spacer from the DOM.

>     Mojo.Animation.animateStyle(
>       this.curDragSpacer,
>       'height',
>       this.dragHeight,
>       0,
>       .2,
>       {onComplete:function(el){Element.remove(el);}}
>     );

In addition, animateValue() is used to provide underlying functionality, so its details are generally supported as well.

#### 'details' properties

currentValue | Current value of the style property being animated. Default is to call parseInt() on the style property.
styleSetter | Function to call with the value to actually apply the style change. Allows for setting more complex style properties like 'clip'.
from | Starting value for the number we are animating (Passed to ValueAnimator)
to | Target value for the number we are animating (Passed to ValueAnimator)
duration | How long the animation should take, in seconds

#### Parameters:

- {Object} element the DOM element whose style should be animated.
- {Object} attr The name of the style attribute to be animated, using HTML DOM naming conventions.
- {String} animationType Can be linear/bezier/zeno. This determines the speed of the animation at various times.
- {Object} details Various animation details as described above. Note that most ValueAnimator details are supported as well.

### Mojo.Animation.animateValue(q, animationType, callback, details)

Animates a value between the two given numbers, over the given duration, calling the given callback with the "current value" at each step of the animation. Returns an animation object that can be used to end the animation early.

#### 'details' properties

onComplete | Function to call when animation is complete. Passes back a boolean 'cancelled' value.
reverse | Boolean. If true, the animation will be "run in reverse".
curve | What sort of curve to use for the animation. Defaults to linear if unspecified. May be the name of one of the standard curves, or an array of coordinates for the control points of a cubic bezier curve. See the curve name constants in Mojo.Animation.
from | Starting value for the number we are animating
to | Target value for the number we are animating
duration | How long the animation should take, in seconds
currentValue | If specified, the animation will be "picked up" at this value between the from and to values. This allows partially complete animations to be canceled and properly animated back to their starting conditions.

#### Methods

cancel() | Same as complete(), but the callback is never called with the target value.
complete() | calls the value callback one last time with the target value, calls onComplete function if specified, and removes the animator from the queue. Called automatically at completion of animation.

#### Parameters:

- {Object} q The animation queue to use in order to run the animation.
- {String} animationType Can be linear/bezier/zeno. This determines the speed of the animation at various times.
- {Function} callback This function is called at each step of the animation, as the value changes. It takes one argument, the current value.
- {Object} details Optional A hash containing additional information.

### Mojo.Animation.queueForElement(element)

Given a DOM element, returns a reference to the appropriate animation queue to use.

#### Parameter

element