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>

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
+    Depending from the event dispatcher implementation does nothing or
-    immediately. Does nothing on platforms other than X11.
+    calls QApplication::sendPostedEvents().
 */
 
 // ### DOC: Are these called when the _application_ starts/stops or just

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();

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
+    be sent with sendEvent() or posted to an event queue with postEvent().
-    sendPostedEvents(). Pending events can be removed with
+    Pending events can be removed with removePostedEvents() or dispatched
-    removePostedEvents() or flushed with flush().
+    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
+    Historically this functions was used to flush the platform-specific native event queues.
-    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.
 
-    \sa sendPostedEvents()
+    \sa sendPostedEvents(), processEvents(), QAbstractEventDispatcher::flush()
 */
 void QCoreApplication::flush()
 {

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);

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
+    q->repaint();
-    QApplication::flush();
     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
+    repaint();
-    QApplication::flush();
     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
+        repaint();
-        QApplication::flush();
         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
+        repaint();
-        QApplication::flush();
         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
+            repaint();
-            QApplication::flush();
             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
+            repaint();
-            QApplication::flush();
             d->emitReleased();
             return;
         }

src/widgets/widgets/qsplashscreen.cpp

@@ -164,15 +164,14 @@ void QSplashScreen::mousePressEvent(QMouseEvent *)
 }
 
 /*!
-    This overrides QWidget::repaint(). It differs from the standard
+    This overrides QWidget::repaint(). It differs from the standard repaint
-    repaint function in that it also calls QApplication::flush() to
+    function in that it also calls QApplication::processEvents() to ensure
-    ensure the updates are displayed, even when there is no event loop
+    the updates are displayed, even when there is no event loop present.
-    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.
-
+    This function calls repaint() to make sure the splash screen is
-    To make sure the splash screen is repainted immediately, you can
+    repainted immediately. As a result the message is kept up
-    call \l{QCoreApplication}'s
+    to date with what your application is doing (e.g. loading files).
-    \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).
 
     \sa Qt::Alignment, clearMessage(), message()
 */

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();
 }

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();
 }

tests/benchmarks/gui/graphicsview/qgraphicsview/tst_qgraphicsview.cpp

@@ -44,7 +44,6 @@
 static inline void processEvents()
 {
     QPixmapCache::clear();
-    QApplication::flush();
     QApplication::processEvents();
     QApplication::processEvents();
 }

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()

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();