Action Statement

Perform actions on first-level children of a specified object.

for each child STRING_VARIABLE of OBJECT_NAME loop [LOOP_NAME]

[ACTION_STATEMENT] ...

[ leave loop [LOOP_NAME] ]

[ACTION_STATEMENT] ...

end loop [LOOP_NAME]

STRING_VARIABLE

On each iteration, STRING_VARIABLE is set to the name of the current child of object OBJECT_NAME, with ancestry.

of OBJECT_NAME

The identifier for an object

LOOP_NAME

The identifier for the loop. This name might identify the loop in which the leave loop is specified, or it might identify an outer loop. If you specify an outer loop, ESL leaves the specified outer loop and all inner loops. If you do not specify a name in the leave loop statement, ESL exits from the innermost loop that contains the leave loop statement, even if the innermost loop has a name.

ACTION_STATEMENT

An action statement.

Description

Use this statement to perform a list of actions on all direct (first-level) children of a specified object, without having to search for those child objects.

Use the for each child loop statement to loop through all the direct children of a specified object. STRING_VARIABLE is used to access the name of the current child. Note that the name of the child contained in STRING_VARIABLE includes full ancestry.

If the loop finishes normally, then STRING_VARIABLE is set to an empty string. If a leave loop statement is executed, then the last assigned value to STRING_VARIABLE continues to be its value.

You can nest a for each child loop within any other type of loop, including another for each child loop. It is possible to process all children and grandchildren of a given object by coding a recursive ESL subroutine that executes a for each child loop.

Note that if a loop deletes the next child to be processed (or the parent of all the children), the loop will halt. You can delete the current child without affecting the loop, but not the next.

You can include a for each child loop statement within a response definition, action routine definition, ESL subroutine, conditional action statement, or other loops, to any number of levels. You can specify blocks in loops, and vice versa. If you specify a block within a loop, execution of a leave loop statement causes all blocks contained in the loop to become inactive.

The leave loop action statement can be one of the action statements in a for each child loop statement. Upon execution, ESL will exit from the loop, and will continue execution at the statement following the end loop keywords. If you specify a leave loop statement, you must specify it within the definition of the loop itself. You cannot specify it in an action routine that is called from inside the loop.

The identifier for the loop must be unique within the ESL program; there must be nothing else in the program with that name. Specifying a name in the for each child loop statement means that you must include a name in the end loop statement that exactly matches the name specified in the for each child loop statement.

If the program is compiled with External Strings, then any string literals used in this statement will be externalized.

Example

 

# In the following example, the subroutine ValidateObject

# is called for each dialog control object in the dialog

# box Form5_DB.

 

for each child DialogControl of Form5_DB loop

 call ValidateObject (DialogControl)

end loop

 

# This recursive subroutine visits all children and

# grandchildren of the object 'Parent'.

 

subroutine VisitChildren(string:Parent) is

 string Child

 for each child Child of Parent loop

         send "Visited object: [" Child "]\n" to errorlog

         call VisitChildren(Child)

 end loop

...

 

# Enumerate all existing objects in this program

copy "desktop" to ObjName

call VisitChildren(ObjName)