Feature: Progress Monitoring

[pags]

It'd be great to have support for an animation progress callback (like jQuery animate) ... or would this have a severe negative impact on performance?

[julianshapiro]

Hey Justin!

This is a really good question.

Providing support for this feature would not inherently have a negative performance impact.

However, it would undoubtedly lead to severe performance drawbacks being triggered by users' own callback functions. If, for example, they were to use the wrong jQuery call inside their callback -- one that queries the DOM -- it would introduce layout thrashing into the requestAnimationFrame tick.

So while I do not discount the utility of progress monitoring, I would be hesitant to provide support for it.

[pags]

Thanks for the response. Your concern is valid, but there's only so much a library can do to protect developers from themselves anyway, right?

In my case the lack of this callback is stopping me from using velocity as a drop in in-lieu of 'animate' (although I can't remember if you've explicitly marketed velocity as a direct drop-in).

[julianshapiro]

Justin,

May I ask for the use case you're dealing with in which you must monitor progress? I don't doubt there are good ones -- but the more I hear of them, the more I'm likely to integrate this soon.

[pags]

@julianshapiro I have a circle that gradually fills with a color, as it's filling I would like a visual counter to increment.

[julianshapiro]

Hmm. I can't think of a simple way to do that outside of Velocity. OK. I agree this is seriously worth considering. Thank you sincerely.

[mikaelkaron]

In relation to this and #32 I'd suggest looking at the progress callback (in Promises). From what I can see from the above it would probably be a nice integration point.

[mattegan]

@julianshapiro I'm creating an interactive card flip that needs to have the animation taken over when the user lets go (during the drag the y-rotation is set using the position of the mouse/finger). Anyway, I'm animating these two divs that are on top of one another and when they cross over the 50% mark they need to have their z-indices swapped.

I suppose I could do this with some clever z-index manipulating (as in, animate the z-index property such that when the rotation is at the 50% mark they swap over), so I might take that route for now, but this would make my life so much easier.

Also, just to note, Transit.js doesn't support this either so, one more leg up if Velocity were to implement this.

[julianshapiro]

Thanks a bunch for the example, @mattegan. Now that the Velocity UI pack is done and released (took me a very long time to do it properly), I'm getting back to the remaining feature requests and processing whichever don't lead to bloat. Progress monitoring is at the top of my list and will be implemented this week.

[mattegan]

@julianshapiro No problem! Thanks for the sweet library.

[julianshapiro]

I'm trying to come up with the best implementation for this:

1. Should the user-defined callback be triggered per animating element or per call (which can consist of one element or many elements).

2. I'm not sure how much pre-calculated information should be passed into the callback. Here's what I'm thinking so far:

• element(s) targeted by call
• percent complete
• ms remaining
• start time

3. Finally, should the callback be fired every time the animation tween ticks (roughly every 16ms) or should it only be fired upon single-digit percent-complete increments? Obviously it makes more sense to do the former, but I'm not sure how else to allow people to capture the point at which the animation hits 50% without having to create their own flags for percentComplete >= 0.50, but I guess that shouldn't be my concern.

The goal of the API, as with the Sequences API (http://VelocityJS.org/#sequences), is to not force the user to have to calculate too much progress data on their own in their callbacks (Velocity should do a good chunk of it).

[mattegan]

1. I think, if possible, it should be done in both ways, just as jQuery's animate(), to provide for more interoperability between animate() and velocity(). Naming the properties the same would be sweet too. (animate() has Step: 'A function to be called for each animated property of each animated element.' and Progress: 'A function to be called after each step of the animation, only once per animated element regardless of the number of animated properties.')

2. I would say again, provide the same numbers to the callback that jQuery does. This gets tricky I think because jQuery is passing the callback some internal jQuery objects that I'm guessing Velocity doesn't utilize. The Step callback is passed a Tween object and the Progress callback is passed some sort of animation promise (not sure what it's for). I think it might be convenient to ignore the internals that jQuery is exposing in these callbacks and simply provide the same numbers that jQuery is providing. The Step callback accepts a 'now' parameter, which is the current value of the property being animated (a tween of a property from 0px to 500px would fire the callback with values between 0 and 500). The progress callback accepts a 'progress' and a 'remainingMs' argument. The progress argument is a percentage that the animation is complete.

3. Yeah, totally, every time the tween ticks.

Hope this helps!

[julianshapiro]

Thanks for this, Matt. Great write-up. I'm going to focus on the progress feature for now. Expect it to be implemented very shortly.

I agree; I'll copy jQuery for the base values then extend from there.

[julianshapiro]

This has been implemented. See VelocityJS.org/#progress in about 1 hour.

[mattegan]

Hey Julian, just wanted to say thanks!

[julianshapiro]

Thank YOU for taking the time to help out. Super appreciated, Matt. Hit me up in the future if you have other recommendations.