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, 3 insertions, 2 deletions

diff --git a/src/corelib/kernel/qabstracteventdispatcher.cpp b/src/corelib/kernel/qabstracteventdispatcher.cpp
index 907b3ccf1f..e94faa4587 100644
--- a/src/corelib/kernel/qabstracteventdispatcher.cpp
+++ b/src/corelib/kernel/qabstracteventdispatcher.cpp
@@ -320,9 +320,10 @@ int QAbstractEventDispatcher::registerTimer(int interval, Qt::TimerType timerTyp
 */
 
 /*! \fn void QAbstractEventDispatcher::flush()
+    \deprecated
 
-    Flushes the event queue. This normally returns almost
-    immediately. Does nothing on platforms other than X11.
+    Depending from the event dispatcher implementation does nothing or
+    calls QApplication::sendPostedEvents().
 */
 
 // ### DOC: Are these called when the _application_ starts/stops or just