Wait - For window

 

Declaration

<AMWAITFORWINDOW WINDOWTITLE="text" ALLOWHIDDEN="YES/NO" WINDOWHANDLEVARIABLE="text" WINDOWCLASSVARIABLE="text" WINDOWTITLEVARIABLE="text" CONTAINSOBJECT="YES/NO" OBJECTNAME="text" OBJECTVALUE="text" OBJECTCLASS="text" OBJECTTYPE="text" CHECKOBJECTNAME="YES/NO" CHECKOBJECTVALUE="YES/NO" CHECKOBJECTCLASS="YES/NO" CHECKOBJECTTYPE="YES/NO" RESULTDATASET="text" FOCUSWINDOW="YES/NO" />

Related Topics   

Description

Causes task execution to pause at the current step until a specific window is open, closed, focused, or unfocused.

Practical Usage

Commonly used to wait for the appearance or disappearance of a dialog box or window generated by an external application. This can be used to confirm that a process has completed successfully. For example, if automating a report printing process, you could use the Wait for Window action to wait until the dialog box "Report Complete" appears before performing further processing.  If the window appears, the task continues, and if not, it fails.

Parameters

General

This activity comprises AutoMate's Window Dissection technology to facilitate the discovery of existing windows and their controls. To select the target window:

  1. Make certain the window is open and in the foreground (in front of all other open windows).
  2. Drag and release the magnifier icon over the window. If the window is supported by this activity, a green border will appear around it.
  3. Upon releasing the icon, identified window properties are populated onto the editor. These properties can be enabled/disabled or further modified.

Property

Type

Required

Default

Markup

Description

By window title

Text

Yes

(Empty)

  1. WINDOWTITLE="Untitled Notepad"

  2. WINDOWTITLE="*Internet Explorer*"

The enabled, indicates the title of the window to wait for. If disabled, the window title will be ignored. This parameter supports wildcard characters (* and ?) to denote partial matches. For example, entering  *Explorer* would include any window that contains the word Explorer in its title.

By window class

Text

No

(Empty)

WINDOWCLASS="Outlook Express Browser Class"

If enabled, indicates the class of the window to wait for. If disabled, the window class will be ignored. A window class is a set of attributes that the system uses as a template to create a window. Every window is a member of a class and all window classes are process specific. This parameter supports wildcard characters (* and ?) to denote partial matches. For example, entering  *Outlook* would include any window with a class containing the word Outlook.

By window handle

Number

No

(Empty)

WINDOWHANDLE="555735"

If enabled, indicates the handle of the window to wait for.  If disabled, the window handle will be ignored. A window handle is numeric code that uniquely identifies an open window.

Accessibility engine

Text (options)

No

Auto

  1. ACCESSIBILITYENGINE="auto"

  2. ACCESSIBILITYENGINE="active"

  3. ACCESSIBILITYENGINE="java"

  4. ACCESSIBILITYENGINE="ie"

The accessibility engine that this activity will use to programmatically gather accurate information about a user interface. The available options are:

  • Auto (default) - AutoMate will detect the best accessibility engine to use based on current properties.
  • Active - Active Accessibility will be used. Active Accessibility is Microsoft's standard for exposing information about its user interface.
  • Java - Java Access Bridge will be used, which is a technology that enables certain Java applications and applets to be visible to assistive technologies on Microsoft Windows systems.
  • Internet Explorer - Internet Explorer DOM will be used, which is the Document Object Model used to represent objects in a web page (i.e. text, images, headers, links, etc.).

Action

Text (options)

Yes

Open

  1. ACTION="open"

  2. ACTION="close"

  3. ACTION="focus"

  4. ACTION="background"

Specifies the action to wait for. The available options are:

  • Wait for window to open (default) - Wait for the window to be opened.

  • Wait for window to close - Wait for the window to be closed.

  • Wait for window to gain focus - Wait for the window to be focused.

  • Wait for the window to lose focus - Wait for the window to be unfocused.

Window is a child window

Yes/No

No

No

CHILDWINDOW="YES"

If set to YES, specifies that the window to wait for is a child window. This option is useful for Multi-Document Interface (MDI) applications, which contain a series of windows contained within one parent window. This parameter is set to NO by default.

Focus found window

Yes/No

No

No

FOCUSWINDOW="YES"

If set to YES, denotes that the window to wait for should be focused when found. If set to NO, the found window will not be focused. This is commonly set to YES with a Wait for window to open action to ensure that the window is also focused to allow ensuing steps to properly interact with it.

Window Contents

If multiple windows with the same title exists, it may be necessary to use AutoMate's Object Editor to specify additional criteria, such as unique objects, controls or properties, in order to distinguish one window from another. To identify additional elements, enable Window must contain the following object(s) and press Add to open the Object Editor dialog. Thereafter, do one of the following:

  1. Drag  and release the magnifier icon over the desired object or control. The Object properties grid becomes populated with a list of name/value pairs unique to that object. Individual values can be enabled/disabled according to preference.
  2. Press Browse to traverse the list of available objects/controls for the selected window. Select the desired object from the Window contents column and press OK. The Object properties grid becomes populated with a list of defined properties unique to that object. Individual values can be enabled or disabled according to preference.

Available object properties are described below.

Property

Type

Required

Default

Markup

Description

Toolkit

Text

No

(Empty)

TOOLKIT=WindowsAccessibility

If enabled, specifies that the toolkit (a set of basic building units for graphical user interfaces) will be examined when determining a matching object. If disabled, the toolkit will be ignored.

Type

Text

No

(Empty)

TYPE="PushButton"

If enabled, specifies that the object type (i.e. Button, Checkbox, Trackbar) will be examined when determining a matching object. If disabled, the object type will be ignored.

Class

Text

No

(Empty)

CLASS="SysTreeView32"

If enabled, specifies that the object class (i.e. XTPToolBar, SysTreeView, MDIClient) will be examined when determining a matching object. If disabled, the object class will be ignored.

Name

Text

No

(Empty)

NAME="Cancel"

If enabled, specifies that the object name (the unique identifier for an object) will be examined when determining a matching object. If disabled, the object name will be ignored.

Value

Text

No

(Empty)

VALUE="1"

If enabled, specifies that the value of the object (which usually coincides with the Name property) will be examined when determining a matching object. If disabled, the object value will be ignored.

X

Number

No

(Empty)

X="80"

If enabled, specifies that the object's X coordinate ( a given number of pixels along the horizontal axis of a window starting from the extreme left side) will be examined when determining a matching object. If disabled, the X coordinate will be ignored.

NOTE: The X and Y coordinates are relative to the specified window as opposed to the screen.

Y

Number

No

(Empty)

Y="90"

If enabled, specifies that the object's Y coordinate ( a given number of pixels along the vertical axis of a window starting from the top-most portion) will be examined when determining a matching object. If disabled, the Y coordinates will be ignored.

NOTE: The X and Y coordinates are relative to the specified window as opposed to the screen.

Advanced

Property

Type

Required

Default

Markup

Description

Include hidden windows

Yes/No

No

No

ALLOWHIDDEN="YES"

If set to YES, specifies that hidden (non-visible) windows should be included in the window search. By default, hidden windows are not searched.

Populate window title in variable

Text

No

(Empty)

WINDOWTITLEVARIABLE="VarName"

If enabled, specifies the name of an existing variable that should be populated with the title of the window to wait for.

Populate window class in variable

Text

No

(Empty)

WINDOWCLASSVARIABLE="VarName"

If enabled, specifies the name of an existing variable that should be populated with the class of the window to wait for.

Populate window handle in variable

Text

No

(Empty)

WINDOWHANDLEVARIABLE="VarName"

If enabled, specifies the name of an existing variable that should be populated with the handle of the window to wait for.

Create and populate dataset

Text

No

(Empty)

RESULTDATASET="DatasetName"

The name of a dataset to be created and populated with information about the window to wait for. For more details see Datasets below.

 

Description

Error Causes

On Error

additional notes

Datasets

A dataset is a multiple column, multiple row container object. This activity creates and populates a dataset containing a specific set of fields in addition to the standard dataset fields. The table below describes these fields (assuming the dataset name assigned was theDataset).

Name

Type

Return Value

theDataset.Title

Text

Returns the window title of the window.

theDataset.Class

Text

Returns the class of the window.

theDataset.Handle

Number

Returns the handle of the window.

Example

NOTE: The sample AML code below can be copied and pasted directly into the Steps panel of the Task Builder.

Description:

This sample task waits for a window titled "Google - Windows Internet Explorer" to open. When doing so, a message dialog appears displaying the newly opened window's title, class and handle.

<AMVARIABLE NAME="handlevar" />

<AMVARIABLE NAME="classvar" />

<AMVARIABLE NAME="titlevar" />

<AMWAIT ACTIVITY="window" WINDOWTITLE="Google - Windows Internet Explorer" CONTAINSOBJECT="YES" OBJECTPROPERTYSETS="Type=Picture,Name=Google,Value=http://www.google.com/intl/en_ALL/images/srpr/logo1w.png,Class=Internet Explorer_Server" ALLOWHIDDEN="YES" WINDOWTITLEVARIABLE="titlevar" WINDOWCLASSVARIABLE="classvar" WINDOWHANDLEVARIABLE="handlevar" RESULTDATASET="thedataset" FOCUSWINDOW="YES" />

<AMSHOWDIALOG WINDOWTITLE="Window title, handle and class">Window title - %titlevar%

Window handle - %handlevar%

Window class - %classvar%</AMSHOWDIALOG>