summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorMorten Johan Sørvig <morten.sorvig@qt.io>2016-01-21 10:33:45 +0100
committerTor Arne Vestbø <tor.arne.vestbo@qt.io>2017-07-11 15:25:00 +0000
commitecac1aeb29f37a080d4f2d3614bfc5fcc5b70689 (patch)
tree0bb1f62818a870e8f287558d56935762a6187a07
parenta6991376cc4c7084a151272d7e27a5140597cc9e (diff)
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>
-rw-r--r--src/gui/kernel/qevent.cpp6
-rw-r--r--src/gui/kernel/qwindowsysteminterface.cpp17
-rw-r--r--src/testlib/qtestcase.qdoc11
3 files changed, 33 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 =
diff --git a/src/testlib/qtestcase.qdoc b/src/testlib/qtestcase.qdoc
index 1b1a8b6007..2d1e27ec40 100644
--- a/src/testlib/qtestcase.qdoc
+++ b/src/testlib/qtestcase.qdoc
@@ -1084,6 +1084,10 @@
This is mainly useful for asynchronous systems like X11, where a window will be mapped to screen some
time after being asked to show itself on the screen.
+ Note that a window that is mapped to screen may still not be considered exposed if the window client
+ area is completely covered by other windows, or if the window is otherwise not visible. This function
+ will then time out when waiting for such a window.
+
\sa QTest::qWaitForWindowActive(), QWindow::isExposed()
*/
@@ -1106,6 +1110,13 @@
This is mainly useful for asynchronous systems like X11, where a window will be mapped to screen some
time after being asked to show itself on the screen.
+ Note that a window that is mapped to screen may still not be considered exposed if the window client
+ area is completely covered by other windows, or if the window is otherwise not visible. This function
+ will then time out when waiting for such a window.
+
+ A specific configuration where this happens is when using QGLWidget as a viewport widget on macOS:
+ The viewport widget gets the expose event, not the parent widget.
+
\sa QTest::qWaitForWindowActive()
*/