For Each...Next Statement

Language Items List

Definition:

Repeats the execution of a statement block for each item in a collection. A collection is defined as the set of objects in a Group object, as objects embedded in a host object, or as the set of objects copied from a prototype object. Which collection to iterate is specified by the use of the “In,” “EmbeddedIn,” or the “CopiedFrom” keywords.

Syntax:

For Each element {In | EmbeddedIn | CopiedFrom} object
[statementblock]
[Exit For]
[statementblock]
Next [element]

---

Syntax Description

---

For Each Marks the beginning of a For Each...Next loop control structure. Must always be the very first part of the structure.

element An object reference variable used to hold the value of each element of the collection being iterated.

In Indicates that the For Each loop will execute once for each member of the group referred to by ‘object’.

EmbeddedIn Indicates that the For Each loop will execute once for each embedded object in the object referred to by ‘object’.

CopiedFrom Indicates that the For Each loop will execute once for each object copied from the object referred to by ‘object’.

statementblock One or more program lines placed between For and Next. These lines are executed the specified number of times.

Exit For Provides an alternative way to exit the For...Next control structure. It can be used only within a For...Next control structure. You can place any number of Exit For statements in the For...Next loop. Exit For immediately transfers control to the statement following the Next keyword, thus is often used with the evaluation of some condition such as If...Then.

Next Marks the bottom of a statement block for a For...Next loop and causes element to be advanced to the next item in the collection.

To begin a For Each...Next loop element is initialized to the first item in the collection. If there are no items in the specified collection, the For Each...Next loop will not execute the statement block. The loop will continue to execute the statement block for each item in the collection.

To iterate different kinds of collections, different keywords are used with the loop:

“ In” - Used to iterate each member of a kind of Group object. For example:

Dim item As Object
For Each item In MyGroup
Debug.Print “Group Object: “;item
Next

“ EmbeddedIn” - Used to iterate each embedded object of any other object. For example:

Dim item As Object
For Each item EmbeddedIn Form1
Debug.Print “Embedded Object: “; item
Next

“ CopiedFrom” - Used to iterate each copy of a given type of object. For example:

Dim item As Object
For Each item CopiedFrom Form
Debug.Print “Copied Object: “; item
Next

When iterating the collection of objects, only objects that can be treated as the loop variable (“element”) will be assigned to element, and have the statement block run for them. Each item of the collection that does not inherit from the loop variable will be silently skipped. For example, to iterate each control on a form, and ignore non-Controls, enter the following:

Dim control As Control
For Each control EmbeddedIn Form1
Debug.Print “Control: “; control
Next

If there are any objects embedded in Form1 that do not inherit from Control, they will simply be skipped during the iteration.

Changing the value of element has no effect inside the loop, therefore this technique (which can be used with regular For...Next loops) can't be used with For Each...Next loops.

See Also:

For...Next Statement