TreeView (GUI) | AutoHotkey v1

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

选项参数的样式和选项

AltSubmit: 通知脚本有比正常更多的 TreeView 事件类型. 换句话说, g-标签会运行地更频繁. 请参阅 TreeView 通知了解详情.

Background: 指定单词 Background 后面紧跟着颜色名称(请参阅颜色图表) 或 RGB 值(0x 前缀可以省略). 例如: BackgroundSilver, BackgroundFFDD99. 如果此选项不存在, 则 TreeView 初始默认的背景颜色由 Gui Color 的最后一个参数设置(如果没有, 则使用系统默认的背景颜色). 指定 BackgroundDefault 来应用系统的默认背景颜色(通常为白色). 例如, 使用 GuiControl, +BackgroundDefault, MyTreeView 可以把 TreeView 恢复为默认的颜色.

Buttons: 指定 -Buttons(负 Buttons) 来避免在每个含有子项目的项目左边显示加号或减号按钮.

C: 文本颜色. 指定字母 C 后面紧跟着颜色名称(请参阅颜色图表) 或 RGB 值(0x 前缀可以省略). 例如: cRed, cFF2211, c0xFF2211, cDefault.

Checked: 在每项的左边提供一个复选框. 当添加项目时, 在其选项中指定单词 Check 来让复选框初始为选中而不是未选中状态. 用户可以点击复选框或按下空格键来选中或取消选中项目. 要找出 TreeView 中当前选中了哪些项目, 请调用 TV_GetNext() 或 TV_Get().

HScroll: 指定 -HScroll(负 HScroll) 来禁用控件中的水平滚动(而且控件将不显示水平滚动条).

ImageList: 这是把图标添加到 TreeView 的方法. 指定单词 ImageList 后紧跟着由之前调用 IL_Create() 返回的 ImageList ID. 此选项仅在创建 TreeView 时才有效果(但是, TV_SetImageList() 没有此限制). 这里是一个可运行示例:

Lines: 指定 -Lines(负 Lines) 来避免显示连接父项目和它们的子项目之间的网状线. 但是, 移除这些线也阻止了顶级项目坐标加号/减号按钮的显示.

ReadOnly: 指定 -ReadOnly(负 ReadOnly) 来允许编辑每项的文本/名称. 要编辑某项, 请选择它接着按下 F2(请参阅下面的 WantF2 选项). 或者, 您可以对某个项目点击一次来选择它, 至少等半秒, 然后再次点击同一项目进行编辑. 编辑后, 可以对一个项目在其同级项目之间按字母顺序进行重新定位, 请参考下面的例子:

R: 行高(创建时). 指定字母 R 后面紧跟着要在控件中留出空间的行数. 例如, R10 会设置控件为 10 个项目的高度.

WantF2: 指定 -WantF2(负 WantF2) 来禁止使用 F2 来编辑当前选择的项目. 仅当 -ReadOnly 也有效时此设置才不会被忽略. 不论此设置如何, g-标签仍会接收到 F2 通知.

(未命名的数值样式): 由于上述以外的其他样式很少使用, 所以没有为它们命名. 请参阅 TreeView 样式表了解这些样式.

TreeView 中的内置函数

以下所有的 TreeView 函数操作于当前线程的默认 GUI 窗口(这可以使用 Gui, 2: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 可以使用在此控件的选项中. 这使得当用户在控件中执行动作时 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.

备注

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

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

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

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

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

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

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

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

Tree View eXtension(TVX) 扩展了 TreeView 的功能, 增加对移动, 插入和删除的支持. 演示的例子请参阅 www.autohotkey.com/board/topic/17497-

相关

示例

下面是一个比页面顶部的脚本更复杂的可工作的脚本. 它创建并显示一个 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+]

目录

入门和简单示例