Description

The 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.

Declaration

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
WndClass	[in]	Required	String
WndCaption	[in]	Optional	String	Default value: *
GroupIndex	[in]	Optional	Integer	Default value: -1
WaitTime	[in]	Required	Integer
Result	Object

Applies To

The method is applied to the following objects:

Browser, BrowserWindow, Process, Window

View Mode

To view this method in the Object Browser panel and in other panels and dialogs, activate the Advanced view mode.

Parameters

The method has the following parameters:

WndClass

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.

WndCaption

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.

GroupIndex

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 FindChild or WaitChild method to obtain the window or map the window name.

WaitTime

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.

Note:

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 WaitWindow method causes the object tree to refresh. To update object data, TestComplete may call some of the object’s native methods that are accessible only from the application’s thread. When the thread is busy, TestComplete tries to call those methods during some pre-defined time (one second) thus delaying the refresh. There could be several attempts to get the object’s data which could result in a noticeable difference from the WaitTime value.

Result Value

If the desired window is found, WaitWindow returns the proper window object. Otherwise, it returns an empty stub object.

Remarks

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:

Use the GroupIndex parameter of the WaitWindow method to specify the window’s index in addition to its class name and caption.
Use the FindChild method instead of the WaitWindow method.
Use Name Mapping to recognize the window.

Unlike the Window method, 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.

Example

To view an example that demonstrates how to use the WaitWindow method, see Waiting for an Object, Process or Window Activation.

WaitWindow Method