GuiControl

对 GUI 窗口中的控件进行各种设置.

GuiControl, SubCommand, ControlID , Value

参数

SubCommand, Value
它们相互依赖, 其用法描述如下.
ControlID

如果目标控件有关联变量, 则指定此变量名作为 ControlID(此方法优先于下面描述的那个). 由于这个原因, 通常最好给每个之后要使用 GuiControl 或 GuiControlGet 访问的控件分配一个变量, 即使那个控件不是可输入型(例如 GroupBox 或 Text).

或者 ControlID 可以是 ClassNN(控件的类名和实例编号) 或控件的文本, 它们都可以通过 Window Spy 获取. 使用文本时, 匹配行为由 SetTitleMatchMode 决定.

注意: 图片控件的文件名(和控件创建时指定的一样) 可以作为 ControlID 使用.

[v1.1.04+]: ControlID 可以是控件的 HWND

如果控件不在默认 GUI 中, 那么还必须指定 GUI 的名称或 HWND -- 除非 [v1.1.20+] ControlID 是一个 HWND 值, 因为每个 HWND 都是唯一值. 见备注中的详细解释.

子命令

对于 SubCommand, 指定以下命令之一:

(Blank)

将新内容放入控件.

GuiControl,, ControlID , Value

SubCommand 留空, 通过 Value 将新内容放入控件中. 具体地:

Picture: Value 为要加载的新图像的文件名(或句柄)(请参阅 Gui Picture 了解支持的文件类型). 在文件名的前面可以指定零个或多个下列选项: *wN(宽度 N), *hN(高度 N) 以及*IconN(在 DLL 或 EXE 文件中的图标组编号 N). 在下面的例子中, 将加载第二个图标组中的默认图标, 设置宽度为 100 以及通过"保持高宽比"自动设置高度: GuiControl,, MyPic, *icon2 *w100 *h-1 C:\My Application.exe. 指定 *w0 *h0 使用图像的实际宽度和高度. 如果同时省略 *w*h, 则调整图像以适应控件当前的大小. 从多图标的 .ICO 文件中加载时, 指定宽度和高度也决定了加载哪个图标.

注意: 在最后一个选项和文件名之间只能含有一个空格或 tab; 其他任何空格或 tab 都会被视为文件名的一部分.

Text/Button/GroupBox/StatusBar/Link: 指定 Value 为控件的新文本. 因为控件不会自动进行扩展, 所以如果需要加宽控件请使用 GuiControl, Move, MyText, W300. 对于 StatusBar, 这里只设置了第一部分的文本(使用 SB_SetText() 会更灵活).

Edit: Value 中任何没有前导回车符(`r) 的换行符(`n) 都会自动转换成 CR+LF(`r`n) 以使它们正确显示. 然而, 通常不需要担心, 因为 Gui SubmitGuiControlGet OutputVar 命令会自动将 CR+LF 替换为 LF(`n) 来撤销这种转换.

Hotkey: Value 为空来清空控件, 或键名和修饰符的集合. 例如: ^!c, ^Numpad1, +Home. 支持的修饰符仅包含 ^(Control), !(Alt) 和 +(Shift). 请参阅按键列表了解可用的按键名称.

Checkbox: Value 为 0 来取消选中按钮, 1 来选中它, 或 -1 来设置灰色的选中标记. 否则, Value 被视为控件的新标题/文本. 请参阅下面的 Text 子命令来了解如何覆盖这种行为.

Radio: 与上面的 Checkbox 相同. 然而, 如果单选按钮已经被选中(打开) 且它是多个单选按钮组成的组中的成员, 那么这个组中其他的单选按钮会自动取消选中. 要选中只含有一个变量的单选按钮组中的新按钮, 如果这个新按钮没有直接关联的变量, 则请在 ControlID 中指定它的名称/文本.

DateTime/MonthCal: 指定 ValueYYYYMMDDHH24MISS 格式的时间戳. 指定 %A_Now% 来使用当前本地日期和时间(当天). 对于 DateTime 控件, 可以省略 Value 来让控件不预选日期/时间(如果它在创建时含有这个能力). 对于 MonthCal 控件, 如果控件是多选的, 则可以指定一个日期范围.

UpDown/Slider/Progress: 指定 Value 为控件的新位置. 如果 Value 的首个字符是加号, 则这个数字会被认为是相对于当前位置的偏移. 例如, +10 会给当前位置加上 10 而 +-10(加减十) 会减去 10. 如果新位置在控件的范围之外, 则控件一般会被设置为最接近的有效值.

Tab/DropDownList/ComboBox/ListBox: 指定 Value 为要附加到控件列表末尾的管道符分隔的条目列表. 要替换(覆盖)这个列表, 请加上管道符作为首个字符(例如 |Red|Green|Blue). 要将控件内容清空, 请只指定一个管道符(|). 要预选其中的某个条目, 请在这个条目后包含两个管道符(例如 Red|Green||Blue). 字段间的分隔符可以改变为管道符外的其他字符. 例如 Gui +Delimiter`n 将改变分隔符为换行符而 Gui +DelimiterTab 将改变为 tab(`t).

Tab 控件: 除了上面段落中描述的行为, 一个选项卡的子控件和它们原始的选项卡编号保持关联; 即它们不会和它们选项卡的实际显示名称关联. 因此, 重命名或移除一个选项卡不会改变子控件所属的选项卡编号. 例如, 如果有三个选项卡"Red|Green|Blue", 使用 GuiControl,, MyTab, |Red|Blue 移除第二个选项卡, 则原来和 Green 关联的子控件现在和 Blue 关联. 由于这种特性, 通常只应该移除默认的选项卡. 使用这种方法移除的选项卡以后还可以添加回来, 此时它们会要回原来的控件集合.

ListViewTreeView: 当 SubCommand 为空时不支持它们. 作为替代, 请使用内置的 ListView 函数TreeView 函数.

Text

更改控件的文本/标题.

GuiControl, Text, ControlID , Value

其行为和上面 blank 子命令一样, 除了:

Checkbox/Radio: Value 作为新文本/标题, 即使它为 -1, 0 或 1.

DateTime: Value 作为新日期/时间格式显示到控件中. 如果省略 Value, 则移除所有自定义格式然后使用短日期格式.

ComboBox: Value 作为文本直接放到 ComboBox 的编辑控件.

Move

移动和/或调整控件的大小.

GuiControl, Move, ControlID, Options

Options 中指定一个或多个下列选项字母 : X(相对于 GUI 窗口工作区的 x 坐标, 这是窗口中不包括标题栏, 菜单栏和边框的区域); Y(y 坐标), W(宽度), H(高度). (将每个数字指定为十进制, 而不是十六进制.) 例如:

GuiControl, Move, MyEdit, x10 y20 w200 h100
GuiControl, Move, MyEdit, % "x" VarX+10 "y" VarY+5 "w" VarW*2 "h" VarH*1.5 ; 通过 "% " 前缀使用表达式.

MoveDraw

移动和/或调整控件的大小并重新绘制它所占用的 GUI 窗口的区域.

GuiControl, MoveDraw, ControlID , Options

有关详细信息, 请参阅上面的 Move 子命令. 尽管重复和快速调用这个功能时可能导致不想要的闪烁效果, 不过它解决了某些控件类型如 GroupBoxes 的部分重绘问题. [v1.0.48.04+]: 可以省略最后一个参数来重绘控件而不进行移动或调整大小.

Focus

设置键盘焦点到控件.

GuiControl, Focus, ControlID

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

Disable

禁用控件(灰色显示).

GuiControl, Disable, ControlID

对于选项卡控件, 这样还会禁用选项卡中的所有子控件. 单词 Disable 后可以紧跟着 0 或 1. 零(0) 会产生相反的效果. 例如, DisableDisable%VarContainingOne% 都会禁用控件, 而 Disable%VarContainingZero% 启用控件.

Enable

启用控件.

GuiControl, Enable, ControlID

对于选项卡控件, 这样还会启用选项卡中的所有子控件. 但是, 通过上面的 Disable 子命令明确禁用的任何子控件都将记住该设置, 因此在重新启用选项卡控件后仍然保持禁用状态. 单词 Enable 后可以紧跟着 0 或 1. 零(0) 会产生相反的效果. 例如, EnableEnable%VarContainingOne% 都会启用控件, 而 Enable%VarContainingZero% 禁用控件.

Hide

隐藏控件.

GuiControl, Hide, ControlID

对于选项卡控件, 这样还会隐藏选项卡中的所有子控件. 如果您还想同时禁用控件的快捷键(加下划线的字母), 请使用 Disable 子命令来禁用控件. 单词 Hide 后可以紧跟着 0 或 1. 0(零) 会产生相反的效果. 例如, HideHide%VarContainingOne% 都会隐藏控件, 而 Hide%VarContainingZero% 显示控件.

Show

显示控件.

GuiControl, Show, ControlID

对于选项卡控件, 这样还会显示选项卡中的所有子控件. 单词 Show 后可以紧跟着 0 或 1. 0(零) 会产生相反的效果. 例如, ShowShow%VarContainingOne% 都会显示控件, 而 Show%VarContainingZero% 隐藏控件.

Delete

未实现: 这个子命令还不存在. 作为变通的解决方法, 请使用上面的 Hide 和/或 Disable 子命令, 或使用 Gui Destroy 销毁和重建整个窗口.

Choose

设置 ListBox, DropDownList, ComboBox 或 Tab 控件中的选择对象为第 N 个条目.

GuiControl, Choose, ControlID, N

N 为 1 表示第一个条目, 2 表示第二个, 等等. 如果 N 不是整数, 则使用下面 ChooseString 子命令. [v1.1.06+]: 如果 N 为 0(零), 则移除 ListBox, DropDownList 或 ComboBox 的当前选择对象.

Control Choose 不同, 此子命令不会触发与控件关联的任何 g-标签, 除非在 N 前面加上管道符(即使如此, 也只有在新选择对象与旧的不同时才会触发 g-标签, 至少对 Tab 控件是这样). 例如: GuiControl, Choose, MyListBox, |3.

要同时产生结束事件(双击 ListBox 时), 请用两个前导的管道符而不是一样(这不支持 Tab 控件).

要选择或取消选择多选 ListBox 中的 所有 项目, 请参照此例:

Gui +LastFound  ; 让后面不需要指定 WinTitle.
PostMessage, 0x185, 1, -1, ListBox1  ; 选择所有项目. 0x185 is LB_SETSEL.
PostMessage, 0x185, 0, -1, ListBox1  ; 取消选择所有项目.
GuiControl, Choose, ListBox1, 0  ; 取消选择所有项目(需要 [v1.1.06+]).

ChooseString

设置 ListBox, DropDownList, ComboBox 或 Tab 控件的选择对象为开始部分匹配 String 的条目.

GuiControl, ChooseString, ControlID, String

搜索不区分大小写. 例如, 如果控件包含项目 "UNIX Text", 指定 GuiControl, ChooseString, ControlID, unix 就能选中它了. 还支持管道符和双管道符前缀(请参阅上面的 Choose 子命令以了解详情).

Font

改变控件的字体为它所在窗口当前使用的字体, 大小, 颜色和样式.

GuiControl, Font, ControlID, Options

例如:

Gui, Font, s18 cRed Bold, Verdana  ; 如果需要, 使用这样的一行给窗口设置新的默认字体.
GuiControl, Font, MyEdit  ; 让上面的字体设置对控件生效.

Options

添加或删除各种控件专用通用选项和样式.

GuiControl, +/-Option1 +/-Option2 ..., ControlID , Value

在下面的例子中, 启用 AltSubmit 但同时移除控件的 g-标签:

GuiControl, +AltSubmit -g, MyListBox

在下一个例子中, 会把 OK 按钮设置为新的默认按钮:

GuiControl, +Default, OK

尽管也能识别样式和扩展样式, 但是其中的某些无法在控件创建后应用或移除. 如果至少成功应用一个指定的改变, 则 ErrorLevel 被置为 0. 否则, 它被设置为 1 来表示没有应用任何改变. 即使成功应用了变化, 控件也可能选择忽略它(还是等于没有任何效果).

[v1.1.20+]: 要设置函数对象来处理控件事件, Value 必须为单个变量引用, 如下例所示. 目前不支持其他返回对象的表达式.

GuiControl +g, ControlID, %FuncObj%
GuiControl +g, ControlID, % FuncObj

错误处理

[v1.1.04+]: 此命令失败时会抛出异常. 想了解更多信息, 请参阅运行时错误.

如果指定的窗口/控件不存在或由于其他问题使得命令无法工作, 则 ErrorLevel 被设置为 1. 否则被设置为 0.

备注

要对非默认窗口进行操作, 需要在子命令前加上窗口名称或编号(或 [v1.1.03+] 它的 HWND) 和一个冒号, 例如:

GuiControl, MyGui:Show, MyButton
GuiControl, MyGui:, MyListBox, Item1|Item2

即使 ControlID 为控件的关联变量或 HWND 这也是必须的, 因为任何一个变量可以使用多个 GUI 窗口. 从 [v1.1.20+] 开始, 如果 ControlID 为某个控件的 HWND 时 GUI 的名称可以省略.

一个 GUI 线程是由 GUI 动作启动的. GUI 动作包含从 GUI 窗口的菜单栏选择一个项目或触发其某个 g-标签(例如按下按钮).

GUI 线程的默认窗口名称是运行此线程的窗口名称. 非 GUI 线程的默认窗口编号为 1.

相关

Gui, GuiControlGet, Control

示例

#1

GuiControl,, MyListBox, |Red|Green|Blue  ; 把当前列表替换为新列表.
GuiControl,, MyEdit, New text line 1.`nNew text line 2.
GuiControl,, MyRadio2, 1  ; 选择此单选按钮并关闭同组中其他所有单选按钮.
GuiControl, Move, OK, x100 y200  ; 移动 OK 按钮到新位置.
GuiControl, Focus, LastName  ; 设置键盘焦点到变量名或文本为 "LastName" 的控件.