iOS: Document why we're using a runloop mode tracker in our event dispatcher

Change-Id: I71093ca05988c3e1ad6d51be7363952dd3f0518e
Reviewed-by: Richard Moe Gustavsen <richard.gustavsen@qt.io>

1 files changed, 18 insertions, 0 deletions

diff --git a/src/corelib/kernel/qeventdispatcher_cf.mm b/src/corelib/kernel/qeventdispatcher_cf.mm
index d670e297c0..a6c5ccd7a8 100644
--- a/src/corelib/kernel/qeventdispatcher_cf.mm
+++ b/src/corelib/kernel/qeventdispatcher_cf.mm
@@ -58,6 +58,24 @@
 
 QT_USE_NAMESPACE
 
+/*!
+    During scroll view panning, and possibly other gestures, UIKit will
+    request a switch to UITrackingRunLoopMode via GSEventPushRunLoopMode,
+    which records the new runloop mode and stops the current runloop.
+
+    Unfortunately the runloop mode is just stored on an internal stack, used
+    when UIKit itself is running the runloop, and is not available through e.g.
+    CFRunLoopCopyCurrentMode, which only knows about the current running
+    runloop mode, not the requested future runloop mode.
+
+    To ensure that we pick up this new runloop mode and use it when calling
+    CFRunLoopRunInMode from processEvents, we listen for the notification
+    emitted by [UIApplication pushRunLoopMode:requester:].
+
+    Without this workaround we end up always running in the default runloop
+    mode, resulting in missing momentum-phases in UIScrollViews such as the
+    emoji keyboard.
+*/
 @interface QT_MANGLE_NAMESPACE(RunLoopModeTracker) : NSObject
 @end