Deprecate QCoreApplication::flush()

... as it has outlived its original purpose:

Qt3 implementation on X11:
void QApplication::flush() { flushX(); }
void QApplication::flushX() { if (appDpy) XFlush( appDpy ); }

Qt4 implementation on X11:
Did nothing when QApplication::flush() was called (the flush()
overrides in {unix,glib} event dispatchers with empty bodies).

In Qt5 this function somehow has been repurposed (inconsistently)
to do what QCoreApplication::sendPostedEvents already does:

QAbstractEventDispatcher::flush() = 0;
 => QCocoaEventDispatcher::flush() {}
 => QEventDispatcherCoreFoundation::flush() {}
    => QIOSEventDispatcher (does not override ::flush())
 => QEventDispatcherGlib::flush() {}
    => QPAEventDispatcherGlib (does not override ::flush())
 => QEventDispatcherUNIX::flush() {}
    => QUnixEventDispatcherQPA (when QT_NO_GLIB=true)
       ::flush() { if (qApp) qApp->sendPostedEvents(); })
       ==> QAndroidEventDispatcher (does not override ::flush())
 => QEventDispatcherWin32::flush() {}
    => QOffscreenEventDispatcher::flush() {
         if (qApp) qApp->sendPostedEvents();
         QEventDispatcherWin32::flush();
       }
    => QWindowsGuiEventDispatcher (does not override ::flush())
       => QWindowsDirect2DEventDispatcher (does not override ::flush())
 => QEventDispatcherWinRT::flush() {}
    => QOffscreenEventDispatcher::flush() {
         if (qApp) qApp->sendPostedEvents();
         QEventDispatcherWinRT::flush();
       }
    => QWinRTEventDispatcher (qminimaleglintegration.cpp) (does not override ::flush())
    => QWinRTEventDispatcher (qwinrteventdispatcher.h) (does not override ::flush())

Whatever this function was doing on macOS in Qt3 and Qt4 also has been
dropped in Qt5. It appears that the other event dispatchers in Qt5 that
have overrides for flush() have simply copy-pasted this logic.

Clearly the documentation of QCoreApplication::flush() is outdated and
has nothing to do with the actual implementation in Qt5.

This function is rarely used in Qt5 sources. It should be safe to remove
the calls to QCoreApplication::flush() from Qt source code, as this
function has been doing nothing on most platforms anyways. Repurposing
it even broke handling of posted events (see QTBUG-48717).

[ChangeLog][QtCore][Event loop] QCoreApplication::flush() is now
deprecated. Use QCoreApplication::processEvents() and
QCoreApplication::sendPostedEvents() instead.

Task-number: QTBUG-33489
Task-number: QTBUG-48717
Change-Id: Icc7347ff203024b7153ea74be6bf527dd07ce821
Reviewed-by: Tor Arne Vestbø <tor.arne.vestbo@qt.io>
Reviewed-by: David Faure <david.faure@kdab.com>
Reviewed-by: Gunnar Sletta <gunnar@crimson.no>

1 files changed, 9 insertions, 10 deletions

diff --git a/src/corelib/kernel/qcoreapplication.cpp b/src/corelib/kernel/qcoreapplication.cpp
index e4b1562b8b..4a4ad3ddf8 100644
--- a/src/corelib/kernel/qcoreapplication.cpp
+++ b/src/corelib/kernel/qcoreapplication.cpp
@@ -634,9 +634,9 @@ void QCoreApplicationPrivate::initLocale()
 
     Several static convenience functions are also provided. The
     QCoreApplication object is available from instance(). Events can
-    be sent or posted using sendEvent(), postEvent(), and
-    sendPostedEvents(). Pending events can be removed with
-    removePostedEvents() or flushed with flush().
+    be sent with sendEvent() or posted to an event queue with postEvent().
+    Pending events can be removed with removePostedEvents() or dispatched
+    with sendPostedEvents().
 
     The class provides a quit() slot and an aboutToQuit() signal.
 
@@ -705,15 +705,14 @@ QCoreApplication::QCoreApplication(QCoreApplicationPrivate &p)
 
 #ifndef QT_NO_QOBJECT
 /*!
-    Flushes the platform-specific event queues.
+    \deprecated
+    This function is equivalent to calling \c {QCoreApplication::eventDispatcher()->flush()},
+    which also is deprecated, see QAbstractEventDispatcher::flush(). Use sendPostedEvents()
+    and processEvents() for more fine-grained control of the event loop instead.
 
-    If you are doing graphical changes inside a loop that does not
-    return to the event loop on asynchronous window systems like X11
-    or double buffered window systems like Quartz (\macos and iOS), and you want to
-    visualize these changes immediately (e.g. Splash Screens), call
-    this function.
+    Historically this functions was used to flush the platform-specific native event queues.
 
-    \sa sendPostedEvents()
+    \sa sendPostedEvents(), processEvents(), QAbstractEventDispatcher::flush()
 */
 void QCoreApplication::flush()
 {