WaitWindow method delays script execution until the specified window appears on screen, unless a specified time limit is reached first. This function searches for the window in the given window’s child list.
TestObj.WaitWindow(WndClass, WndCaption, GroupIndex, WaitTime)
|TestObj||A variable, parameter or expression that specifies a reference to one of the objects listed in the Applies To section|
|WndCaption||[in]||Optional||String||Default value: *|
|GroupIndex||[in]||Optional||Integer||Default value: -1|
The method is applied to the following objects:
To view this method in the Object Browser panel and in other panels and dialogs, activate the Advanced view mode.
The method has the following parameters:
Name of the window class. If the window class name changes from one application run to another, or it changes during the script run, you can use wildcard characters ('*' and '?') in WndClass in place of variable parts. To specify an asterisk as part of the caption, duplicate it (**) in the WndClass string.
Window caption. If the window caption changes from one application run to another, or it changes during the script run, you can use wildcard characters ('*' and '?') in WndCaption in place of variable parts. The default value is '*'. To specify an asterisk as part of the caption, duplicate it (**) in the WndCaption string.
Note that if you specify an empty string as the parameter’s value, TestComplete interprets it as a string that contains an asterisk ('*'). For details, see Remarks below.
Window’s current front-to-back onscreen position (similar to z-order), relative to others of the same WndClass from the same parent TestObj.
1 means topmost. If GroupIndex is less than
1, it is disregarded.
During the test run, TestComplete may ignore the GroupIndex parameter and obtain the currently active window of the tested application instead of the specified one.
If you fail to obtain the correct window by its index, use the WndClass or WndCaption parameter to specify it. You can also use the
Time limit in milliseconds to wait for the specified window. If WaitTime is 0, the method searches for the desired window once and then returns immediately. If WaitTime is -1, the waiting time is infinite.
If you are testing an Open Application, the WaitTime parameter is required. For non-open applications, the WaitTime parameter is optional and has the default value 0.
Also, remember that the WaitTime value is not strict and if the tested application is busy, TestComplete may wait for the window for a longer period of time than what is specified by the parameter. The following may cause this:
A call to the
If the desired window is found,
WaitWindow returns the proper window object. Otherwise, it returns an empty stub object.
As it was said above, empty strings specified as the WndCaption parameter's value are interpreted as strings that contain an asterisk (“*”), that is, TestComplete interprets such window captions not as empty strings, but as any strings. This may cause problems when searching for windows having empty captions. For instance, if there are two or more sibling windows with the same class name, and one of these windows has an empty caption while the others do not, the
WaitWindow method may return any of these sibling windows with a non-empty caption instead of the needed window with an empty caption if you specify an empty string as the value of WndCaption. In such cases, TestComplete posts a warning message about ambiguous window recognition to the log, because two or more windows correspond to the specified search condition.
However, you can solve this problem and obtain the needed window having an empty caption by using one of the following approaches:
WaitWindow does not post an error message to the log if the desired window does not exist. It simply returns an empty stub object. Use the
Exists property of the returned object to determine whether the desired window exists in the system. If the window exists, its
Exists property will return True; the property of the stub object will return False. Note that calling any method of the stub object, except for
WaitWindow, will cause an error.
You should use
WaitWindow mostly to determine if your script should execute certain test actions, depending on whether or not the desired window exists. If all that you need is to wait until the window appears onscreen, then you can use the Window method to reference the corresponding window object and fill the pause either by using the
aqUtils.Delay method, or by increasing the value of the Auto-wait timeout project setting.
To view an example that demonstrates how to use the
WaitWindow method, see Waiting for an Object, Process or Window Activation.