Introduce QWindow::paintEvent with QPA plumbing

The explicit paint event on QtGui and QPA level allows us to untangle
the expose event, which today has at least 3 different meanings.

It also allows us to follow the platform more closely in its semantics
of when painting can happen. On some platforms a paint can come in
before a window is exposed, e.g. to prepare the first frame. On others
a paint can come in after a window has been de-exposed, to save a
snapshot of the window for use in an application switcher or similar.

The expose keeps its semantics of being a barrier signaling that the
application can now render at will, for example in a threaded render
loop.

There are two compatibility code paths in this patch:

  1. For platform plugins that do not yet report the PaintEvents
     capability, QtGui will synthesize paint events on the platform's
     behalf, based on the existing expose events coming from the platform.

  2. For applications that do not yet implement paintEvent, QtGui will
     send expose events instead, ensuring the same behavior as before.

For now none of the platform plugins deliver paint events natively,
so the first compatibility code path is always active.

Task-numnber: QTBUG-82676
Change-Id: I0fbe0d4cf451d6a1f07f5eab8d376a6c8a53ce8c
Reviewed-by: Paul Olav Tvete <paul.tvete@qt.io>

1 files changed, 34 insertions, 13 deletions

diff --git a/src/gui/kernel/qwindow.cpp b/src/gui/kernel/qwindow.cpp
index 3fed7c3776..be1e3532fd 100644
--- a/src/gui/kernel/qwindow.cpp
+++ b/src/gui/kernel/qwindow.cpp
@@ -1198,7 +1198,7 @@ void QWindow::requestActivate()
 
     When the window is not exposed, it is shown by the application
     but it is still not showing in the windowing system, so the application
-    should minimize rendering and other graphical activities.
+    should minimize animations and other graphical activities.
 
     An exposeEvent() is sent every time this value changes.
 
@@ -2246,24 +2246,22 @@ bool QWindow::close()
 }
 
 /*!
-    The expose event (\a ev) is sent by the window system whenever an area of
-    the window is invalidated, for example due to the exposure in the windowing
-    system changing.
+    The expose event (\a ev) is sent by the window system when a window moves
+    between the un-exposed and exposed states.
 
-    The application can start rendering into the window with QBackingStore
-    and QOpenGLContext as soon as it gets an exposeEvent() such that
-    isExposed() is true.
+    An exposed window is potentially visible to the user. If the window is moved
+    off screen, is made totally obscured by another window, is minimized, or
+    similar, this function might be called and the value of isExposed() might
+    change to false. You may use this event to limit expensive operations such
+    as animations to only run when the window is exposed.
 
-    If the window is moved off screen, is made totally obscured by another
-    window, iconified or similar, this function might be called and the
-    value of isExposed() might change to false. When this happens,
-    an application should stop its rendering as it is no longer visible
-    to the user.
+    This event should not be used to paint. To handle painting implement
+    paintEvent() instead.
 
     A resize event will always be sent before the expose event the first time
     a window is shown.
 
-    \sa isExposed()
+    \sa paintEvent(), isExposed()
 */
 void QWindow::exposeEvent(QExposeEvent *ev)
 {
@@ -2271,6 +2269,25 @@ void QWindow::exposeEvent(QExposeEvent *ev)
 }
 
 /*!
+    The paint event (\a ev) is sent by the window system whenever an area of
+    the window needs a repaint, for example when initially showing the window,
+    or due to parts of the window being uncovered by moving another window.
+
+    The application is expected to render into the window in response to the
+    paint event, regardless of the exposed state of the window. For example,
+    a paint event may be sent before the window is exposed, to prepare it for
+    showing to the user.
+
+    \since 6.0
+
+    \sa exposeEvent()
+*/
+void QWindow::paintEvent(QPaintEvent *ev)
+{
+    ev->ignore();
+}
+
+/*!
     Override this to handle window move events (\a ev).
 */
 void QWindow::moveEvent(QMoveEvent *ev)
@@ -2421,6 +2438,10 @@ bool QWindow::event(QEvent *ev)
         exposeEvent(static_cast<QExposeEvent *>(ev));
         break;
 
+    case QEvent::Paint:
+        paintEvent(static_cast<QPaintEvent *>(ev));
+        break;
+
     case QEvent::Show:
         showEvent(static_cast<QShowEvent *>(ev));
         break;