# 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): 将新内容放入控件.
- Text: 更改控件的文本/标题.
- Move: 移动和/或调整控件的大小.
- MoveDraw: 移动和/或调整控件的大小并重新绘制它所占用的区域.
- Focus: 设置键盘焦点到控件.
- Disable: 禁用控件(灰色显示).
- Enable: 启用控件.
- Hide: 隐藏控件.
- Show: 显示控件.
- Delete: 还没有实现.
- Choose: 在多项目控件中选择指定的项目号.
- ChooseString: 在一个多项目控件中选择一个项目, 该项目的主要部分匹配一个字符串.
- Font: 更改控件的字体, 大小, 颜色和样式.
- Options: 添加或删除各种控件专用的或通用的选项和样式.

### (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 Submit` 和 `GuiControlGet OutputVar` 命令会自动将 CR+LF 替换为 LF(`n) 来撤销这种转换.

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

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

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

DateTime/MonthCal: 指定 Value 为 YYYYMMDDHH24MISS 格式的时间戳. 指定 `%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 关联. 由于这种特性, 通常只应该移除默认的选项卡. 使用这种方法移除的选项卡以后还可以添加回来, 此时它们会要回原来的控件集合.

ListView 和 TreeView: 当 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) 会产生相反的效果. 例如, `Disable` 和 `Disable%VarContainingOne%` 都会禁用控件, 而 `Disable%VarContainingZero%` 启用控件.

### Enable

启用控件.

    GuiControl, Enable, ControlID

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

### Hide

隐藏控件.

    GuiControl, Hide, ControlID

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

### Show

显示控件.

    GuiControl, Show, ControlID

对于选项卡控件, 这样还会显示选项卡中的所有子控件. 单词 Show 后可以紧跟着 0 或 1. 0(零) 会产生相反的效果. 例如, `Show` 和 `Show%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

例如:

    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 为控件的关联变量这也是必需的, 因为任何一个变量可以在多个 GUI 窗口中使用. 从 [v1.1.20+] 开始, 如果 ControlID 为某个控件的 HWND, 则可以省略 GUI 的名称.

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

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

## 相关

Gui, GuiControlGet, Control

## 示例

用一个新的列表替换当前列表.

    GuiControl,, MyListBox, |Red|Green|Blue

将新的文本放入编辑控件中.

    GuiControl,, MyEdit, New text line 1.`nNew text line 2.

打开一个单选按钮并关闭其组中的所有其他按钮.

    GuiControl,, MyRadio2, 1

移动 OK 按钮到新的位置.

    GuiControl, Move, OK, x100 y200

设置键盘焦点到其变量名或文本为 "LastName" 的控件上.

    GuiControl, Focus, LastName

dftg