Description

The Window method searches for a window in the child list of the TestObj window. If the search is successful, the method returns the found window, otherwise it returns an empty object and posts an error message to the test log. Call Exists to determine whether the returned object exists. To obtain the window object without posting any messages to the log, use WaitWindow or WaitChild.

Declaration

TestObj.Window(WndClass, WndCaption, GroupIndex)

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
Result	A `Window` 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

Window class name. 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 to mark variable parts. To specify an asterisk as part of the window class name, use two asterisks (**) 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.

Note that when recording a script TestComplete may not record the GroupIndex parameter for the Window function. This typically happens if WndClass and WndCaption provides enough information for window recognition.

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.

Result Value

A window object that represents the desired child window.

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 Window 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 Window method to specify the window’s index in addition to its class name and caption.
Use the FindChild method instead of the Window method.
Use Name Mapping to recognize the window.

For more information on the recognition attributes of window objects (class name, caption and index), see Naming Windows.

Example

The following example demonstrates how to use the Window method in scripts:

JavaScript, JScript

processObj = Sys.Process("winword");
windowObj = processObj.Window("OpusApp", "Microsoft Word - *", 1)