GuiControl 对象

class Gui.Control extends Object

Add

添加新项目到多项目控件(ListBox, DropDownList, ComboBox 或 Tab).

GuiCtrl.Add(Items)

参数

Items

类型: Array

将作为项目插入控件列表末尾的字符串数组, 例如, ["Red", "Green", "Blue"].

备注

要替换(覆盖) 列表, 请事先使用 GuiControl.Delete.

要添加项目到 ListView 或 TreeView 控件, 请使用 LV.Add 或 TV.Add.

有关演示, 请参阅示例 #1.

Choose

在多项目控件(ListBox, DropDownList, ComboBox 或 Tab) 中选择一个项目..

GuiCtrl.Choose(Item)

参数

Item

类型: 整数或字符串

指定 1 表示第一个项目, 2 表示第二个, 等等. 指定 0 表示取消选择所有项目.

如果字符串(可以是数字字符串), 将选择名称前部与字符串相匹配的项目. 搜索不区分大小写. 例如, 如果多项目控件中包含 "UNIX Text" 项目, 指定单词 unix(小写) 就可以选择它. 对于一个多选 ListBox, 所有匹配的项目都会被选中.

备注

要选择多选 ListBox 中的所有项目, 请使用 PostMessage(0x0185, 1, -1, GuiCtrl), 其中 0x0185 为 LB_SETSEL. 作为另一种选择, 可以对由 ControlGetItems 函数返回的数组中的每个元素调用此方法:

for index, text in ControlGetItems(GuiCtrl)
    GuiCtrl.Choose(index)

与 ControlChooseIndex 不同, 该方法不会触发 Change 或 DoubleClick 事件.

要选择 ListView 或 TreeView 控件中的项目, 请使用带有 Select 选项的 LV.Modify 或 TV.Modify.

Delete

删除多项目控件(ListBox, DropDownList, ComboBox 或 Tab) 中的一个或所有项目.

GuiCtrl.Delete(Item)

参数

Item

类型: 整数

如果省略, 则删除所有项目. 否则, 指定 1 表示第一个项目, 2 表示第二个, 等等.

备注

对于 Tab 控件, 一个标签的子控件会与其原始的标签编号相关联; 也就是说, 它们永远不会与其标签的实际显示名称相关联. 因此, 重命名或删除一个选项卡不会改变子控件所属的选项卡号. 例如, 如果有三个选项卡 ["Red", "Green", "Blue"] 并且通过 GuiCtrl.Delete(2) 删除了第二个选项卡, 则原来与 Green 相关联的子控件现在将与 Blue 相关联. 由于这种行为, 一般只应删除最后的标签页. 以这种方式删除的标签页可以在以后再添加回来, 届时它们将重新获得原来的控件集.

要删除 ListView 或 TreeView 控件中的项目, 请使用 LV.Delete 或 TV.Delete.

有关演示, 请参阅示例 #1.

Focus

设置键盘焦点到控件上.

GuiCtrl.Focus()

要让设置生效, 窗口一般不能处于最小化或隐藏状态.

要得到用户界面窗口的当前焦点控件, 请使用 Gui.FocusedCtrl.

要确定一个控件是否处于键盘焦点状态, 请使用 GuiControl.Focused.

有关演示, 请参阅示例 #6.

GetPos

获取控件的位置和大小.

GuiCtrl.GetPos(&X, &Y, &Width, &Height)

参数

&X, &Y

类型: VarRef

如果省略, 则不存储相应的值. 否则, 指定对输出变量的引用, 在输出变量中存储控件左上角的 X 和 Y 坐标(以像素为单位). 这些坐标相对于窗口客户端区域的左上角, 该区域不包括标题栏, 菜单栏和边框.

&Width, &Height

类型: VarRef

如果省略, 则不存储相应的值. 否则, 指定对输出变量的引用, 以存储控件的宽度和高度(以像素为单位).

备注

与 ControlGetPos 不同, 本方法对返回的坐标应用了 DPI 缩放(除非使用了 -DPIScale 选项).

有关演示, 请参阅示例 #5 或示例 #10.

Move

移动和/或调整控件.

GuiCtrl.Move(X, Y, Width, Height)

参数

X, Y

类型: 整数

如果省略其中任何一个, 则不会更改控件在该维度中的位置. 否则, 指定控件新位置左上角的 X 和 Y 坐标(以像素为单位). 坐标相对于窗口的客户端区域的左上角, 该区域不包括标题栏, 菜单栏和边框.

Width, Height

类型: Integer

如果省略其中任何一个, 则不会更改该维度中的控件的大小. 否则, 指定控件的新宽度和高度(以像素为单位).

备注

与 ControlMove 不同, 本方法将 DPI 缩放应用于坐标(除非使用了 -DPIScale 选项).

有关演示, 请参阅示例 #4 或示例 #5.

OnCommand

注册一个函数或方法, 当通过 WM_COMMAND 消息接收到控件通知时调用.

GuiCtrl.OnCommand(NotifyCode, Callback , AddRemove)

有关详情, 请参阅 OnCommand.

OnEvent

注册一个函数或方法, 当给定事件触发时调用.

GuiCtrl.OnEvent(EventName, Callback , AddRemove)

有关详情, 请参阅 OnEvent.

OnNotify

注册一个函数或方法, 当通过 WM_NOTIFY 消息接收到控件通知时调用.

GuiCtrl.OnNotify(NotifyCode, Callback , AddRemove)

有关详情, 请参阅 OnNotify.

Opt

添加或移除各种选项和样式.

GuiCtrl.Opt(Options)

参数

Options

类型: 字符串

指定一个或多个控件专用或通用选项和样式, 用一个或多个空格或制表符与下一个隔开.

例如, "+Disabled -Background" 这两种操作都会禁用一个控件, 并将其 background 恢复为系统默认样式, 而 "+Default" 则会将按钮设为新的默认按钮.

备注

所有有效的选项和样式通常都会被识别. 然而, 这并不意味着在创建控件后所有这些选项都能被应用或取消. 有些样式是不能事后更改的. 对于位置和大小选项, 请使用 GuiControl.Move, 可选择配合 GuiControl.GetPos 进行相对调整.

如果无法应用更改, 则抛出异常. 即便更改成功执行了, 控件也可能选择忽略它.

Redraw

重绘控件所占的 GUI 窗口区域.

GuiCtrl.Redraw()

虽然当重复和快速调用时, 可能会导致不必要的闪烁效果, 但它解决了某些控件类型(如 GroupBoxe) 的显示重影的问题.

在向控件(如 a ListView, TreeView 或 ListBox) 添加大量项目时, 可以通过在进行更改时阻止控件重新绘制来提高性能. 这可以通过在添加项目之前使用 GuiCtrl.Opt("-Redraw") 并在之后使用 GuiCtrl.Opt("+Redraw") 来实现. 在禁用重绘之前尚未显示的控件更改通常要等到重绘重新启用后才会显示出来.

出于性能考虑, 对控件内容的更改通常不会导致该控件立即重新绘制, 即便重绘功能已启用也是如此. 相反, 控件的一部分会被 "标记为无效", 通常会在短暂延迟后, 当程序检查其内部消息队列时重新绘制. 脚本可以通过调用 Sleep -1 来强制立即执行此操作.

SetFont

更改控件的字体类型, 大小, 颜色和/或样式.

GuiCtrl.SetFont(Options, FontName)

省略这两个参数, 以将字体设置为 GUI 的当前字体, 如 Gui.SetFont 所设置. 否则, 任何未指定的字体属性将从控件的先前字体中复制. 只有在 Options 中指定的情况下, 文本颜色才会改变.

关于这两个参数的详细说明, 请参阅 Gui.SetFont.

有关演示, 请参阅示例 #7.

ClassNN

获取控件的 ClassNN(类名和序列编号).

ClassNN := GuiCtrl.ClassNN

Enabled

获取或设置控件是否处于启用状态.

IsEnabled := GuiCtrl.Enabled

GuiCtrl.Enabled := NewState

IsEnabled 值为 1 表示控件处于启用状态, 值为 0 则表示处于禁用状态. 而 Disabled 选项 会影响初始设置.

NewState 是一个布尔值. 如果为 true, 则启用该控件. 如果为 false, 则禁用该控件.

对于 Tab 控件, 这也将启用或禁用该 Tab 的所有子控件. 然而, 任何通过 GuiCtrl.Enabled := false 显式禁用的子控件将记住该设置, 因此即使在其 Tab 控件被重新启用后也会保持禁用状态.

Focused

获取控件是否具有键盘焦点.

IsFocused := GuiCtrl.Focused

IsFocused 值为 1 表示控件有键盘焦点, 值为 0 则表示没有键盘焦点.

要让设置生效, 窗口一般不能处于最小化或隐藏状态.

要在 GUI 窗口中获取聚焦的控件, 请使用 Gui.FocusedCtrl.

要聚焦到控件, 请使用 GuiControl.Focus.

Gui

获取控件的父窗口.

GuiObj := GuiCtrl.Gui

GuiObj 是父窗口的 Gui 对象.

Hwnd

获取控件的窗口句柄(HWND).

HWND := GuiCtrl.Hwnd

Name

获取或设置控件的显式名称.

CurrentName := GuiCtrl.Name

GuiCtrl.Name := NewName

CurrentName 为控件的当前名称, 或者如果它没有名称, 则是一个空字符串. V 选项则会影响初始设置.

NewName 为控件的新名称.

名称可以与 Gui.__Item 一起使用, 来检索 GuiControl 对象. 对于大多数支持输入的控件, Gui.Submit 也会使用这个名称.

Text

获取或设置控件的文本/标题.

CurrentText := GuiCtrl.Text

GuiCtrl.Text := NewText

CurrentText 和 NewText 的值取决于当前控件. 如果控件没有可见的标题文本且没有(单个) 文本值, 如 MonthCal, 那么此属性对应于该控件的隐藏标题文本(类似于 ControlGetText 和 ControlSetText). 有关示例, 请参阅示例 #9.

Button / CheckBox / GroupBox / Link / Radio / Text

CurrentText 和 NewText 分别是当前和新的标题/显示文本. 由于该控件不会自动扩展, 若要使该控件变宽, 请使用 GuiControl.Move.

DateTime

CurrentText 是该控件所显示的当前格式化文本. NewText 无效, 并会引发异常. 若要更改显示的日期/时间, 请使用 GuiControl.Value 来设置 YYYYMMDDHH24MISS 格式的日期时间戳.

ComboBox / DropDownList / ListBox / Tab

CurrentText 示当前选中项目或选项卡的文本, 若未选中则为空. 对于 ComboBox, 若未选中任何项, 则为编辑字段中的文本内容. 对于多选的 ListBox, 它是一个包含每个选中项文本的数组, 若未选中则为空.

NewText 是要选择的项目或选项卡的完整文本(不区分大小写), 若为空则会取消当前的选择. 对于多选的 ListBox, 会选中完全匹配该文本的所有项目. 若要用不同文本选择多个项目, 请重复调用 GuiControl.Choose. GuiControl.Value 通过索引来选择一个项目或选项卡.

Edit

CurrentText 和 NewText 分别代表当前文本和新文本. 与其他控件一样, 文本会被原样获取或设置; 不会进行换行转换. 若要在获取或设置多行编辑控件的文本时同时进行 CR+LF (`r`n) 和 LF (`n) 之间的转换, 请使用 GuiControl.Value.

StatusBar

CurrentText 和 NewText 分别代表第一部分的当前文本和新文本. 若需更灵活的使用方式, 请使用 StatusBar.SetText.

Type

获取控件的类型.

CurrentType := GuiCtrl.Type

CurrentType 是以下字符串之一, 这取决于控件类型: ActiveX, Button, CheckBox, ComboBox, Custom, DateTime, DDL, Edit, GroupBox, Hotkey, Link, ListBox, ListView, MonthCal, Pic, Progress, Radio, Slider, StatusBar, Tab, Tab2, Tab3, Text, TreeView, UpDown.

Value

获取或设置具有值属性的控件的内容.

CurrentValue := GuiCtrl.Value

GuiCtrl.Value := NewValue

CurrentValue 和 NewValue 的值取决于当前的控件. 如果该控件不包含值, CurrentValue 将是空白, 并且赋值给 NewValue 将引发错误. 无效的值会抛出异常. 有关演示, 请参阅示例 #2, 示例 #3, 示例 #8 或示例 #9.

ActiveX

CurrentValue 是一个 ActiveX 对象. 例如, 如果该控件是通过组件名称 "Shell.Explorer" 创建的, 那么这就是一个 WebBrowser 对象. 每次都会返回同一个包装对象. NewValue 无效并抛出异常.

CheckBox / Radio

CurrentValue 和 NewValue 分别代表当前设置和新设置: 1 表示选中, 0 未选中, 或 -1 表示不确定. 对于 Radio 按钮, 如果有一个按钮被选中(打开) 并且它是一个多个单选按钮组的成员, 那么该组中的其他单选按钮将被自动取消选中. 如果要获取或设置控件的文本/标题, 请使用 GuiControl.Text.

ComboBox / DropDownList / ListBox / Tab

CurrentValue 是当前选中的项目/选项卡的索引, 如果没有选择, 则为 0. 对于 ComboBox, 若输入了文本, 则为与该文本(不区分大小写) 完全匹配的第一项的索引, 如果没有匹配的项目, 则为 0. 对于多选的 ListBox, 它是一个包含每个选中项索引的数组, 如果没有选中任何项, 则该数组为空.

NewValue 是要选择的单个项目/选项卡的索引, 或者为 0 来清除当前的选择(即使对 Tab 控件也有效).对于多选的 ListBox, 要选择多个项目, 请重复调用 GuiControl.Choose. GuiControl.Text 则通过文本来选择一个项目或选项卡.

DateTime / MonthCal

CurrentValue 和 NewValue 均为采用 YYYYMMDDHH24MISS 格式的日期时间戳, 分别代表当前选中以及将在控件中被选中的日期/时间. 指定 A_Now 为 NewValue, 可使用当前日期和时间(即今天). 对于 DateTime 控件, NewValue 可以为空, 以使该控件没有选择日期/时间(如果它在创建时含有这个能力). 对于 MonthCal 控件, 如果控件是多选的, 则可以指定一个日期范围.

Edit

CurrentValue 是当前内容. 对于多行控件, 文本中的任何换行符将以普通换行符(`n) 表示, 而不是 ControlGetText 和 ControlSetText 等非 GUI 函数所使用传统的 CR+LF(`r`n).

NewValue 是新的内容. 对于多行控件, 任何缺少前回车(`r) 的换行(`n) 都会被自动转换为 CR+LF(`r`n) 以使其正确显示. 然而, 这通常不是一个问题, 因为当使用 Gui.Submit 或检索这个值时, 这个转换会自动反过来, 用 LF(`n) 替换 CR+LF(`r`n).

要获取或设置文本, 而不将 LF(`n) 转换为或从 CR+LF(`r`n) 进行转换, 请使用 GuiControl.Text.

Hotkey

CurrentValue 和 NewValue 均为由修饰符和键名组成的字符串, 分别代表当前在控件中显示的热键以及要显示在控件中的热键. 例如, ^!c, ^Numpad1 或 +Home. 如果在控件中没有热键, CurrentValue 为空. NewValue 可以为空以清空控件. 支持的修饰符仅包含 ^(Control), !(Alt) 和 +(Shift). 有关可用的按键名称, 请参阅按键列表.

Picture

CurrentValue 指的是创建控件时所指定的该图片的文件名. 即使指定了新的图片文件名, 这个名称也不会改变.

NewValue 是要加载的新图片的文件名(或句柄(关于支持的文件类型, 请参阅 Picture). 可以在文件名前指定零个或多个下列选项: *wN(宽度 N), *hN(高度 N) 和 *IconN(DLL 或 EXE 文件中的图标组编号 N). 例如, "*icon2 *w100 *h-1 C:\My Application.exe" 从第二个图标组中加载默认图标, 该图标宽度为 100 以及通过 "保持高宽比" 自动设置高度. 指定 *w0 *h0 使用图像的实际宽度和高度. 如果同时省略 *w 和 *h, 则调整图像以适应控件当前的大小. 从多图标的 .ICO 文件中加载时, 指定宽度和高度也决定了加载哪个图标. 注意: 在最后的选项和文件名之间只使用一个空格或制表符; 任何其他空格和制表符都会被视为文件名的一部分.

Progress / Slider / UpDown

CurrentValue 和 NewValue 分别是控件的当前位置和新位置. 如果新位置会超出控件的范围, 通常会将控件设置为最接近的有效值.

Text

CurrentValue 和 NewValue 分别代表当前的和新的文本/标题. 由于控件不会自动扩展, 若要使控件变宽, 请使用 GuiControl.Move.

Visible

获取或设置控件是否处于可见状态.

IsVisible := GuiCtrl.Visible

GuiCtrl.Visible := NewState

如果控件可见, IsVisible 值为 1, 否则值为 0. Hidden 选项影响初始设置.

NewState 应是一个布尔值. 如果为 true, 控件可见. 如果为 false, 控件被隐藏.

对于 Tab 控件, 这也将显示或隐藏该 Tab 的所有子控件.

如果您还想阻止一个控件的快捷键(下划线字母) 工作, 通过 GuiCtrl.Enabled := false 禁用该控件.

MyGui := Gui()
MyListBox := MyGui.Add("ListBox",, ["Black", "White"])
MyGui.Show()
Sleep 1000 ; 为演示目的而等待.
MyListBox.Delete()
MyListBox.Add(["Red", "Green", "Blue"])

MyGui := Gui()
MyEdit := MyGui.Add("Edit", "r2 w100", "Old text line.")
MyGui.Show()
Sleep 1000 ; 为演示目的而等待.
MyEdit.Value := "New text line 1.`nNew text line 2."

MyGui := Gui()
MyRadio1 := MyGui.Add("Radio", "Checked", "Radio button 1")
MyRadio2 := MyGui.Add("Radio",, "Radio button 2")
MyRadio3 := MyGui.Add("Radio",, "Radio button 3")
MyGui.Show()
Sleep 1000 ; 为演示目的而等待.
MyRadio2.Value := 1

MyGui := Gui()
MyButton := MyGui.Add("Button",, "OK")
MyGui.Show("w300 h300")
Sleep 1000 ; 为演示目的而等待.
MyButton.Move(100, 200)

MyGui := Gui()
MyEdit := MyGui.Add("Edit")
MyGui.Show("w300 h300")
Sleep 1000 ; 为演示目的而等待.
MyEdit.GetPos(&X, &Y, &W, &H)
MyEdit.Move(X+10, Y+5, W*2, H*1.5)

MyGui := Gui()
MyGui.Add("Text", "Section", "First name:")
MyGui.Add("Text",, "Last name:")
EditFirstName := MyGui.Add("Edit", "ys")
EditLastName := MyGui.Add("Edit")
MyGui.Show()
Sleep 1000 ; 为演示目的而等待.
EditLastName.Focus()

MyGui := Gui()
MyGui.SetFont("s14")
MyGui.Add("Text",, "This is a test.")
MyText := MyGui.Add("Text",, "This is a test.")
MyGui.Add("Text",, "This is a test.")
MyGui.Show()
Sleep 1000 ; 为演示目的而等待.
MyText.SetFont("cRed", "Times New Roman")

MyGui := Gui()
MyEdit := MyGui.Add("Edit",, "This is a test.")
MyGui.Show()
MsgBox MyEdit.Value

MyGui := Gui()
MyCheckBox1 := MyGui.Add("CheckBox",, "CheckBox 1")
MyCheckBox2 := MyGui.Add("CheckBox",, "CheckBox 2")
MyCheckBox1.OnEvent("Click", ReportState)
MyCheckBox2.OnEvent("Click", ReportState)
MyGui.Show()

ReportState(MyCheckBox, *)
{
    Caption := MyCheckBox.Text
    State := MyCheckBox.Value
    MsgBox Caption " is " (State = 0 ? "unchecked" : "checked")
}

MyGui := Gui()
MyPicture := MyGui.Add("Picture",, A_AhkPath)
MyGui.Show()
MyPicture.GetPos(&X, &Y, &W, &H)
MsgBox "x" X ", y" Y ", w" W ", h" H