TreeView Reference

Reference for the folder tree (CTRL_TV) of Tablacus Explorer.

Notation: P = property (read with TV.Name, write with TV.Name = v), M = method (TV.Name(...)).

Table of Contents

  1. How to Obtain
  2. Basics and Display
  3. Root and Enumeration Settings
  4. Selection, Expansion, and Operations
  5. Position, Hit Testing, and Notifications
  6. Tree-Related Events (For Reference)
  7. Constants
  8. Examples
  9. Legacy Compatibility Members

1. How to Obtain

const TV = FV.TreeView;               // the tree of the view
const TV2 = te.Ctrl(CTRL_TV);         // the tree of the current view
const arTV = te.Ctrls(CTRL_TV, true); // all visible trees
const TV3 = te.CreateCtrl(CTRL_TV);   // create a new one

Important: When the tree is hidden (bit 2 of Align is not set), many members return no value and become S_FALSE (do nothing). The exceptions include Root / SetRoot / Align / Visible / Width / Style / EnumFlags / RootStyle / Data / Type / hwnd / Close. Check the display state with TV.Visible before use.

2. Basics and Display

Name Kind Description
Type P (read-only) Always returns CTRL_TV
Data P A value the script can hold freely
hwnd P (read-only) The handle of the window that contains the tree
hwndTree P (read-only) The handle of the tree view control itself (SysTreeView32)
FolderView P (read-only) The FolderView this tree belongs to. If there is no owning view, the current view is returned
Align P The placement (SB_TreeAlign). The tree is shown when bit 2 (value 2) is set. Assigning to it re-arranges and updates the display. In the old specification; using Visible is recommended
Visible P The display state. Assigning true sets Align = 3, and false sets Align = 1. OnVisibleChanged is called when it changes. Reading returns whether bit 2 is set
Width P The width of the tree (px)
Style P The style of the tree (NSTCS_*). Changing it recreates the tree
Close() M Closes the tree (sets Align to 0 and destroys it)
Focus() M Moves focus to the tree (hwndTree)
Refresh() M Schedules a reset of the root after about 100 ms and reloads

Width / Style / EnumFlags / RootStyle can be read and written even when the tree is hidden. Changes to Width and Style are also saved as the default for all trees (those created afterwards). When Style / EnumFlags / RootStyle is changed, the tree is closed and recreated.

3. Root and Enumeration Settings

Name Kind Description
Root P The root setting (a string). Reading returns the current root (a string), and assigning is equivalent to SetRoot
SetRoot(root [, enumFlags [, rootStyle]]) M Sets the root of the tree. root is a path, a FolderItem, a string that represents a root, and so on. If you pass enumFlags and rootStyle, the enumeration flags and the root display style are also changed. If omitted, they return to the defaults (the defaults of FV)
EnumFlags P The enumeration flags (SHCONTF_*). Specifies things such as showing or hiding hidden files
RootStyle P The display style of the root (NSTCRS_*) 
TV.SetRoot("C:\\Users", SHCONTF_FOLDERS, NSTCRS_VISIBLE);

4. Selection, Expansion, and Operations

Name Kind Description
SelectedItem P (read-only) The selected item (a FolderItem). Empty if there is none
SelectedItems() M Returns the selected items as a FolderItems
Expand(item, bExpand) M Selects the item and, if bExpand is non-zero, expands it. The processing runs after about 100 ms. Empty items, the root, and search folders are ignored. For items under "Internet", when te.ShowInternet is false the operation goes back up to the parent 
TV.Expand(FV.FolderItem, 1);   // select and expand the current folder

5. Position, Hit Testing, and Notifications

Name Kind Description
HitTest(pt [, flags]) M Returns the item at the screen coordinates pt. flags is TVHT_* (TVHT_ONITEM if omitted, and TVHT_ONITEM \| TVHT_ONITEMRIGHT if NSTCS_FULLROWSELECT is enabled). If flags is omitted, a FolderItem is returned; if it is specified, the item handle (HTREEITEM) is returned. 0 if there is none
GetItemRect(item, rc) M Writes the rectangle of the item into rc (a RECT Memory; api.Memory("RECT")). Success is S_OK (0)
Notify(event, item, ...) M Passes a shell change notification (SHCNE_*) to the tree. If event is an addition type (SHCNE_MKDIR / SHCNE_MEDIAINSERTED / SHCNE_DRIVEADD / SHCNE_NETSHARE), the new item is shown if the parent is already expanded. For removal types (SHCNE_RMDIR / SHCNE_DRIVEREMOVED / SHCNE_MEDIAREMOVED / SHCNE_NETUNSHARE / SHCNE_RENAMEFOLDER and others), the corresponding item is removed. At least 3 arguments are required (event, item1, ...)

te.OnItemClick is also called when the tree is clicked, and in the implementation its arguments are, in order, (Ctrl=TreeView, Item=FolderItem, HitTest, Flags) (HitTest is NSTCEHITTEST, and Flags is NSTCSTYLE). If a return value is returned, that value (an HRESULT) is used. OnSelectionChanged and OnVisibleChanged are also called with the TreeView as an argument.

7. Constants

Defined in consts.js.

NSTCS_* (Style) NSTCS_HASEXPANDOS = 1 / NSTCS_HASLINES = 2 / NSTCS_SINGLECLICKEXPAND = 4 / NSTCS_FULLROWSELECT = 8 / NSTCS_SPRINGEXPAND = 0x10 / NSTCS_HORIZONTALSCROLL = 0x20 / NSTCS_ROOTHASEXPANDO = 0x40 / NSTCS_SHOWSELECTIONALWAYS = 0x80 / NSTCS_NOINFOTIP = 0x200 / NSTCS_EVENHEIGHT = 0x400 / NSTCS_NOREPLACEOPEN = 0x800 / NSTCS_DISABLEDRAGDROP = 0x1000 / NSTCS_NOORDERSTREAM = 0x2000 / NSTCS_RICHTOOLTIP = 0x4000 / NSTCS_BORDER = 0x8000 / NSTCS_NOEDITLABELS = 0x10000 / NSTCS_TABSTOP = 0x20000 / NSTCS_FAVORITESMODE = 0x80000 / NSTCS_AUTOHSCROLL = 0x100000 / NSTCS_FADEINOUTEXPANDOS = 0x200000 / NSTCS_EMPTYTEXT = 0x400000 / NSTCS_CHECKBOXES = 0x800000 / NSTCS_PARTIALCHECKBOXES = 0x1000000 / NSTCS_EXCLUSIONCHECKBOXES = 0x2000000 / NSTCS_DIMMEDCHECKBOXES = 0x4000000 / NSTCS_NOINDENTCHECKS = 0x8000000 / NSTCS_ALLOWJUNCTIONS = 0x10000000 / NSTCS_SHOWTABSBUTTON = 0x20000000 / NSTCS_SHOWDELETEBUTTON = 0x40000000 / NSTCS_SHOWREFRESHBUTTON = 0x80000000

SHCONTF_* (EnumFlags) SHCONTF_CHECKING_FOR_CHILDREN = 0x10 / SHCONTF_FOLDERS = 0x20 / SHCONTF_NONFOLDERS = 0x40 / SHCONTF_INCLUDEHIDDEN = 0x80 / SHCONTF_INIT_ON_FIRST_NEXT = 0x100 / SHCONTF_NETPRINTERSRCH = 0x200 / SHCONTF_SHAREABLE = 0x400 / SHCONTF_STORAGE = 0x800 / SHCONTF_NAVIGATION_ENUM = 0x1000 / SHCONTF_FASTITEMS = 0x2000 / SHCONTF_FLATLIST = 0x4000 / SHCONTF_ENABLE_ASYNC = 0x8000 / SHCONTF_INCLUDESUPERHIDDEN = 0x10000

NSTCRS_* (RootStyle) NSTCRS_VISIBLE = 0 / NSTCRS_HIDDEN = 1 / NSTCRS_EXPANDED = 2

TVHT_* (HitTest) TVHT_NOWHERE = 1 / TVHT_ONITEMICON = 2 / TVHT_ONITEMLABEL = 4 / TVHT_ONITEMINDENT = 8 and others (see consts.js)

8. Examples

const FV = te.Ctrl(CTRL_FV);
const TV = FV.TreeView;

// Show / hide
TV.Visible = true;
TV.Width = 250;

// Set the root
TV.SetRoot("C:\\", SHCONTF_FOLDERS | SHCONTF_INCLUDEHIDDEN, NSTCRS_VISIBLE);

// Expand and select the current folder
TV.Expand(FV.FolderItem, 1);

// Get the item under the mouse position (a FolderItem is returned when flags is omitted)
const pt = api.Memory("POINT");
api.GetCursorPos(pt);
const item = TV.HitTest(pt);
if (item) {
    FV.Navigate(item, SBSP_SAMEBROWSER);
}

9. Legacy Compatibility Members

In the current build (which uses NameSpaceTreeControl), the following members have no dedicated handling in the implementation, and calling them returns no value (a "member not found" error may occur). The names come from the IShellNameSpace control used in old builds for Windows 2000 / XP, and their behavior in the old builds needs verification. Do not use them in new scripts.

CountViewTypes Depth EnumOptions Export Flags Import Mode ResetSort SetViewType Synchronize TVFlags Columns