Enum Reference

Reference for the Enum object, which enumerates COM collections (such as FolderItems, the Drives of Scripting.FileSystemObject, and TabCtrl) one element at a time. It corresponds to JScript's Enumerator.

Related: te Reference, api Reference (api.CreateObject), FolderItems Reference, TabCtrl Reference

Notation: M = method. Member names are matched case-insensitively.

How to Obtain
Methods
What Can Be Enumerated
Notes
Examples

1. How to Obtain

api.CreateObject("Enum", collection)

const e = api.CreateObject("Enum", fso.Drives);

Pass the collection (object) to enumerate as the second argument. If it is omitted, nothing can be enumerated (the object is still created, but atEnd() is immediately true).
At creation time, the first element is fetched in advance. You do not need to call moveFirst().
There is no te-side entry point such as te.Enum.

2. Methods

Name	Return value	Description
`atEnd()`	bool	`true` if the enumeration has finished (or the object cannot be enumerated)
`item()`	value	Returns the current element. Do not call it while `atEnd()` is true (the value is unspecified)
`moveNext()`	none	Advances to the next element
`moveFirst()`	none	Returns to the beginning and fetches the first element

A typical loop looks like this (the same as with Enumerator).

for (const e = api.CreateObject("Enum", collection); !e.atEnd(); e.moveNext()) {
    const item = e.item();
}

3. What Can Be Enumerated

The object you pass is checked in the following order, and the first condition that matches is used.

Object passed	What is enumerated
`IShellWindows` (`Windows()` of `Shell.Application`)	The open shell windows
`FolderItems` (`FV.Items()`, `FV.SelectedItems()`, `te.FolderItems()`, etc.)	`FolderItem`
An object that has `_NewEnum` (`DISPID_NEWENUM`)	The elements returned by its enumerator (many COM collections other than `fso.Drives`, `TabCtrl`, `Memory`, and `WICBitmap`)
Any other `IDispatchEx`	Returns the member names (property names) one by one as strings (like `for…in`)
Anything else	Nothing is enumerated; `atEnd()` is `true` from the start

For an object that provides an enumerator, moveFirst() calls Reset() on the underlying enumerator. When member names are being returned, it starts counting again from the beginning.
When enumerating member names, the behavior for an array (Array) passed in (for example, whether the indexes are returned as strings) depends on the script engine, so it needs verification.

4. Notes

Elements are fetched each time you enumerate, so modifying the collection during enumeration gives unspecified results.
atEnd() is determined by whether the previous element could be fetched. If you repeat only atEnd() without fetching an element, the loop never ends (always call moveNext()).
In asynchronous scripts (the WebView2 side, such as ui.js), every method call, including CreateObject, requires await.

5. Examples

// Enumerate drives (Scripting.FileSystemObject)
const fso = api.CreateObject("Scripting.FileSystemObject");
for (const e = api.CreateObject("Enum", fso.Drives); !e.atEnd(); e.moveNext()) {
    const drive = e.item();
    // drive.DriveLetter, drive.TotalSize ...
}

// Enumerate FolderItems
const Items = FV.SelectedItems();
for (const e = api.CreateObject("Enum", Items); !e.atEnd(); e.moveNext()) {
    const path = e.item().Path;
}

// Enumerate property names
const o = api.CreateObject("Object");
o.a = 1;
o.b = 2;
for (const e = api.CreateObject("Enum", o); !e.atEnd(); e.moveNext()) {
    const key = e.item();     // "a", "b"
}

// Asynchronous script (WebView2 side)
for (let list = await api.CreateObject("Enum", collection); !await list.atEnd(); await list.moveNext()) {
    const item = await list.item();
}

To enumerate a FolderItems, for...in or index access is usually simpler (FolderItems can be enumerated with Count and Item(i), and TabCtrl can also be enumerated with for...in). Use Enum for COM collections that provide only _NewEnum, and for enumerating member names.