# Fix Flickable wheel velocity calculation (QTBUG-56075)

Angular velocity is defined as angle rotated divided by time elapsed. But the historical problem with Flickable is that the calculation ignored time, as if there was a maximum frequency of events and we only needed to know the rotation angle per fixed unit of time. With "clicky" mouse wheels perhaps it was a reasonable approximation. With touchpads that provide pixel deltas, we've been doing the velocity calculation the right way since a6ed830f Now we divide by dt also in the wheel rotation case.

That gives instantaneous velocity. Next question: how to do smoothing? AxisData::velocityBuffer is basically a Kalman filter, but until now it was used only when dragging ends and we animate the deceleration from the velocity at that time. It seems to work well for smoothing the velocity that comes from wheel events, too. So now we use that instead of smoothVelocity, and it stays in control better.

Next question: when a series of wheel events occurs, we have valid dt for the dy / dt velocity calculation (or dx / dt horizontally), but what about the initial flick? What if first thing the user does is rotate a physical mouse wheel by one "click", how far should Flickable move before it comes to rest? QStyleHints::wheelScrollLines() tells us how far to move for one wheel event... in "lines", whatever that is. Flickable doesn't know about its contents. But it "feels" reasonable if we define a "line" as 24 pixels. At least the setting will do something now: applications can adjust it, and some system control panels can adjust it. A subclass of QQuickFlickable (such as TableView) could even change QQFlickablePrivate::initialWheelFlickDistance to be the actual number of pixels per "line", to scroll exactly by rows. (But when the events occur faster, it moves further and faster, like it always did.)

OK so we know how far we want to move when the Flickable is at rest and receives a QWheelEvent with angleDelta of 120. I.e. when isMoving() is false. So I tried an experiment: set dt to 0.25. How far did it move? 77 pixels. Why? We're making it move via QQuickFlickablePrivate::flick() which does some math and drives the timeline. The key formula is qreal dist = v2 / (accel * 2.0) which agrees with the testing: if the wheel turns by 120 units, (120 / 0.25)^2 / (1500 * 2) =~ 77 So it's possible to do the algebra to reverse-engineer what dt should be so that we will move the right distance with a single wheel event, despite the complexity of the animation itself. That's what is now done. When the user rotates the wheel very slowly, it moves by discrete amounts but with smooth animation. A little faster, and it speeds up, somewhat like it did before, but with more control. If it has sped up to a high speed and then the user rotates the wheel backwards, it reverses instantly: we clear the Kalman filter and insert instantaneous velocity (so it will go from there at the next event).

On a touchpad, it also feels quite in-control because the velocity is calculated properly as distance-delta / time-delta. Smoothing it out doesn't hurt, and animating after release doesn't hurt. It longer goes "zing" out of control when the wheel events come in too frequently from a touchpad or a free-spinning wheel.

None of this affects trackpads on macOS, because then the wheel events have phases and pixel deltas, and we don't use this animation. We still should try to get that working on as many OSes as possible, eventually.

Clarify the meaning of the flickDeceleration property.

[ChangeLog][QtQuick][Flickable] Flickable no longer tries to detect whether you're using a "clicky" wheel or a touchpad, but rather does the velocity calculation more correctly with elapsed time (dθ / dt). A single rotation of a "clicky" wheel also moves a fixed distance, which is now adjustable via QStyleHints::wheelScrollLines(). Animation is restored, but should now stay in control on touchpads; and it will once again transition the "moving" properties correctly when scrolling ends.

Fixes: QTBUG-56075 Pick-to: 6.2 Change-Id: I5166ca31c86335641cf407a922a3a970fced653d Reviewed-by: Richard Moe Gustavsen richard.gustavsen@qt.io