The effects core now uses a new factory jQuery.Animation( element, props, opts )
which is responsible for creating an animation object.
It returns a promise, with these additional properties:
elem
: Object The element being animatiedprops
: Object The final value of each property animatingopts
: Object The animation optionsoriginalProps
: Object The original properties before being filteredoriginalOpts
: Object The original options before being filteredstartTime
: Number The numeric value ofnew Date()
when the animation beganduration
: Number The duration specified in msstop( gotoEnd )
: Function Stops the animation early, optionally going to the end.createTween( propName, finalValue, easing )
: Function Explained in the Tween section.tweens
: Array The animations tweens (also explained in the Tween section).
The promise will be resolved when the animation reaches its end, and rejected when terminated early. The context of callbacks attached to the promise will be the element, and the arguments will be the Animation
object and a boolean jumpedToEnd
which when true means the animation was stopped with gotoEnd
, when undefined
the animation completed naturally.
Note: Remember that jQuery.fn.stop( clearQueue, gotoEnd )
takes the clearQueue
parameter first, but the Animation.stop( gotoEnd )
doesn't have that option.
-
.stop( gotoEnd = true )
calls:done( anim, jumpedToEnd = true )
always( anim, jumpedToEnd = true )
-
.stop( gotoEnd = false )
calls:fail( anim, jumpedToEnd = false )
always( anim, jumpedToEnd = false )
-
natural completion calls:
done( anim, jumpedToEnd = undefined )
always( anim, jumpedToEnd = undefined )
The promise will also be notified via the progress
callback in each frame (for each element) after setting values.
We added new callbacks progress
, always
, done
, and fail
to the jQuery.fn.animate
(and friends) options
object which will attach callbacks to the promise:
progress: function( anim, progress, remainingMs )
always: function( anim, jumpedToEnd )
done: function( anim, jumpedToEnd )
fail: function( anim, jumpedToEnd )
Also, we added start: function( anim )
which will be called after the prefilters have been processed and tweens have been created.
All callbacks will be called with this === element
During the initial setup, jQuery.Animation
will call any callbacks that have been registered through jQuery.Animation.prefilter( function( element, props, opts ) )
.
The prefilter will have this
set to an animation object, and you can modify any of the props
or opts
however you need. The prefilter may return its own promise which also implements stop()
, in which case, processing of prefilters stops. If the prefilter is not trying to override the animation entirely, it should return undefined
or some other falsy value.
There is a new factory jQuery.Tween( elem, options, prop, end, easing, unit )
which replaces the jQuery.fx
objects. The format of the Tween
object is very similar to the old fx
object in order to maintain backwards compatability with jQuery.fx.step
functions.
elem
: The element being animatedprop
: The property being animatedeasing
: The easing usedoptions
: A reference to the animation optionsstart
: The starting value of the tweennow
: The current value of the tweenend
: The ending value of the tweenunit
: The CSS unit for the tweencur()
: Reads the current value for property from the elementrun( progress )
:progress
is a number from 0 to 1. Updates the value for the property on the animated elemd.
A "Tweener" is a function responsible for creating a tween object, and you might want to override these if you want to implement complex values ( like a clip/transform array matrix ) in a single property.
You can override the default process for creating a tween in order to provide your own tween object by using jQuery.Animation.tweener( props, callback( prop, value ) )
. props
is a space separated list of properties to be passed to your tweener, or "*"
if it should be called for all properties. The callback will be called with this
being an Animation
object. The tweener function will generally start with var tween = this.createTween( prop, value );
, but doesn't nessecarily need to use the jQuery.Tween()
factory.
If you want to create your own tween, you can push a new object that has a run( progress )
function that sets the value you want onto the .tweens
array on the animation. The tween is considered to have been created, and it will stop calling other tweeners if your tweener returns any truthy value.
jQuery.Tween.propHooks[ prop ]
is a hook point that replaces jQuery.fx.step[ prop ]
(which is being deprecated.) These hooks are used by the tween to get and set values on elements.
jQuery.Tween.propHooks[ property ] = {
get: function( tween ) {
// get tween.prop from tween.elem and return it
},
set: function( tween ) {
// set tween.prop on tween.elem to tween.now + tween.unit
}
}
The default jQuery timers use a single setInterval
to call each of the tick functions in the jQuery.timers
array.
jQuery.fx.tick()
: Calls .run()
on each object in the jQuery.timers
array, removing it from the array if .run()
returns a falsy value. Calls jQuery.fx.stop()
whenever there are no timers remaining.
jQuery.fx.stop()
: overridable Clears up the setInterval
jQuery.fx.timer( tickFunction )
: overridable Creates a setInterval
if one doesn't already exist, and pushes tickFunction
to the jQuery.timers
array. tickFunction
should also have anim
, elem
, and queue
properties that reference the animation object, animated element, and queue option to facilitate jQuery.fn.stop()
By overriding fx.timer
and fx.stop
you should be able to implement any animation tick behaviour you desire. (like using requestAnimationFrame
instead of setTimeout
.)
There is an example of overriding the timer loop in jquery.requestAnimationFrame
jQuery.fx.step
functions are being replaced byjQuery.Tween.propHooks
and may eventually be removed, but are still supported via the default tween propHook.
Looks really good. Now I just have to figure out how to get this into the new docs site. :)