WaitForWindow

Syntax

WaitForWindow
  [Caption="<caption>" | Handle=<hwnd>]
  [Class="<class>"]
  [Timeout=<secs>]
  [Exclude=<handlelist>]
  [NoActivate]
  [Result=<var>]

Description

Wait for a window to appear on the screen. The window is made the active window and brought to the foreground.

Parameters

Caption="<caption>"

The window's title bar text. This parameter, together with the optional Class parameter is used to identify the window. If the last character of the caption is an asterisk (*), then the search is for a window whose title bar text begins with the characters preceeding the asterisk. If the first character of the caption is an asterisk, then the search is for a window whose title bar text ends with the characters after the asterisk. If the first and last characters are both asterisks, the search is for a window whose title bar text contains the text between the asterisks. Either Caption or Handle must be supplied.

Handle=<hwnd>

The window handle of the window to wait for. The window handle must have been obtained from a previous SetWindow or WaitForWindow statement's Result. Use of this parameter instead of Caption (and Class) results in much faster processing of the statement. Either Caption or Handle must be supplied.

Class="<class>"

Optional. The window class of the window. This parameter is used to further refine the window search. This is useful for example when an application's pop-up dialog box has the same title as the application main window. The Class parameter is included automatically by the recorder.

Timeout=<secs>

Optional. The period in seconds after which execution of the script will continue regardless of whether the window was found. If a timeout occurs, the variableTimedOut is set toTrue. Otherwise, it is set toFalse. If the Timeout parameter is not specified, the TimedOut variable's value is not modified. A timeout value of zero causes an immediate timeout if the window is not already visible.

Exclude=<handlelist>

Optional. This parameter specifies a list (a CSV list) of window handles that are to be ignored in the search for a matching window. These handles must have been obtained in an earlier SetWindow, WaitForWindow, ChildWindows, or other call that returns a window handle.

NoActivate

Optional. If this parameter is present, the window found is not given the input focus nor is it brought to the foreground. If this parameter is not present, the window is brought to the foreground and given the input focus.

Result=<var>

Optional. This parameter specifies a variable into which the window handle of the window is inserted. This value can then be used in subsequent SetWindow and Wait ForWindow statements.

Example

WaitForWindow Caption="Notepad*" Timeout=0
If TimedOut Then
  MessageBox
     Title=Error
     Text="No Notepad"
     Ok Stop
EndIf

The above code fragment checks for a Notepad window. The timeout value of zero means that a timeout will occur immediately if the window is not already visible. If the Notepad is not up, a message box is displayed indicating an error.