FolderView (ShellBrowser) Reference
Reference for the file view of Tablacus Explorer (the ShellBrowser object that can be obtained with te.Ctrl(CTRL_FV) and similar calls).
- From here on, this object is written as
FV. - Related: te Reference, api Reference
Notation: P = property (read with
FV.Name, write withFV.Name = v), M = method (FV.Name(...)). Members whose implementation supports both properties and methods, such asColumns/SortColumn/CurrentViewMode/FilterView, are written as "P/M".
Table of Contents
- How to Obtain
- Navigation
- View Mode and Settings
- Getting and Selecting Items
- Columns, Sorting, Grouping, and Filtering
- Windows, Tabs, and Related Objects
- Dynamically Adding and Removing Items (Search Result Views, etc.)
- Customization Properties
- Notification and Internal Methods
- Constants
- Deprecated / Internal
1. How to Obtain
const FV = te.Ctrl(CTRL_FV); // the view of the current tab
const arFV = te.Ctrls(CTRL_FV, true); // all visible views
const FV2 = te.CtrlFromWindow(hwnd); // from an hwnd
const FV3 = te.CtrlFromPoint(pt); // from coordinates
It is also passed as an argument of each event (such as OnBeforeNavigate).
2. Navigation
| Name | Kind | Description |
|---|---|---|
Navigate(Path [, wFlags]) |
M | Navigates to the specified path / FolderItem / FolderItems. wFlags is SBSP_* (see below). If the destination became a different view, that view is returned; otherwise it returns itself |
Navigate2(Path [, wFlags [, Type, ViewMode, FolderFlags, Options, ViewFlags, IconSize, TreeAlign, TreeWidth, TreeFlags, EnumFlags, RootStyle, Root]]) |
M | Navigates while specifying display settings. The 3rd and later arguments are given in the SB_* order (see the table below; if TreeAlign is 0, processing stops there, and the rest use defaults). Returns the view (FV) after navigation |
History |
P | Returns the history as a FolderItems (the current position is Index, and the newest is first). History = Path behaves the same as Navigate |
FolderItem |
P (read-only) | The folder currently displayed (a FolderItem) |
Refresh([n]) |
M | Reloads. If n is non-zero and the view is hidden, it runs when the view is shown |
NavigateComplete() |
M | Clears the state of waiting for navigation to complete and, if needed, shows the view window (for internal processing) |
Focus() |
M | Activates this view and switches the tab |
Close() |
M | Closes this tab. Returns the result as a boolean (the conditions under which it cannot be closed need verification). If the tab control is not locked, the layout is updated |
Suspend([mode]) |
M | Destroys the view and frees memory (the tab stays). 0/omitted = normal, 1 = also close the tree, 2 = put it in the "unavailable" state, 4 = lightweight (m_nUnload=8) |
Argument order of Navigate2 (3rd argument onward):
| Order | Argument | Content |
|---|---|---|
| 1 | Type |
CTRL_SB (1) or CTRL_EB (2). Anything else is treated as CTRL_SB |
| 2 | ViewMode |
FVM_* |
| 3 | FolderFlags |
FWF_* |
| 4 | Options |
ExplorerBrowser options (EBO_*) |
| 5 | ViewFlags |
View flags (specific to Tablacus) |
| 6 | IconSize |
Icon size |
| 7 | TreeAlign |
Position of the tree (0 disables it) |
| 8 | TreeWidth |
Width of the tree |
| 9 | TreeFlags |
Flags of the tree |
| 10 | EnumFlags |
Enumeration flags (SHCONTF_*) |
| 11 | RootStyle |
How the root is displayed |
| 12 | Root |
Root of the tree |
FV.Navigate("C:\\Windows", SBSP_SAMEBROWSER);
FV.Navigate(null, SBSP_PARENT | SBSP_SAMEBROWSER); // up
FV.Navigate(null, SBSP_NAVIGATEBACK | SBSP_SAMEBROWSER); // back
const newFV = FV.Navigate("C:\\", SBSP_NEWBROWSER); // new tab
3. View Mode and Settings
| Name | Kind | Description |
|---|---|---|
Type |
P | CTRL_SB (1) or CTRL_EB (2). Changing it makes the layout be judged again (other values are ignored) |
CurrentViewMode |
P/M | The view mode (FVM_*). FV.CurrentViewMode = FVM_DETAILS |
SetViewMode(mode [, iconSize]) |
M | Sets the view mode. If a second argument is passed, the icon size is also set. Returns the current view mode |
IconSize |
P | The icon size (px). Valid when the view has already been created. When changed, it is reflected in the shell view |
FolderFlags |
P | FWF_* (folder display flags). If any bit other than FWF_NOENUMREFRESH / FWF_USESEARCHFOLDER / FWF_SNAPTOGRID changes, it is reflected in the view |
Options |
P | ExplorerBrowser options (EBO_*). With CTRL_EB, the setting is reflected directly |
ViewFlags |
P | Tablacus-specific view flags (only stored; the meaning depends on the script's definition) |
SizeFormat |
P | The display format of file sizes. When changed, the list is redrawn |
Title |
P | The title of the tab (a string). When read, it is returned with the & escapes removed. Nothing is returned for a view that has no tab |
Index |
P | The position within the tab control (0-based). Assigning to it moves the tab |
Id |
P (read-only) | The identification number of the view (corresponds to the id of te.Ctrl(CTRL_FV, id)) |
SessionId |
P (read-only) | The session ID of the current folder (changes with each navigation). For consistency checks in AddItem/AddItems |
Parent |
P (read-only) | The parent object (normally the TabCtrl it belongs to) |
Data |
P | A value the script can hold freely |
4. Getting and Selecting Items
| Name | Kind | Description |
|---|---|---|
Items([flags [, bArray]]) |
M | Returns the items of the view as a FolderItems. flags is SVGIO_* (SVGIO_ALLVIEW \| SVGIO_FLAG_VIEWORDER if omitted). If bArray is true, a SafeArray is returned |
SelectedItems([bArray]) |
M | Returns the selected items as a FolderItems. A SafeArray if bArray is true |
ItemCount([flags]) |
M | Returns the number of items. SVGIO_ALLVIEW if flags is omitted. With SVGIO_SELECTION, the number of selected items |
Item(index) |
M | Returns the item at index (0-based, in view display order) as a FolderItem |
FocusedItem |
P (read-only) | The focused item (a FolderItem) |
GetFocusedItem() |
M | Returns the index of the focused item (an integer) |
SelectItem(item, flags) |
M | Selects an item. item is a FolderItem, a path, an index (a number), or a FolderItems. flags is SVSI_*. If you pass a FolderItems, all of them are selected, and SVSI_FOCUSED and similar flags are applied only to the first one |
GetItemPosition(item, pt) |
M | Writes the position of the item into pt (a POINT Memory). Returns an HRESULT |
SelectAndPositionItem(item, flags, pt) |
M | Selects an item and places it at the coordinates pt (for icon view). Returns an HRESULT |
GetItemRect(item, rc [, type]) |
M | Writes the rectangle of the item into rc (a RECT Memory) (type is LVIR_*, LVIR_BOUNDS if omitted). Valid only for views that have a list view. Returns an HRESULT |
HitTest(pt [, flags]) |
M | Returns the index of the item at the screen coordinates pt (a negative value if none). LVHT_ONITEM if flags is omitted. Only when flags is omitted, the item found is returned as a FolderItem |
ViewMenu([flags]) |
M | Returns the context menu of the view (a ContextMenu object). If flags is omitted, it is SVGIO_BACKGROUND (the background menu) |
TranslateAccelerator(hwnd, msg, wParam, lParam) |
M | Asks the shell view to handle accelerators. Returns an HRESULT |
const items = FV.SelectedItems();
for (let i = 0; i < items.length; ++i) {
const path = items[i].Path;
}
for (let i = 0; i < items.Count; ++i) {
const path = items.Item(i).Path;
}
FV.SelectItem(FV.Item(0), SVSI_SELECT | SVSI_FOCUSED | SVSI_ENSUREVISIBLE | SVSI_DESELECTOTHERS);
5. Columns, Sorting, Grouping, and Filtering
| Name | Kind | Description |
|---|---|---|
Columns |
P/M | Returns the current columns as a string (if you use it as GetColumns(format), you can specify the format). Assigning a string sets the column configuration. It returns nothing while the shell view (DefView) has not been created |
GetColumns([format]) |
M | The same as Columns (for getting). format specifies the output format |
MapColumnToSCID(index, format) |
M | Returns the property name that corresponds to a column index |
SortColumn |
P/M | Returns the sort column as a string (if you use it as GetSortColumn(format), you can specify the format). Assigning a string sorts |
GetSortColumn([format]) |
M | The same as SortColumn (for getting) |
GroupBy |
P | Gets/sets the grouping column as a string |
AltSortColumn |
P | The alternative sort column (a string). It is reapplied after file enumeration completes |
FilterView |
P/M | The filter string. Assigning as a property sets the filter string and calls OnFilterChanged. Calling as a method, FV.FilterView("text") (or FV.Search("text")), runs a search filter (if OnFilterView is registered, it is called first) |
Search(text) |
M | The method version of FilterView (runs a search) |
6. Windows, Tabs, and Related Objects
| Name | Kind | Description |
|---|---|---|
hwnd |
P (read-only) | The window handle of the whole view (pass it to api functions) |
hwndView |
P (read-only) | The handle of the shell view (DefView) |
hwndList |
P (read-only) | The handle of the list view (SysListView32) |
hwndAlt |
P | The handle of an alternative window. When set, it is placed in the view area |
TreeView |
P (read-only) | The tree of this view (CTRL_TV) |
ShellFolderView |
P (read-only) | The dispatch of the shell folder view (IShellFolderView) |
Droptarget |
P (read-only) | The drop target for the current folder (a DropTarget object) |
7. Dynamically Adding and Removing Items (Search Result Views, etc.)
For views, such as a search result folder, whose items are controlled programmatically.
| Name | Kind | Description |
|---|---|---|
AddItem(item [, sessionId]) |
M | Adds one item. If you specify sessionId, it fails (E_ACCESSDENIED) when it does not match the current SessionId |
AddItems(items [, bDeleted [, OnCompleted]]) |
M | Adds the items of an array / FolderItems on a separate thread. If bDeleted is true, they are treated as removals rather than additions. If the 3rd argument is a function object, it is called on completion; if it is a boolean, it decides whether to run NavigateComplete. A processing message is shown in the status bar |
RemoveItem(item) |
M | Removes an item (in search result views and the like). Returns an HRESULT (on S_OK, the status is updated after 500 ms) |
RemoveAll() |
M | Removes all items. The return value is a result code |
8. Customization Properties
You assign a JavaScript object or function to replace the behavior per view.
| Name | Description |
|---|---|
TotalFileSize |
An object used as a cache of folder sizes. The key is the path and the value is the total size. It is replaced with a new empty object on each navigation |
ColumnsReplace |
An object keyed by column name that replaces what a column displays. It takes priority over te.ColumnsReplace |
OnIncludeObject |
A callback that filters items. It is cleared when FilterView is set |
AltSelectedItems |
A FolderItems treated as a substitute for SelectedItems. When it is set, ItemCount(SVGIO_SELECTION) returns its Count |
9. Notification and Internal Methods
| Name | Description |
|---|---|
Notify(event, item1 [, item2 [, bTotalFileSize]]) |
Passes a shell change notification (SHCNE_*) to the view. If event is a rename (SHCNE_RENAMEITEM/SHCNE_RENAMEFOLDER), item2 is also used. If bTotalFileSize is true, the folder size of the item concerned is recalculated; if false or omitted, the TotalFileSize cache is discarded and the view is redrawn |
10. Constants
The ones defined in consts.js are listed.
SBSP_* (flags of Navigate)
SBSP_SAMEBROWSER = 1 / SBSP_NEWBROWSER = 2 / SBSP_OPENMODE = 0x10 / SBSP_EXPLOREMODE = 0x20 / SBSP_RELATIVE = 0x1000 / SBSP_PARENT = 0x2000 / SBSP_NAVIGATEBACK = 0x4000 / SBSP_NAVIGATEFORWARD = 0x8000 / SBSP_ACTIVATE_NOFOCUS = 0x80000 / SBSP_WRITENOHISTORY = 0x08000000
FVM_* (view modes)
FVM_AUTO = -1 / FVM_ICON = 1 / FVM_SMALLICON = 2 / FVM_LIST = 3 / FVM_DETAILS = 4 / FVM_THUMBNAIL = 5 / FVM_TILE = 6 / FVM_THUMBSTRIP = 7
SVSI_* (flags of SelectItem)
SVSI_DESELECT = 0 / SVSI_SELECT = 1 / SVSI_EDIT = 3 / SVSI_DESELECTOTHERS = 4 / SVSI_ENSUREVISIBLE = 8 / SVSI_FOCUSED = 0x10 / SVSI_TRANSLATEPT = 0x20 / SVSI_SELECTIONMARK = 0x40 / SVSI_POSITIONITEM = 0x80 / SVSI_CHECK = 0x100 / SVSI_CHECK2 = 0x200 / SVSI_KEYBOARDSELECT = 0x401 / SVSI_NOTAKEFOCUS = 0x40000000 / SVSI_NOSTATECHANGE = 0x80000000
SVGIO_* (Items / ItemCount / ViewMenu)
SVGIO_BACKGROUND = 0 / SVGIO_SELECTION = 1 / SVGIO_ALLVIEW = 2 / SVGIO_CHECKED = 3 / SVGIO_TYPE_MASK = 0xf / SVGIO_FLAG_VIEWORDER = 0x80000000
The other FWF_*, EBO_*, LVHT_*, LVIR_*, and SHCNE_* constants are also in consts.js.
Values of Type: CTRL_SB = 1 (ShellBrowser) / CTRL_EB = 2 (ExplorerBrowser). te.Ctrl(CTRL_FV) returns either kind of view.
11. Deprecated / Internal
| Name | Status |
|---|---|
NameFormat |
Deprecated. Does nothing |
VirtualName |
Deprecated (SB_VirtualName) |
Searches / ViewProperty |
Commented out in the code, or only in USE_VIEWPROPERTY builds. Normally not usable |