Loop Windows Action Icon

Loop Windows

Declaration

<AMLOOP TYPE="WINDOWS" RESULTVARIABLE="text" ALLOWHIDDEN="YES/NO" EXCLUDE="text" SORT="text(options)" WINDOWHANDLEVARIABLE="text" RESULTDATASET="text">

See Also

Loop | End Loop | Loop Files | Loop Windows | Loop Processes | Loop Expression | Loop Dataset | Loop List | Loop List Control | Loop Processes | Loop Tree Control | Loop Windows | Break

Description

Loops through all of the Windows that are currently open on the system. The variable specified is updated with the current window title. With each successive loop, the next window title is retrieved. The loop ends after the window title of all the open windows have been retrieved or when a Break is encountered.

Practical Usage

Ideally used to perform one or more actions on every window that is open on the system.

Parameters

General Properties

Property

Type

Required

Default

Markup

Description

Populate Variable with Window Title

Text

Yes

(Empty)

RESULTVARIABLE="varname"

The name of the variable that should be populated with the current window title upon each successive loop.

Include Hidden Windows

Yes/No

No

No

ALLOWHIDDEN="yes"

If set to YES, invisible (or hidden) windows should be included in the loop results.

 

Advanced Properties

Property

Type

Required

Default

Markup

Description

Include Windows

Text

No

(Empty)

INCLUDE="*Explorer"

Indicates a wildcard mask to designate the titles of windows to be included in the loop. For example, if "*Internet Explorer" was specified, the loop would only include window titles ending with the text Internet Explorer. Asterisk (*) or question mark (?) can be used as wildcard characters.

Exclude Windows

Text

No

 

(Empty)

 

EXCLUDE="*Explorer"

Specifies a wildcard mask to designate the titles of the windows to be excluded from the loop. For example, if "*Internet Explorer" was specified, the loop would include all window titles except those ending with the text Internet Explorer. Asterisk (*) or question mark (?) can be used as wildcard characters.

Populate Variable with Window Handle

Text

No

Disabled

WINDOWHANDLEVARIABLE="Var1"

If enabled, indicates the name of the variable that should be populated with the current window handle upon each successive loop. This parameter is disabled by default.

Create and Populate Dataset

Text

No

Disabled

RESULTDATASET="theDataset"

If enabled, indicates the name of a dataset to be created and populated with data about each window being looped. In addition to the standard dataset fields, this dataset contains specific action specific fields entered below under Notes. This parameter is disabled by default.

Sorting

Text (options)

No

None

SORT="ascending"

Specifies whether a sort order should be applied to the window titles before loop begins. The available options are:

  • Do not sort list (default)

  • Sort the list in ascending alphabetical order

  • Sort the list in descending alphabetical order

 

Description Properties

The Description tab allows you to customize the text description of any step as it appears in the Task Builder's Steps Pane.

More on setting custom step description

Error Causes Properties

The Error Causes tab allows you to select/omit specific errors that should cause a particular step to fail.

More on Error Causes properties

On Error Properties

The On Error tab allows you to determine what the task should do if a particular step encounters an error.

More about On Error properties

Notes

Datasets

A dataset is a multiple column, multiple row container object. For example, in a SQL Query action, the fields contained within the created dataset are determined by the query that was executed. For example if the following query is executed:

 

 

SELECT firstname, lastname, company from customer where city='Los Angeles';

 

 

Then the following dataset would be generated (where datasetname specifies the name of the dataset):

 

datasetname.firstname

datasetname.lastname

datasetname.company

 

A record (row) is created for each record (row) that is retrieved from the server. To access this data use the Loop Dataset Action to loop through the records, inside the loop you can extract the data from the field of your choice (from the current record) by using an embedded expression such as the one that follows:

 

%datasetname.firstname%

 

 

or you could combine two fields together like this:

 

%datasetname.firstname + " " + datasetname.lastname%

 

 

Embedded Expressions such as these can be used in any parameter in any action. So, to display the data in a message box the AML code would look like this:

 

 

<AMMESSAGEBOX MESSAGETEXT="%datasetname.firstname%" WINDOWTITLE="The firstname of the current record is">

 

At runtime the text %datasetname.firstname% is replaced by the contents of the subject of the current record.

 

This action creates a dataset with the following fields (assuming the name of the dataset is theDataset):

Name

Data Type

Return Value

theDataset.Title

Text

Returns the window title.

theDataset.Handle

Number

Returns the window handle.

theDataset.Class

Text

Returns the window class.

 

There are standard fields included in every dataset. The table below describes these fields (assuming the name of the dataset is theDataset):

 

Name

Data Type

Return Value

theDataset.CurrentRow

Number

The current row that will be accessed in the dataset by an expression that does not contain a specific row index.

theDataset.TotalRows

Number

The total number of rows in the dataset

theDataset.TotalColumns

Number

The total number of columns (not including the static columns) in the dataset.

theDataset.ExecutionDate

Date

The date and time the dataset was created and populated

theDataset.RowsAffected

Number

The number of rows affected by an update.

theDataset.SQLQuery

Text

The SQL Query that was used to generate this dataset (If a SQL Query was not used, this value is empty).

theDataset.Datasource

Text

The datasource used for the SQL Query, if applicable.

theDataset.ColumnNames

Text

A comma-delimited list of the column names in the dataset

Variables and Expressions

All text fields allow the use of expressions, which can be entered by surrounding the expression in percentage signs (Example: %myVariable% or %Left('Text',2)%). To help construct these expressions, you can open Expression Builder from these fields by clicking the Insert expression/variable button or pressing F2.

More on variables
More on expressions

More on the Expression Builder

Example

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

 

Sample Task 1 - Loop Windows action used to loop all open windows in alphabetical order excluding windows that contain the text Internet Explorer in its title. A message box is displayed during each successful iteration displaying the title of the current window.

 

<AMVARIABLE NAME="theTitle"></AMVARIABLE>

<AMLOOP TYPE="WINDOWS" RESULTVARIABLE="theTitle" EXCLUDE="*Internet Explorer*" SORT="ascending">

     <AMMESSAGEBOX>A Window titled &quot;%theTitle%&quot; is currently open.</AMMESSAGEBOX>

</AMLOOP>

 

 

Sample Task 2 - Loop Windows and close all windows that contain the text Internet Explorer in its title.

 

<AMVARIABLE NAME="theTitle"></AMVARIABLE>

<AMLOOP TYPE="WINDOWS" RESULTVARIABLE="theTitle" INCLUDE="*Internet Explorer*" SORT="ascending">

     <AMWINDOWCLOSE WINDOWTITLE="%theTitle%" />

</AMLOOP>

 

↑ Top of Page