FolderItems Reference
Reference for the FolderItems object, which represents a collection of FolderItem objects.
Notation: P = property, M = method.
Table of Contents
1. Overview
It is used for the selected items, dropped items, history, and so on. Because it also behaves as an IDataObject, it can be passed as-is to drag and drop or the clipboard (for example api.OleSetClipboard(items) and api.DoDragDrop(items, ...)).
2. How to Obtain
| How to obtain | Returns |
|---|---|
FV.Items() / FV.SelectedItems() |
FolderItems (a SafeArray if the argument is true) |
FV.History |
FolderItems (history) |
te.FolderItems() |
An empty FolderItems (te.FolderItems(dataObject) creates one from an IDataObject) |
api.DataObject() |
An empty FolderItems (the result of api.OleGetClipboard() is also a FolderItems) |
| Event arguments | For example dataObj of OnDrop |
3. Members
| Name | Kind | Description |
|---|---|---|
Count / length |
P (read-only) | Number of items |
Item(index) |
M | Returns the FolderItem at index (0-based). If a second argument is passed, as in Item(index, newItem), the item at that position is replaced. Item(-1) returns the parent folder (the common parent, if it can be obtained). Returns empty if out of range |
AddItem(item) |
M | Appends an item to the end. item can be a FolderItem, a path string, or an IDList. A path string is converted to a FolderItem before being stored |
_NewEnum |
P | For enumeration (used by Enumerator) |
Index |
P | Current position (0-based). For history (FV.History), it is used to specify the current position |
Application |
P (read-only) | Shell.Application |
Parent |
P (read-only) | Always empty |
Data |
P | A value the script can hold freely |
4. Drag and Drop / Clipboard
| Name | Kind | Description |
|---|---|---|
dwEffect |
P | The drop effect value (DROPEFFECT_*). The result of the drop operation is stored here |
pdwEffect |
P (read-only) | A Memory (DWORD) that points to dwEffect. Pass it to api.DoDragDrop and similar functions |
hDrop(x, y, fNC) |
P | Returns an HDROP handle in CF_HDROP format. If x, y, and fNC are specified, it is returned with the drop position (pt / fNC of DROPFILES) set (empty if it cannot be obtained) |
GetData() |
M | Returns the text of the IDataObject (CF_UNICODETEXT, or CF_TEXT if that is not available). Empty if there is none |
SetData(text) |
M | Sets the text and treats this FolderItems as "data that has text" (UseText becomes true) |
UseText |
P | When true, text data is provided with priority |
5. Internal Behavior
- The internal format differs depending on where it was created. One obtained from a view (such as
FV.Items()) keeps the original enumeration result, one created withte.FolderItems()keeps an array of FolderItem, and one created from an IDataObject keeps an IDList. Writes throughAddItemorItem(index, newItem)are performed after converting internally to the array form. - When it comes from an IDataObject,
Item(index)rebuilds the ItemIDList and returns a FolderItem (combined with the parent folder).
6. Examples
// Get the paths of the selected items
const items = FV.SelectedItems();
for (let i = 0; i < items.Count; i++) {
const item = items.Item(i);
const path = item.Path;
const isFolder = item.IsFolder;
}
// Access it like a JavaScript array
for (let i = 0; i < items.length; i++) {
const item = items[i];
const path = item.Path;
const isFolder = item.IsFolder;
}
// Enumerate with for...in
for (const item in FV.Items()) { /* ... */ }
// Create your own FolderItems and select it in the view
const list = te.FolderItems();
list.AddItem("C:\\Windows\\notepad.exe");
list.AddItem("C:\\Windows\\explorer.exe");
FV.SelectItem(list, SVSI_SELECT | SVSI_DESELECTOTHERS);
// Copy to the clipboard
api.OleSetClipboard(list);