TreeView (GUI) | AutoHotkey v1

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

参数

内置函数

以下函数操作于当前线程的默认 GUI 窗口(这可以使用 Gui Default 进行改变). 如果默认窗口不存在或不含有 TreeView 控件, 则函数返回零来表明此问题.

如果窗口中含有多个 TreeView 控件, 则默认情况下函数操作于最近添加的那个. 要改变这种情况, 请指定 Gui, TreeView, TreeViewName, 其中 TreeViewName 为 TreeView 的关联变量的名称或 Window Spy 中显示的其 ClassNN 或在 [v1.1.04+] 中它的 HWND. 一旦改变后, 所有现有和将来的线程都会使用指定的 TreeView. [v1.1.23+]: A_DefaultTreeView 包含当前设置.

TV_Add

参数

返回值

备注

当添加大量项目时, 在添加项目前使用 GuiControl, -Redraw, MyTreeView 并且在添加项目后使用 GuiControl, +Redraw, MyTreeView 可以提升性能.

TV_Modify

参数

返回值

成功时, 函数返回项目自己的 ID. 失败时(或部分失败), 返回 0.

TV_Delete

参数

返回值

TV_GetSelection

返回值

TV_GetCount

返回值

函数返回控件中项目的总数. 该值总是即时返回的, 因为控件会跟踪此计数.

TV_GetParent

参数

返回值

函数返回指定项目的父项目的 ID 号. 如果项目没有父项目, 返回 0, 这适用于所有顶级项目.

TV_GetChild

参数

返回值

函数返回指定项目的第一个/最上面的子项目的 ID 号. 如果没有子项目, 返回 0.

TV_GetPrev

参数

返回值

函数返回指定项目上一个的同级项目的 ID 号. 如果没有同级项目, 返回 0.

TV_GetNext

参数

返回值

函数返回指定项目下一个项目的 ID 号. 如果没有下一个项目, 返回 0.

备注

TV_GetText

参数

返回值

TV_Get

参数

返回值

如果指定的项目具有指定的属性, 则返回它自己的 ID. 否则, 返回 0.

备注

因为在 IF 语句中把任何非零值视为 "true", 所以下面两行功能相同: if TV_Get(ItemID, "Checked") = ItemID 和 if TV_Get(ItemID, "Checked").

TV_SetImageList [v1.1.02+]

参数

返回值

成功时, 函数返回先前与 TreeView 关联的 ImageList ID. 失败时, 返回 0. 任何这样分离的 ImageList 通常应该通过 IL_Destroy() 来销毁.

G-标签通知(主要)

g-标签例如 gMySubroutine 可以使用在 Options 中. 这使得当用户在控件中执行动作时 MySubroutine 标签会自动运行. 此子程序中可引用内置变量 A_Gui 和 A_GuiControl 来找出产生事件的是哪个窗口和 TreeView. 更重要的是, 它可以参考 A_GuiEvent, 其包含下列字符串或字母的其中一个(考虑到和未来版本的兼容性, 脚本不应假定这些字符串或字母是唯一可能的值):

DoubleClick: 用户双击了一项. 变量 A_EventInfo 包含目标项目 ID.

D: 用户尝试开始拖动一个项目(目前还没有内置对拖动项目的支持). 变量 A_EventInfo 包含目标项目 ID.

e(小写的 E): 用户完成编辑一个项目(只有当 TreeView 选项中含有 -ReadOnly 时用户才可以编辑项目). 变量 A_EventInfo 包含目标项目 ID.

S: 选择了一个新项目, 可以是用户或脚本自己选择的. 变量 A_EventInfo 包含新选择项目的 ID.

G-标签通知(次要)

如果 TreeView 含有 AltSubmit 选项, 则其 g-标签会运行的更频繁并且 A_GuiEvent 还可能包含下列值:

Normal: 用户左键单击了一个项目. 变量 A_EventInfo 包含目标项目 ID.

RightClick: 用户右键单击了一个项目. 变量 A_EventInfo 包含目标项目 ID. 在大多数情况下, 最好不要通过显示菜单来响应此通过. 而应使用 GuiContextMenu 标签, 因为它还能识别 Appskey. 例如:

E: 用户开始编辑一个项目(只有当 TreeView 含有 -ReadOnly 选项时用户才可以编辑项目). 变量 A_EventInfo 包含目标项目 ID.

K: 当 TreeView 拥有焦点时用户按下了一个键. A_EventInfo 包含此键的虚拟按键代码, 这是介于 1 和 255 之间的数字. 如果此键是字母键, 则在大多数键盘布局中可以使用 Chr(A_EventInfo) 把它转换成相应的字符. 不论 WantF2 选项如何都可以接收到 F2. 然而, 不会接收到 Enter; 要接收它, 请像下面描述的那样使用一个默认按钮.

+(加号): 展开了一个项目来显示它的子项目. 变量 A_EventInfo 包含目标项目 ID.

-(减号): 折叠一个项目来隐藏它的子项目. 变量 A_EventInfo 包含目标项目 ID.

ImageLists

图像列表是指一组大小相同并存储在内存中的图标. 创建时, 每个 ImageList 都是空的. 脚本会重复调用 IL_Add() 函数来向列表中添加图标, 并且每个图标都会被赋予一个从 1 开始的连续编号. 这个编号就是脚本用于在项目名称左侧显示特定图标所依据的数字. 以下是一个有效的示例, 展示了如何将图标放入 TreeView 中:

与 ListView 不同, 当 TreeView 销毁时它的图像列表不会自动被销毁. 因此, 如果 TreeView 中使用的图像列表以后不再用于其他地方, 则在销毁 TreeView 所在的窗口后脚本应调用 IL_Destroy() 来销毁此图像列表. 然而, 如果脚本很快将退出, 这样做是没必要的, 因为那时所有的图像列表会自动被销毁.

备注

Gui Submit 命令对 TreeView 控件没有效果. 因此, 脚本可以使用 TreeView 的关联变量(如果有) 来保存其他数据而不用担心它会被覆盖.

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

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

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

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

脚本可以在每个窗口中创建多个 TreeView. 要对非默认的 TreeView 进行操作, 请参阅内置函数.

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

Tree View eXtension(TVX)(旧论坛) 扩展了 TreeView 的功能, 增加对插入, 移动和删除的支持.

相关

示例

下面是一个比页面顶部的脚本更复杂的可工作的脚本. 它创建并显示一个 TreeView, 其中包含所有用户开始菜单中的所有文件夹. 当用户选择一个文件夹时, 它的内容会显示在右边的 ListView 中(类似于 Windows 资源管理器). 此外, StatusBar 控件会显示当前选择文件夹的信息.

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

; 让用户可以最大化或拖动调整窗口大小:
Gui +Resize

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

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

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

; 添加文件夹及其子文件夹到树中. 如果加载需要很长时间, 则显示提示信息:
SplashTextOn, 200, 25, TreeView and StatusBar Example, Loading the tree...
AddSubFoldersToTree(TreeRoot)
SplashTextOff

; 显示窗口并返回. 每当用户执行符合条件的动作时, 操作系统会通知脚本:
Gui, Show,, %TreeRoot%  ; 在标题栏中显示源目录(TreeRoot).
return

AddSubFoldersToTree(Folder, ParentItemID = 0)
{
    ; 此函数添加指定文件夹中所有子文件夹到 TreeView.
    ; 它还可以调用自己来递归获取到任意深度的内嵌文件夹.
    Loop %Folder%\*.*, 2  ; 获取所有文件夹的子文件夹.
        AddSubFoldersToTree(A_LoopFileFullPath, TV_Add(A_LoopFileName, ParentItemID, "Icon4"))
}

MyTreeView:  ; 此子程序处理用户的操作(例如点击).
if (A_GuiEvent != "S")  ; 即除了 "选择树中的新项目" 以外的其他操作.
    return  ; 什么都不做.
; 否则, 把选择的文件夹中的内容放入 ListView.
; 首先确定选择的文件夹的完整路径:
TV_GetText(SelectedItemText, A_EventInfo)
ParentID := A_EventInfo
Loop  ; 建立到选择的文件夹的完整路径.
{
    ParentID := TV_GetParent(ParentID)
    if not ParentID  ; 没有更高层的项目了.
        break
    TV_GetText(ParentText, ParentID)
    SelectedItemText := ParentText "\" SelectedItemText
}
SelectedFullPath := TreeRoot "\" SelectedItemText

; 把文件放入 ListView:
LV_Delete()  ; 清除所有行.
GuiControl, -Redraw, MyListView  ; 加载过程中禁用重绘来提升性能.
FileCount := 0  ; 在下面循环之前初始化.
TotalSize := 0
Loop %SelectedFullPath%\*.*  ; 为了简化, 这里省略了文件夹, 所以只在 ListView 中显示文件.
{
    LV_Add("", A_LoopFileName, A_LoopFileTimeModified)
    FileCount += 1
    TotalSize += A_LoopFileSize
}
GuiControl, +Redraw, MyListView

; 更新状态栏的三个部分, 让它们显示当前选择的文件夹的信息:
SB_SetText(FileCount . " files", 1)
SB_SetText(Round(TotalSize / 1024, 1) . " KB", 2)
SB_SetText(SelectedFullPath, 3)
return

GuiSize:  ; 当用户改变窗口大小时扩展/收缩 ListView 和 TreeView.
if (A_EventInfo = 1)  ; 窗口被最小化了. 无需进行操作.
    return
; 否则, 窗口的大小被调整过或被最大化了. 调整控件大小以适应.
GuiControl, Move, MyTreeView, % "H" . (A_GuiHeight - 30)  ; -30 用于状态栏和边距.
GuiControl, Move, MyListView, % "H" . (A_GuiHeight - 30) . " W" . (A_GuiWidth - TreeViewWidth - 30)
return

GuiClose:  ; 当用户关闭 TreeView 所在的 GUI 窗口时退出脚本.
ExitApp

TreeView [v1.0.44+]

目录

入门和简单示例

参数