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>

11 files changed, 33 insertions, 45 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
diff --git a/src/corelib/kernel/qabstracteventdispatcher.h b/src/corelib/kernel/qabstracteventdispatcher.h
index 68d9bf180f..a256b03523 100644
--- a/src/corelib/kernel/qabstracteventdispatcher.h
+++ b/src/corelib/kernel/qabstracteventdispatcher.h
@@ -102,7 +102,9 @@ public:
 
     virtual void wakeUp() = 0;
     virtual void interrupt() = 0;
-    virtual void flush() = 0;
+#if QT_DEPRECATED_SINCE(5, 9)
+    QT_DEPRECATED virtual void flush() = 0;
+#endif
 
     virtual void startingUp();
     virtual void closingDown();
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()
 {
diff --git a/src/corelib/kernel/qcoreapplication.h b/src/corelib/kernel/qcoreapplication.h
index 5e10136dc5..0fee7b3de8 100644
--- a/src/corelib/kernel/qcoreapplication.h
+++ b/src/corelib/kernel/qcoreapplication.h
@@ -165,7 +165,9 @@ public:
 #endif
 
 #ifndef QT_NO_QOBJECT
-    static void flush();
+#  if QT_DEPRECATED_SINCE(5, 9)
+    QT_DEPRECATED static void flush();
+#  endif
 
     void installNativeEventFilter(QAbstractNativeEventFilter *filterObj);
     void removeNativeEventFilter(QAbstractNativeEventFilter *filterObj);
diff --git a/src/widgets/widgets/qabstractbutton.cpp b/src/widgets/widgets/qabstractbutton.cpp
index c0bd8bce5a..77fb203b82 100644
--- a/src/widgets/widgets/qabstractbutton.cpp
+++ b/src/widgets/widgets/qabstractbutton.cpp
@@ -396,8 +396,7 @@ void QAbstractButtonPrivate::click()
     }
     blockRefresh = false;
     refresh();
-    q->repaint(); //flush paint event before invoking potentially expensive operation
-    QApplication::flush();
+    q->repaint();
     if (guard)
         emitReleased();
     if (guard)
@@ -834,8 +833,7 @@ void QAbstractButton::animateClick(int msec)
     if (d->checkable && focusPolicy() & Qt::ClickFocus)
         setFocus();
     setDown(true);
-    repaint(); //flush paint event before invoking potentially expensive operation
-    QApplication::flush();
+    repaint();
     if (!d->animateTimer.isActive())
         d->emitPressed();
     d->animateTimer.start(msec, this);
@@ -977,8 +975,7 @@ void QAbstractButton::mousePressEvent(QMouseEvent *e)
     if (hitButton(e->pos())) {
         setDown(true);
         d->pressed = true;
-        repaint(); //flush paint event before invoking potentially expensive operation
-        QApplication::flush();
+        repaint();
         d->emitPressed();
         e->accept();
     } else {
@@ -1025,8 +1022,7 @@ void QAbstractButton::mouseMoveEvent(QMouseEvent *e)
 
     if (hitButton(e->pos()) != d->down) {
         setDown(!d->down);
-        repaint(); //flush paint event before invoking potentially expensive operation
-        QApplication::flush();
+        repaint();
         if (d->down)
             d->emitPressed();
         else
@@ -1051,8 +1047,7 @@ void QAbstractButton::keyPressEvent(QKeyEvent *e)
     case Qt::Key_Space:
         if (!e->isAutoRepeat()) {
             setDown(true);
-            repaint(); //flush paint event before invoking potentially expensive operation
-            QApplication::flush();
+            repaint();
             d->emitPressed();
         }
         break;
@@ -1103,8 +1098,7 @@ void QAbstractButton::keyPressEvent(QKeyEvent *e)
 #ifndef QT_NO_SHORTCUT
         if (e->matches(QKeySequence::Cancel) && d->down) {
             setDown(false);
-            repaint(); //flush paint event before invoking potentially expensive operation
-            QApplication::flush();
+            repaint();
             d->emitReleased();
             return;
         }
diff --git a/src/widgets/widgets/qsplashscreen.cpp b/src/widgets/widgets/qsplashscreen.cpp
index 4ad2b83582..2758af53ef 100644
--- a/src/widgets/widgets/qsplashscreen.cpp
+++ b/src/widgets/widgets/qsplashscreen.cpp
@@ -164,15 +164,14 @@ void QSplashScreen::mousePressEvent(QMouseEvent *)
 }
 
 /*!
-    This overrides QWidget::repaint(). It differs from the standard
-    repaint function in that it also calls QApplication::flush() to
-    ensure the updates are displayed, even when there is no event loop
-    present.
+    This overrides QWidget::repaint(). It differs from the standard repaint
+    function in that it also calls QApplication::processEvents() to ensure
+    the updates are displayed, even when there is no event loop present.
 */
 void QSplashScreen::repaint()
 {
     QWidget::repaint();
-    QApplication::flush();
+    QApplication::processEvents();
 }
 
 /*!
@@ -190,13 +189,9 @@ void QSplashScreen::repaint()
 /*!
     Draws the \a message text onto the splash screen with color \a
     color and aligns the text according to the flags in \a alignment.
-
-    To make sure the splash screen is repainted immediately, you can
-    call \l{QCoreApplication}'s
-    \l{QCoreApplication::}{processEvents()} after the call to
-    showMessage(). You usually want this to make sure that the message
-    is kept up to date with what your application is doing (e.g.,
-    loading files).
+    This function calls repaint() to make sure the splash screen is
+    repainted immediately. As a result the message is kept up
+    to date with what your application is doing (e.g. loading files).
 
     \sa Qt::Alignment, clearMessage(), message()
 */
diff --git a/tests/benchmarks/gui/graphicsview/qgraphicsitem/tst_qgraphicsitem.cpp b/tests/benchmarks/gui/graphicsview/qgraphicsitem/tst_qgraphicsitem.cpp
index 88779e8471..313cc56b0b 100644
--- a/tests/benchmarks/gui/graphicsview/qgraphicsitem/tst_qgraphicsitem.cpp
+++ b/tests/benchmarks/gui/graphicsview/qgraphicsitem/tst_qgraphicsitem.cpp
@@ -69,14 +69,13 @@ tst_QGraphicsItem::~tst_QGraphicsItem()
 
 static inline void processEvents()
 {
-    QApplication::flush();
     QApplication::processEvents();
     QApplication::processEvents();
 }
 
 void tst_QGraphicsItem::initTestCase()
 {
-    QApplication::flush();
+    processEvents();
     QTest::qWait(1500);
     processEvents();
 }
diff --git a/tests/benchmarks/gui/graphicsview/qgraphicsscene/tst_qgraphicsscene.cpp b/tests/benchmarks/gui/graphicsview/qgraphicsscene/tst_qgraphicsscene.cpp
index 8189388d0f..622df2fb3b 100644
--- a/tests/benchmarks/gui/graphicsview/qgraphicsscene/tst_qgraphicsscene.cpp
+++ b/tests/benchmarks/gui/graphicsview/qgraphicsscene/tst_qgraphicsscene.cpp
@@ -62,7 +62,6 @@ tst_QGraphicsScene::~tst_QGraphicsScene()
 
 static inline void processEvents()
 {
-    QApplication::flush();
     QApplication::processEvents();
     QApplication::processEvents();
 }
diff --git a/tests/benchmarks/gui/graphicsview/qgraphicsview/tst_qgraphicsview.cpp b/tests/benchmarks/gui/graphicsview/qgraphicsview/tst_qgraphicsview.cpp
index 0064ecbaaf..cdec833f4e 100644
--- a/tests/benchmarks/gui/graphicsview/qgraphicsview/tst_qgraphicsview.cpp
+++ b/tests/benchmarks/gui/graphicsview/qgraphicsview/tst_qgraphicsview.cpp
@@ -44,7 +44,6 @@
 static inline void processEvents()
 {
     QPixmapCache::clear();
-    QApplication::flush();
     QApplication::processEvents();
     QApplication::processEvents();
 }
diff --git a/tests/benchmarks/gui/kernel/qwidget/tst_qwidget.cpp b/tests/benchmarks/gui/kernel/qwidget/tst_qwidget.cpp
index 19b8e27b63..aeec0624e8 100644
--- a/tests/benchmarks/gui/kernel/qwidget/tst_qwidget.cpp
+++ b/tests/benchmarks/gui/kernel/qwidget/tst_qwidget.cpp
@@ -33,7 +33,6 @@
 
 static void processEvents()
 {
-    QApplication::flush();
     QApplication::processEvents();
     QApplication::processEvents();
 }
@@ -174,7 +173,7 @@ void tst_QWidget::update()
         }
     }
 
-    QApplication::flush();
+    QApplication::processEvents();
 }
 
 void tst_QWidget::updatePartial_data()
diff --git a/tests/benchmarks/gui/styles/qstylesheetstyle/main.cpp b/tests/benchmarks/gui/styles/qstylesheetstyle/main.cpp
index b8d5478c03..c1e6d780ba 100644
--- a/tests/benchmarks/gui/styles/qstylesheetstyle/main.cpp
+++ b/tests/benchmarks/gui/styles/qstylesheetstyle/main.cpp
@@ -169,7 +169,6 @@ void tst_qstylesheetstyle::grid()
     if(show) {
         w->show();
         QTest::qWaitForWindowExposed(w);
-        QApplication::flush();
         QApplication::processEvents();
         QTest::qWait(30);
         QApplication::processEvents();