AuroraMiddleware/qt5base-lts
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update documentation of qWaitForWindowActive / qWaitForWindowExposed

Browse Source 
Sharpen existing documentation with a focus on use cases and
differences between both methods / overrides in qtestsupport_gui and
qtestsupport_widgets.

Pick-to: 6.4 6.2 5.15
Change-Id: I62b7be437dd43bb0b114af66de51fb4d1f55b671
Reviewed-by: Volker Hilsheimer <volker.hilsheimer@qt.io>
This commit is contained in:
Axel Spoerl 2022-09-24 09:24:13 +02:00
parent 24d5290133
commit e3358e2336
2 changed files with 31 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

24
src/gui/kernel/qtestsupport_gui.cpp
View File

@ -18,9 +18,16 @@ QT_BEGIN_NAMESPACE
/*!
\since 5.0
Waits for \a timeout milliseconds or until the \a window is active.
Returns \c true, if \a window is active within \a timeout milliseconds. Otherwise returns \c false.
Returns \c true if \c window is active within \a timeout milliseconds, otherwise returns \c false.
The method is useful in tests that call QWindow::show() and rely on the window actually being
active (i.e. being visible and having focus) before proceeding.
\note The method will time out and return \c false if another window prevents \a window from
becoming active.
\note Since focus is an exclusive property, \a window may loose its focus to another window at
any time - even after the method has returned \c true.
\sa qWaitForWindowExposed(), QWindow::isActive()
*/
@ -40,15 +47,14 @@ Q_GUI_EXPORT bool QTest::qWaitForWindowActive(QWindow *window, int timeout)
/*!
\since 5.0
Waits for \a timeout milliseconds or until the \a window is exposed.
Returns \c true if \c window is exposed within \a timeout milliseconds, otherwise returns \c false.
Returns \c true, if \a window is exposed within \a timeout milliseconds. Otherwise returns \c false.
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.
The method is useful in tests that call QWindow::show() and rely on the window actually being
being visible before proceeding.
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.
\note A window mapped to screen may still not be considered exposed, if the window client area is
not visible, e.g. because it is completely covered by other windows.
In such cases, the method will time out and return \c false.
\sa qWaitForWindowActive(), QWindow::isExposed()
*/

29
src/widgets/kernel/qtestsupport_widgets.cpp
View File

@ -32,9 +32,16 @@ static bool qWaitForWidgetWindow(FunctorWindowGetter windowGetter, FunctorPredic
/*!
\since 5.0
Waits for \a timeout milliseconds or until the \a widget's window is active.
Returns \c true if \a widget is active within \a timeout milliseconds. Otherwise returns \c false.
Returns \c true if \c widget's window is active within \a timeout milliseconds, otherwise returns \c false.
The method is useful in tests that call QWidget::show() and rely on the widget actually being
active (i.e. being visible and having focus) before proceeding.
\note The method will time out and return \c false if another window prevents \a widget from
becoming active.
\note Since focus is an exclusive property, \a widget may loose its focus to another window at
any time - even after the method has returned \c true.
\sa qWaitForWindowExposed(), QWidget::isActiveWindow()
*/
@ -56,20 +63,16 @@ Q_WIDGETS_EXPORT bool QTest::qWaitForWindowActive(QWidget *widget, int timeout)
/*!
\since 5.0
Waits for \a timeout milliseconds or until the \a widget's window is exposed.
Returns \c true if \c widget's window is exposed within \a timeout milliseconds, otherwise returns \c false.
Returns \c true if \a widget is exposed within \a timeout milliseconds. Otherwise returns \c false.
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.
The method is useful in tests that call QWidget::show() and rely on the widget actually being
being visible before proceeding.
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.
\note A window mapped to screen may still not be considered exposed, if the window client area is
not visible, e.g. because it is completely covered by other windows.
In such cases, the method will time out and return \c false.
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 qWaitForWindowActive()
\sa qWaitForWindowActive(), QWidget::isVisible(), QWindow::isExposed()
*/
Q_WIDGETS_EXPORT bool QTest::qWaitForWindowExposed(QWidget *widget, int timeout)
{