Wait - For window

Declaration

<AMWAITFORWINDOW WINDOWTITLE="text" ALLOWHIDDEN="YES/NO" WINDOWHANDLEVARIABLE="text" WINDOWCLASSVARIABLE="text" WINDOWTITLEVARIABLE="text" OBJECTPROPERTYSETS="Toolkit=text,Type=text,Class=text,FrameworkId=text,Name=text,AutomationId=text,Value=text,Role=text,Description=text,X=number,Y=number,Width=number,Height=number,IndexInParent=text,ParentPath=text,Occurrence=number" 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 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 "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 Desktop'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)
  • WINDOWTITLE="Untitled Notepad"
  • 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 (that is, * 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 (that is, * 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
  • ACCESSIBILITYENGINE="auto"
  • ACCESSIBILITYENGINE="ui_automation"
  • ACCESSIBILITYENGINE="active"
  • ACCESSIBILITYENGINE="java"
  • ACCESSIBILITYENGINE="ie"
 The accessibility engine that this activity will use to programmatically gather accurate information about a user interface in order to interact with it. The available options are:
  • Auto - Starting with UI Automation, Automate Desktop detects which accessibility engine to use based on the control's properties.
    NOTE: Some controls may not be compatible with this option and will require one of the other accessibility engine options to be manually selected for best results.
  • UI Automation - UI Automation will be used, which is Microsoft's standard for exposing information about its user interface.
  • Active - Active Accessibility will be used, which uses an older Microsoft engine 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 (that is, text, images, headers, links, etc.).
Action Text (options) Yes Open
  • ACTION="open"
  • ACTION="close"
  • ACTION="focus"
  • ACTION="background"
 Specifies the action to wait for. The available options are:
  • Wait for window to open- 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 selected, 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 disabled by default.
Focus found window Yes/No No No FOCUSWINDOW="YES" If selected, denotes that the window to wait for should be focused when found. If disabled, the found window will not be focused. This is commonly selected 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 Desktop'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 objects, and then click 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. Click Browse to traverse the list of available objects / controls for the selected window. Select the desired object from the Window contents column, and then click 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=UIAutomation
  • TOOLKIT=WindowsAccessibility
  • TOOLKIT=JavaAccessibility
 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.

The toolkit that appears is based on the Accessibility engine used:

  • UI Automation - UIAutomation
  • Active - WindowsAccessibility
  • Java - JavaAccessibility
  • Internet Explorer - WindowsAccessibility
Type Text No (Empty) TYPE=PushButton If enabled, specifies that the object's type (that is, Button, Checkbox, Trackbar) will be examined when determining a matching object. If disabled, the type will be ignored.
Class Text No (Empty) CLASS=SysTreeView32 If enabled, specifies that the object's class (that is, XTPToolBar, SysTreeView, MDIClient) will be examined when determining a matching object. If disabled, the class will be ignored.
FrameworkId Text No (Empty) FRAMEWORKID=WPF If enabled, specifies that the object's framework ID (the framework technology used to create the object) will be examined when determining a matching object. If disabled, the framework ID will be ignored.
Name Text No (Empty) NAME=Cancel If enabled, specifies that the object's name (a unique identifier for an object) will be examined when determining a matching object. If disabled, the name will be ignored.
AutomationId Text No (Empty) AUTOMATIONID=System If enabled, specifies that the object's automation ID (a unique identifier for an object) will be examined when determining a matching object. If disabled, the automation ID will be ignored.
Value Text No (Empty) VALUE=1 If enabled, specifies that the object's value (which usually coincides with the Name property) will be examined when determining a matching object. If disabled, the value will be ignored.
Role Text No (Empty) ROLE=desktop pane If enabled, specifies that the object's role type (the control type provided by the Java Accessibility bridge) will be examined when determining a matching object. If disabled, the role type will be ignored.
Description Text No (Empty) DESCRIPTION=JScrollPane If enabled, specifies that the object's description (the description given for an object) will be examined when determining a matching object. If disabled, the description 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.
Width Number No (Empty) WIDTH=711 If enabled, specifies that the object's pixel width will be examined when determining a matching object. If disabled, the pixel width will be ignored.
Height Number No (Empty) HEIGHT=42 If enabled, specifies that the object's pixel height will be examined when determining a matching object. If disabled, the pixel height will be ignored.
IndexInParent Text No (Empty) INDEXINPARENT=1 If enabled, specifies that the object's index in parent number (the numeric identifier of a child object located within a parent object) will be examined when determining a matching object. If disabled, the index in parent number will be ignored.
ParentPath Text No (Empty) PARENTPATH=50032|50033 If enabled, specifies that the object's parent path (the sequence of control type identifiers that lead to the object) will be examined when determining a matching object. If disabled, the parent path will be ignored.
Occurrence Number No (Empty) OCCURRENCE=1 If enabled, specifies that the object's occurrence (the numeric identifier of an object, useful when multiple matching objects are found) will be examined when determining a matching object. If disabled, the occurrence will be ignored.

Advanced

Property Type Required Default Markup Description
Include hidden windows Yes/No No No ALLOWHIDDEN="YES" If selected, 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:
  • Copy and paste the sample AML code below directly into the Task Builder Steps Panel.
  • To successfully run the sample code, update parameters containing user credentials, files, file paths, or other information specific to the task to match your environment.

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.

Copy 
<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>