doc: explain QWheelEvent::angleDelta() more thoroughly

It has been a QPoint for a long time now, to support both the usual
vertical mouse wheel and also the wheel tilt for horizontal scrolling,
or the actual horizontal wheel if the mouse has one, or the simulation
of a horizontal wheel via touchpad gestures; but the docs continued to
read as if it was just one value.

Task-number: QTBUG-71575
Change-Id: I3efa686ace4f09c7f237f72bf0500fbfbd3213cb
Reviewed-by: Richard Moe Gustavsen <richard.gustavsen@qt.io>

1 files changed, 19 insertions, 9 deletions

diff --git a/src/gui/kernel/qevent.cpp b/src/gui/kernel/qevent.cpp
index f555f4dc05..0706ae3e90 100644
--- a/src/gui/kernel/qevent.cpp
+++ b/src/gui/kernel/qevent.cpp
@@ -667,9 +667,9 @@ QHoverEvent::~QHoverEvent()
     if that widget does not handle the event they are sent to the
     focus widget. Wheel events are generated for both mouse wheels
     and trackpad scroll gestures. There are two ways to read the
-    wheel event delta: angleDelta() returns the delta in wheel
-    degrees. This value is always provided. pixelDelta() returns
-    the delta in screen pixels and is available on platforms that
+    wheel event delta: angleDelta() returns the deltas in wheel
+    degrees. These values are always provided. pixelDelta() returns
+    the deltas in screen pixels, and is available on platforms that
     have high-resolution trackpads, such as \macos. If that is the
     case, source() will return Qt::MouseEventSynthesizedBySystem.
 
@@ -852,7 +852,7 @@ QWheelEvent::QWheelEvent(const QPointF &pos, const QPointF& globalPos,
     by \a globalPos.
 
     \a pixelDelta contains the scrolling distance in pixels on screen, while
-    \a angleDelta contains the wheel rotation distance. \a pixelDelta is
+    \a angleDelta contains the wheel rotation angle. \a pixelDelta is
     optional and can be null.
 
     The mouse and keyboard states at the time of the event are specified by
@@ -914,10 +914,16 @@ QWheelEvent::~QWheelEvent()
 /*!
     \fn QPoint QWheelEvent::angleDelta() const
 
-    Returns the distance that the wheel is rotated, in eighths of a
-    degree. A positive value indicates that the wheel was rotated
-    forwards away from the user; a negative value indicates that the
-    wheel was rotated backwards toward the user.
+    Returns the relative amount that the wheel was rotated, in eighths of a
+    degree. A positive value indicates that the wheel was rotated forwards away
+    from the user; a negative value indicates that the wheel was rotated
+    backwards toward the user. \c angleDelta().y() provides the angle through
+    which the common vertical mouse wheel was rotated since the previous event.
+    \c angleDelta().x() provides the angle through which the horizontal mouse
+    wheel was rotated, if the mouse has a horizontal wheel; otherwise it stays
+    at zero. Some mice allow the user to tilt the wheel to perform horizontal
+    scrolling, and some touchpads support a horizontal scrolling gesture; that
+    will also appear in \c angleDelta().x().
 
     Most mouse types work in steps of 15 degrees, in which case the
     delta value is a multiple of 120; i.e., 120 units * 1/8 = 15 degrees.
@@ -926,7 +932,9 @@ QWheelEvent::~QWheelEvent()
     that are less than 120 units (less than 15 degrees). To support this
     possibility, you can either cumulatively add the delta values from events
     until the value of 120 is reached, then scroll the widget, or you can
-    partially scroll the widget in response to each wheel event.
+    partially scroll the widget in response to each wheel event.  But to
+    provide a more native feel, you should prefer \l pixelDelta() on platforms
+    where it's available.
 
     Example:
 
@@ -937,6 +945,8 @@ QWheelEvent::~QWheelEvent()
     \li scrolling is about to begin, but the distance did not yet change (Qt::ScrollBegin),
     \li or scrolling has ended and the distance did not change anymore (Qt::ScrollEnd).
     \endlist
+
+    \see pixelDelta()
 */
 
 /*!