doc: Add details about what to use instead of QMouseEvent::source()

Pick-to: 6.2
Fixes: QTBUG-98875
Change-Id: I2678edccf68d754d191b9eb6cdfe09bba327e85a
Reviewed-by: Volker Hilsheimer <volker.hilsheimer@qt.io>

1 files changed, 10 insertions, 0 deletions

diff --git a/src/gui/kernel/qevent.cpp b/src/gui/kernel/qevent.cpp
index 3c33731279..6617057b42 100644
--- a/src/gui/kernel/qevent.cpp
+++ b/src/gui/kernel/qevent.cpp
@@ -803,6 +803,16 @@ QMouseEvent::~QMouseEvent()
 
     \sa Qt::MouseEventSource
     \sa QGraphicsSceneMouseEvent::source()
+
+    \note In Qt 5-based code, source() was often used to attempt to distinguish
+    mouse events from an actual mouse vs. those that were synthesized because
+    some legacy QQuickItem or QWidget subclass did not react to a QTouchEvent.
+    However, you could not tell whether it was synthesized from a QTouchEvent
+    or a QTabletEvent, and other information was lost. pointingDevice()
+    tells you the specific device that it came from, so you might check
+    \c {pointingDevice()->type()} or \c {pointingDevice()->capabilities()} to
+    decide how to react to this event. But it's even better to react to the
+    original event rather than handling only mouse events.
 */
 #if QT_DEPRECATED_SINCE(6, 0)
 Qt::MouseEventSource QMouseEvent::source() const