Document expose event behavior

Document that "visible"-but-obscured windows may not
get expose events for various audiences: QTestLib
users, platform plugin authors and on the QExposeEvent
itself. QWindow::exposeEvent() already has this documented
and is not changed.

Task-number: QTBUG-50414
Change-Id: I91042e8b1c70e48f10e692b2e80367d242a8ccbe
Reviewed-by: Tor Arne Vestbø <tor.arne.vestbo@qt.io>

2 files changed, 22 insertions, 1 deletions

diff --git a/src/gui/kernel/qevent.cpp b/src/gui/kernel/qevent.cpp
index 680acb16e7..5000cc35dd 100644
--- a/src/gui/kernel/qevent.cpp
+++ b/src/gui/kernel/qevent.cpp
@@ -1525,7 +1525,11 @@ QMoveEvent::~QMoveEvent()
     \ingroup events
 
     Expose events are sent to windows when an area of the window is invalidated
-    or window visibility in the windowing system changes.
+    or window exposure in the windowing system changes.
+
+    A Window with a client area that is completely covered by another window, or
+    is otherwise not visible may be considered obscured by Qt and may in such
+    cases not receive expose events.
 
     The event handler QWindow::exposeEvent() receives expose events.
 */
diff --git a/src/gui/kernel/qwindowsysteminterface.cpp b/src/gui/kernel/qwindowsysteminterface.cpp
index 233c27dee7..e2087bd22f 100644
--- a/src/gui/kernel/qwindowsysteminterface.cpp
+++ b/src/gui/kernel/qwindowsysteminterface.cpp
@@ -303,6 +303,23 @@ QWindowSystemInterfacePrivate::ExposeEvent::ExposeEvent(QWindow *window, const Q
 {
 }
 
+/*! \internal
+    Handles an expose event.
+
+    The platform plugin sends expose events when an area of the window
+    is invalidated or window exposure changes. \a region is in window
+    local coordinates. An empty region indicates that the window is
+    obscured, but note that the exposed property of the QWindow will be set
+    based on what QPlatformWindow::isExposed() returns at the time of this call,
+    not based on what the region is. // FIXME: this should probably be fixed.
+
+    The platform plugin may omit sending expose events (or send obscure
+    events) for windows that are on screen but where the client area is
+    completely covered by other windows or otherwise not visible. Expose
+    event consumers can then use this to disable updates for such windows.
+    This is required behavior on platforms where OpenGL swapbuffers stops
+    blocking for obscured windows (like macOS).
+*/
 QT_DEFINE_QPA_EVENT_HANDLER(void, handleExposeEvent, QWindow *window, const QRegion &region)
 {
     QWindowSystemInterfacePrivate::ExposeEvent *e =