TreeView

目录

• 入门和简单示例
• 参数
• 内置方法
• 事件
• ImageLists(the means by which icons are added to a TreeView)
• 备注
• 示例

入门和简单示例

TreeView 通过缩进父项目下的子项目来显示出层级关系. 最常见的例子是资源管理器的驱动器和文件夹树.

TreeView 通常看起来像这样:

创建 TreeView 的语法为:

GuiCtrl := MyGui.Add("TreeView", Options)
GuiCtrl := MyGui.AddTreeView(Options)

这是一个创建和显示简单项目层次结构的可运行脚本:

MyGui := Gui()
TV := MyGui.Add("TreeView")
P1 := TV.Add("First parent")
P1C1 := TV.Add("Parent 1's first child", P1)  ; 指定 P1 为此项目的父项目.
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)

MyGui.Show()  ; 显示窗口和 TreeView.

Parameters

Options

Type: String

In addition to the general options and styles, the following are supported or noteworthy:

BackgroundColor: Background color. Specify for Color 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 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.

CColor: Text color. Specify for Color 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 the GetNext or Get methods.

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

ImageListID: This is the means by which icons are added to a TreeView. Specify for ID the ImageList ID returned from a previous call to IL_Create. This option has an effect only when creating a TreeView. Alternatively, the SetImageList method can be used without the limitation previously mentioned. For details, see ImageLists.

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 F2 (see the WantF2 option below). 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, as in example #1.

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

Wn: Sets the width of the control. For example, specifying w400 would make the control 400 pixels wide. If omitted, the default is 30 times the current font size.

Rn or Hn: Sets the height of the control. For example, specifying r7 would make room for 7 rows inside the control, while h400 would set the total height of the control to 400 pixels. If both R and H are omitted, the default is 5 rows.

(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.

TreeViews 的内置方法

除了GUI 控件的默认方法/属性外, 该控件类型拥有以下方法.

项目方法:

• Add: 添加新的项目到 TreeView.
• Modify: 修改项目的属性和/或名称.
• Delete: 删除指定项目或所有项目.

检索方法:

• GetSelection: 返回选择项目的 ID 号.
• GetCount: 返回控件中项目的总数.
• GetParent: 返回指定项目的父项目的 ID.
• GetChild: 返回指定项目的第一个/最上面的子项目的 ID.
• GetPrev: 返回指定项目上面一个的同级项目的 ID 号.
• GetNext: 返回指定项目下面一个项目的 ID 号.
• GetText: 检索指定项目的文本/名称.
• Get: 如果指定项目含有指定的属性, 则返回项目的 ID.

其他方法:

• SetImageList: 设置或替换用于显示图标的 ImageList.

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

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

TV.Delete(ItemID)

ItemID := TV.GetSelection()

Count := TV.GetCount()

ParentItemID := TV.GetParent(ItemID)

ChildItemID := TV.GetChild(ItemID)

PrevItemID := TV.GetPrev(ItemID)

NextItemID := TV.GetNext(ItemID, ItemType)

ItemID := 0  ; 这样使得首次循环从树的顶部开始搜索.
Loop
{
    ItemID := TV.GetNext(ItemID, "Full")  ; 把 "Full" 替换为 "Checked" 来找出所有含复选标记的项目.
    if not ItemID  ; 没有更多项目了.
        break
    ItemText := TV.GetText(ItemID)
    MsgBox('The next Item is ' ItemID ', whose text is "' ItemText '".')
}

Text := TV.GetText(ItemID)

ItemID := TV.Get(ItemID, Attribute)

PrevImageListID := TV.SetImageList(ImageListID , IconType)

事件

通过调用 GuiControl.OnEvent 来注册一个回调函数或方法, 可以检测到以下事件:

额外的(很少使用的) 通知可以通过使用 GuiControl.OnNotify 来检测. 这些通知在 Microsoft Docs 上都有文档. Microsoft Docs 没有显示每个通知代码的数值; 这些可以在 Windows SDK 中找到, 或者在互联网上搜索.

ImageLists

An Image-List is a group of identically sized icons stored in memory. Upon creation, each ImageList is empty. The script calls IL_Add repeatedly to add icons to the list, and each icon is assigned a sequential number starting at 1. This is the number to which the script refers to display a particular icon to the left of an item's name. Here is a working example that demonstrates how to put icons into a TreeView:

MyGui := Gui()
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 := MyGui.Add("TreeView", "ImageList" . ImageListID)
TV.Add("Name of Item", 0, "Icon4")  ; Add an item to the TreeView and give it a folder icon.
MyGui.Show()

The SetImageList method can be used as an alternative to the ImageList option.

For detailed information about all ImageList functions, check out the ListView page.

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.

备注

当 TreeView 拥有焦点时如果要检测到用户按下的 Enter 键, 请使用默认按钮(如果需要可以隐藏它). 例如:

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

使用键盘除了在项与项之间导航外, 用户还可以通过输入一个项目名称的前几个字符来进行增量搜索. 这使得选择对象跳转到最近匹配的项目.

尽管 TreeView 中的每个项目可以存储任意长度的文本, 但仅显示开始的 260 个字符.

尽管理论上 TreeView 中的项目数可以多达 65536, 然而接近此数目时添加项的性能将显著降低. 通过使用 Add 方法中描述的重绘提示可以稍微减轻这种情况.

脚本可以在每个窗口中创建多个 TreeView.

要执行一些操作, 例如调整大小, 隐藏或改变 TreeView 的字体, 请参阅 GuiControl 对象.

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

相关

ListView, 其他控件类型, Gui(), ContextMenu 事件, Gui 对象, GuiControl 对象, TreeView 样式表

示例

MyGui := Gui()
TV := MyGui.Add("TreeView", "-ReadOnly")
TV.Add("A")
TV.Add("B")
TV.Add("C")
TV.OnEvent("ItemEdit", TV_Edit)  ; Call TV_Edit whenever we finish editing an item.
MyGui.Show()

TV_Edit(TV, Item)
{
    TV.Modify(TV.GetParent(Item), "Sort")  ; This works even if the item has no parent.
}

; 下面的文件夹为 TreeView 的根文件夹. 请注意, 如果指定整个驱动器例如 C:\
; 那么可能需要很长加载时间:
TreeRoot := A_MyDocuments
TreeViewWidth := 280
ListViewWidth := A_ScreenWidth/2 - TreeViewWidth - 30

;  创建 Gui 窗口并在标题栏中显示源目录(TreeRoot):
MyGui := Gui("+Resize", TreeRoot)  ; 让用户可以最大化或拖动调整窗口大小.

; 创建图像列表并在其中放入一些标准的系统图标:
ImageListID := IL_Create(5)
Loop 5 
    IL_Add(ImageListID, "shell32.dll", A_Index)
; 创建 TreeView 和 ListView, 让它们像在 Windows 资源管理器中那样靠在一起:
TV := MyGui.Add("TreeView", "r20 w" TreeViewWidth " ImageList" ImageListID)
LV := MyGui.Add("ListView", "r20 w" ListViewWidth " x+10", ["Name", "Modified"])

; 创建状态栏, 显示文件夹数及其总大小的信息:
SB := MyGui.Add("StatusBar")
SB.SetParts(60, 85)  ; 在状态栏中创建三个部分(第三部分占用所有剩余宽度).

; 添加文件夹及其子文件夹到树中. 如果加载需要很长时间, 则显示提示信息:
M := Gui("ToolWindow -SysMenu Disabled AlwaysOnTop", "Loading the tree..."), M.Show("w200 h0")
DirList := AddSubFoldersToTree(TreeRoot, Map())
M.Hide()

; 每当有新的项目被选中时, 调用 TV_ItemSelect:
TV.OnEvent("ItemSelect", TV_ItemSelect)

; 每当窗口被调整大小时, 调用 Gui_Size:
MyGui.OnEvent("Size", Gui_Size)

; 设置 ListView 的列宽(这是可选的):
Col2Width := 70  ; 缩小到只显示 YYYYMMDD 部分.
LV.ModifyCol(1, ListViewWidth - Col2Width - 30)  ; 允许垂直滚动条.
LV.ModifyCol(2, Col2Width)

; 显示窗口并返回. 每当用户执行符合条件的动作时, 操作系统会通知脚本:
MyGui.Show()

AddSubFoldersToTree(Folder, DirList, ParentItemID := 0)
{
    ; 该函数将指定文件夹中的所有子文件夹添加到 TreeView 中,
    ; 并将它们与 ID 相关联的路径保存到一个对象中, 供以后使用.
    ; 它还可以递归地调用自己来收集任意深度的嵌套文件夹.
    Loop Files, Folder "\*.*", "D"  ; 获取所有文件夹的子文件夹.
    {
        ItemID := TV.Add(A_LoopFileName, ParentItemID, "Icon4")
        DirList[ItemID] := A_LoopFilePath
        DirList := AddSubFoldersToTree(A_LoopFilePath, DirList, ItemID)
    }
    return DirList
}

TV_ItemSelect(thisCtrl, Item)  ; 当选择一个新的项目时, 该函数被调用.
{
    ; 将文件放入 ListView 中:
    LV.Delete()  ; 清除所有行.
    LV.Opt("-Redraw")  ; 通过在加载过程中禁止重绘来提高性能.
    TotalSize := 0  ; 在下面循环之前初始化.
    Loop Files, DirList[Item] "\*.*"  ; 为了简化, 这里省略了文件夹, 所以只在 ListView 中显示文件.
    {
        LV.Add(, A_LoopFileName, A_LoopFileTimeModified)
        TotalSize += A_LoopFileSize
    }
    LV.Opt("+Redraw")

    ; 更新状态栏的三个部分, 让它们显示当前选择的文件夹的信息:
    SB.SetText(LV.GetCount() " files", 1)
    SB.SetText(Round(TotalSize / 1024, 1) " KB", 2)
    SB.SetText(DirList[Item], 3)
}

Gui_Size(thisGui, MinMax, Width, Height)  ; 当用户改变窗口大小时扩展/收缩 ListView 和 TreeView.
{
    if MinMax = -1  ; 窗口被最小化了. 无需进行操作.
        return
    ; 否则, 窗口的大小被调整过或被最大化了. 调整控件大小以适应.
    TV.GetPos(,, &TV_W)
    TV.Move(,,, Height - 30)  ; -30 用于状态栏和边距.
    TV.Move(,, Width - TV_W - 30, Height - 30)
}