Add QPA notes to QCursor pos() and setPos()

Change-Id: I7173816e0d792d6d26497b4fd59a57a50e512afd
Reviewed-by: Samuel Rødal <samuel.rodal@nokia.com>

2 files changed, 19 insertions, 1 deletions

diff --git a/src/gui/kernel/qcursor.cpp b/src/gui/kernel/qcursor.cpp
index 95b2b4a28e..476d3a449b 100644
--- a/src/gui/kernel/qcursor.cpp
+++ b/src/gui/kernel/qcursor.cpp
@@ -205,6 +205,13 @@ QT_BEGIN_NAMESPACE
     You can call QWidget::mapFromGlobal() to translate it to widget
     coordinates.
 
+    \note The position is queried from the windowing system. If mouse events are generated
+    via other means (e.g., via QWindowSystemInterface in a unit test), those fake mouse
+    moves will not be reflected in the returned value.
+
+    \note On platforms where there is no windowing system or cursors are not available, the returned
+    position is based on the mouse move events generated via QWindowSystemInterface.
+
     \sa setPos(), QWidget::mapFromGlobal(), QWidget::mapToGlobal(), QGuiApplication::primaryScreen()
 */
 
@@ -218,6 +225,16 @@ QT_BEGIN_NAMESPACE
     You can call QWidget::mapToGlobal() to translate widget
     coordinates to global screen coordinates.
 
+    \note Calling this function results in changing the cursor position through the windowing
+    system. The windowing system will typically respond by sending mouse events to the application's
+    window. This means that the usage of this function should be avoided in unit tests and
+    everywhere where fake mouse events are being injected via QWindowSystemInterface because the
+    windowing system's mouse state (with regards to buttons for example) may not match the state in
+    the application-generated events.
+
+    \note On platforms where there is no windowing system or cursors are not available, this
+    function may do nothing.
+
     \sa pos(), QWidget::mapFromGlobal(), QWidget::mapToGlobal()
 */
 
diff --git a/src/testlib/qtestmouse.h b/src/testlib/qtestmouse.h
index 441cfa1f65..47a74d7389 100644
--- a/src/testlib/qtestmouse.h
+++ b/src/testlib/qtestmouse.h
@@ -127,7 +127,8 @@ namespace QTest
                 break;
             case MouseMove:
                 QWindowSystemInterface::handleMouseEvent(window,pos,window->mapToGlobal(pos),lastButton,stateKey);
-                //QCursor::setPos(window->mapToGlobal(pos));
+                // No QCursor::setPos() call here. That could potentially result in mouse events sent by the windowing system
+                // which is highly undesired here. Tests must avoid relying on QCursor.
                 break;
             default:
                 QTEST_ASSERT(false);