TreeView

Table of Contents

• Introduction and Simple Example
• Options and Styles
• Built-in Methods:
  • Add/modify/delete items
  • Getting data out of a TreeView
  • Setting Icons
• Events
• Remarks
• Longer Example

Introduction and Simple Example

A Tree-View displays a hierarchy of items by indenting child items beneath their parents. The most common example is Explorer's tree of drives and folders.

The syntax for creating a TreeView is:

TV := Gui.Add("TreeView", Options)

Here is a working script that creates and displays a simple hierarchy of items:

Gui := GuiCreate()
TV := Gui.Add("TreeView")
P1 := TV.Add("First parent")
P1C1 := TV.Add("Parent 1's first child", P1)  ; Specify P1 to be this item's parent.
P2 := TV.Add("Second parent")
P2C1 := TV.Add("Parent 2's first child", P2)
P2C2 := TV.Add("Parent 2's second child", P2)
P2C2C1 := TV.Add("Child 2's first child", P2C2)

Gui.Show  ; Show the window and its TreeView.

Options and Styles for the Options parameter

Background: Specify the word Background followed immediately by a color name (see color chart) or RGB value (the 0x prefix is optional). Examples: BackgroundSilver, BackgroundFFDD99. If this option is not present, the TreeView initially defaults to the system's default background color. Specifying BackgroundDefault or -Background applies the system's default background color (usually white). For example, a TreeView can be restored to the default color via TV.Opt("+BackgroundDefault").

Buttons: Specify -Buttons (minus Buttons) to avoid displaying a plus or minus button to the left of each item that has children.

C: Text color. Specify the letter C followed immediately by a color name (see color chart) or RGB value (the 0x prefix is optional). Examples: cRed, cFF2211, c0xFF2211, cDefault.

Checked: Provides a checkbox at the left side of each item. When adding an item, specify the word Check in its options to have the box to start off checked instead of unchecked. The user may either click the checkbox or press the spacebar to check or uncheck an item. To discover which items in a TreeView are currently checked, call TV.GetNext or TV.Get.

HScroll: Specify -HScroll (minus HScroll) to disable horizontal scrolling in the control (in addition, the control will not display any horizontal scroll bar).

ImageList: This is the means by which icons are added to a TreeView. Specify the word ImageList followed immediately by the ImageListID returned from a previous call to IL_Create. This option has an effect only when creating a TreeView (however, TV.SetImageList does not have this limitation). Here is a working example:

Gui := GuiCreate()
ImageListID := IL_Create(10)  ; Create an ImageList with initial capacity for 10 icons.
Loop 10  ; Load the ImageList with some standard system icons.
    IL_Add(ImageListID, "shell32.dll", A_Index)
TV := Gui.Add("TreeView", "ImageList" . ImageListID)
TV.Add("Name of Item", 0, "Icon4")  ; Add an item to the TreeView and give it a folder icon.
Gui.Show

Lines: Specify -Lines (minus Lines) to avoid displaying a network of lines connecting parent items to their children. However, removing these lines also prevents the plus/minus buttons from being shown for top-level items.

ReadOnly: Specify -ReadOnly (minus ReadOnly) to allow editing of the text/name of each item. To edit an item, select it then press the F2 key. Alternatively, you can click an item once to select it, wait at least half a second, then click the same item again to edit it. After being edited, an item can be alphabetically repositioned among its siblings via the following example:

TV := Gui.Add("TreeView", "-ReadOnly")
TV.OnEvent("ItemEdit", "MyTree_Edit")  ; Call MyTree_Edit whenever a user has finished editing an item.
; ...
MyTree_Edit(TV, Item)
{
    TV.Modify(TV.GetParent(Item), "Sort")  ; This works even if the item has no parent.
}

R: Rows of height (upon creation). Specify the letter R followed immediately by the number of rows for which to make room inside the control. For example, R10 would make the control 10 items tall.

WantF2: Specify -WantF2 (minus WantF2) to prevent an F2 keystroke from editing the currently selected item. This setting is ignored unless -ReadOnly is also in effect.

(Unnamed numeric styles): Since styles other than the above are rarely used, they do not have names. See the TreeView styles table for a list.

Built-in Methods for TreeViews

Additionally to the default methods/properties of a GUI control, the following methods can be specified for a TreeView. If the associated GuiControl object does not exist or does not belongs to a TreeView, the TreeView methods throw an exception.

Add, Modify, and Delete Items

UniqueID := TV.Add(Name, ParentItemID, Options)

CurrentItemID := TV.Modify(ItemID , Options, NewName)

TV.Delete(ItemID)

Getting Data Out of a TreeView

SelectedItemID := TV.GetSelection()

CountNumber := TV.GetCount()

ParentItemID := TV.GetParent(ItemID)

TopChildID := TV.GetChild(ParentItemID)

PrevItemID := TV.GetPrev(ItemID)

NextItemID := TV.GetNext(ItemID := 0, ItemType := "")

ItemID := 0  ; Causes the loop's first iteration to start the search at the top of the tree.
Loop
{
    ItemID := TV.GetNext(ItemID, "Full")  ; Replace "Full" with "Checked" to find all checkmarked items.
    if not ItemID  ; No more items in tree.
        break
    ItemText := TV.GetText(ItemID)
    MsgBox('The next Item is ' ItemID ', whose text is "' ItemText '".')
}

RetrievedText := TV.GetText(ItemID)

CurrentItemID := TV.Get(ItemID, Attribute)

Setting Icons

PrevImageListID := TV.SetImageList(ImageListID , IconType)

Events

The following events can be detected by calling OnEvent to register a callback function or method:

Additional (rarely-used) notifications can be detected by using OnNotify. These notifications are documented at MSDN. MSDN does not show the numeric value of each notification code; those can be found in the Windows SDK or by searching the Internet.

Remarks

To detect when the user has pressed Enter while a TreeView has focus, use a default button (which can be hidden if desired). For example:

Gui.Add("Button", "Hidden Default", "OK").OnEvent("Click", "ButtonOK")
...
ButtonOK() {
  global
  if Gui.FocusedCtrl != TV
    return
  MsgBox("Enter was pressed. The selected item ID is " TV.GetSelection)
}

In addition to navigating from item to item with the keyboard, the user may also perform incremental search by typing the first few characters of an item's name. This causes the selection to jump to the nearest matching item.

Although any length of text can be stored in each item of a TreeView, only the first 260 characters are displayed.

Although the theoretical maximum number of items in a TreeView is 65536, item-adding performance will noticeably decrease long before then. This can be alleviated somewhat by using the redraw tip described in TV.Add.

Unlike ListViews, a TreeView's ImageList is not automatically destroyed when the TreeView is destroyed. Therefore, a script should call IL_Destroy after destroying a TreeView's window if the ImageList will not be used for anything else. However, this is not necessary if the script will soon be exiting because all ImageLists are automatically destroyed at that time.

A script may create more than one TreeView per window.

To perform actions such as resizing, hiding, or changing the font of a TreeView, see GuiControl object.

Tree View eXtension (TVX) extends TreeViews to support moving, inserting and deleting. It is demonstrated at www.autohotkey.com/forum/topic19021.html

Related

ListView, Other Control Types, GuiCreate, ContextMenu event, Gui object, GuiControl object, TreeView styles table

Example

; The following is a working script that is more elaborate than the one near the top of this page.
; It creates and displays a TreeView containing all folders of the user's document folder. When the
; user selects a folder, its contents are shown in a ListView to the right (like Windows Explorer).
; In addition, a StatusBar control shows information about the currently selected folder.

; The following folder will be the root folder for the TreeView. Note that loading might take a long
; time if an entire drive such as C:\ is specified:
TreeRoot := A_MyDocuments
TreeViewWidth := 280
ListViewWidth := A_ScreenWidth/2 - TreeViewWidth - 30

; Create the GUI window and display the source directory (TreeRoot) in the title bar:
Gui := GuiCreate("+Resize", TreeRoot)  ; Allow the user to maximize or drag-resize the window.

; Create an ImageList and put some standard system icons into it:
ImageListID := IL_Create(5)
Loop 5 
  IL_Add(ImageListID, "shell32.dll", A_Index)
; Create a TreeView and a ListView side-by-side to behave like Windows Explorer:
TV := Gui.Add("TreeView", "r20 w" TreeViewWidth " ImageList" ImageListID)
LV := Gui.Add("ListView", "r20 w" ListViewWidth " x+10", "Name|Modified")

; Create a Status Bar to give info about the number of files and their total size:
SB := Gui.Add("StatusBar")
SB.SetParts(60, 85)  ; Create three parts in the bar (the third part fills all the remaining width).

; Add folders and their subfolders to the tree. Display the status in case loading takes a long time:
M := GuiCreate("ToolWindow -SysMenu", "Loading the tree..."), M.Show()
DirList := AddSubFoldersToTree(TV, TreeRoot, {})
M.Hide()

; Call TV_ItemSelect whenever a new item is selected:
TV.OnEvent("ItemSelect", Func("TV_ItemSelect").bind(DirList, SB, LV))

; Call Gui_Size whenever the window is resized:
Gui.OnEvent("Size", Func("Gui_Size").bind(TV, LV))

; Set the ListView's column widths (this is optional):
Col2Width := 70  ; Narrow to reveal only the YYYYMMDD part.
LV.ModifyCol(1, ListViewWidth - Col2Width - 30)  ; Allows room for vertical scrollbar.
LV.ModifyCol(2, Col2Width)

; Display the window. The OS will notify the script whenever the user performs an eligible action:
Gui.Show

AddSubFoldersToTree(TV, Folder, DirList, ParentItemID := 0)
{
  ; This function adds to the TreeView all subfolders in the specified folder
  ; and saves their paths associated with an ID into an object for later use.
  ; It also calls itself recursively to gather nested folders to any depth.
  Loop Files, Folder "\*.*", "D"  ; Retrieve all of Folder's sub-folders.
  {
    ItemID := TV.Add(A_LoopFileName, ParentItemID, "Icon4")
    DirList[ItemID] := A_LoopFilePath
    DirList := AddSubFoldersToTree(TV, A_LoopFilePath, DirList, ItemID)
  }
  return DirList
}

TV_ItemSelect(DirList, SB, LV, TV, Item)  ; This function is called when a new item is selected.
{
  ; Put the files into the ListView:
  LV.Delete  ; Clear all rows.
  LV.Opt("-Redraw")  ; Improve performance by disabling redrawing during load.
  TotalSize := 0  ; Init prior to loop below.
  Loop Files, DirList[Item] "\*.*"  ; For simplicity, omit folders so that only files are shown in the ListView.
  {
    LV.Add(, A_LoopFileName, A_LoopFileTimeModified)
    TotalSize += A_LoopFileSize
  }
  LV.Opt("+Redraw")

  ; Update the three parts of the status bar to show info about the currently selected folder:
  SB.SetText(LV.GetCount " files", 1)
  SB.SetText(Round(TotalSize / 1024, 1) " KB", 2)
  SB.SetText(DirList[Item], 3)
}

Gui_Size(TV, LV, Gui, MinMax, Width, Height)  ; Expand/Shrink ListView and TreeView in response to the user's resizing.
{
  if MinMax = -1  ; The window has been minimized.  No action needed.
    return
  ; Otherwise, the window has been resized or maximized. Resize the controls to match.
  TV.Move("H" Height - 30)  ; -30 for StatusBar and margins.
  LV.Move("H" Height - 30 " W" Width - TV.Pos.W - 30)
}