# GuiControl

对一个图形用户界面窗口的控件做出种种改变。

GuiControl, Sub-command, ControlID [, Param3]

#### 参数

Sub-command | 参见下面的列表。
ControlID | 如果目标控件有一个关联的变量，那么将变量名指定为 ControlID (这个方法优先于后面描述的方法)。由于这个原因，通常最好给每一个之后要被 GuiControl 或者 GuiControlGetit 存取的控件指定一个变量名，即使那个控件没有输入功能(例如 GroupBox 或者 Text)。 如若不然，ControlID 可以是 ClassNN (控件的类名和实例号) 或者控件的名字/文本，这两者都可以通过 Window Spy(窗体侦探) 来决定。当使用名字/文本时，匹配的行为可以由 SetTitleMatchMode 决定。注意：一个图片控件的文件名字 (和控件创建时指定的一样) 可以当做 ControlID 使用。
Param3 | 除了下面 sub-commands 列表中说明的，这个参数是被省略的。

#### ErrorLevel

如果指定的窗体/控件不存在或者其他一些错误导致命令不能工作，ErrorLevel 被设为 1 。否则，它被设为 0 。

#### Sub-commands

(Blank) (空白): 将 Sub-command 留空，然后通过 Param3 给予控件新的内容。比如：

Picture: Param3 应当是要加载的图片的文件名 (支持的文件类型参见 Gui Picture)。在文件名的前面可以指定零个或多个下面的参数：*wN (宽度 N), *hN (高度 N), 和 *IconN (DLL 或者 EXE 文件中的图标的组号)。下面的例子中，第二个图标组中的默认的图标载入的宽度是 100 ，通过 "keep aspect ratio" 设置自动高度: GuiControl,, MyPic, *icon2 *w100 *h-1 C:\My Application.exe。指定 *w0 *h0 来使用图像的实际高度和宽度。如果 *w 和 *h 被省略，图像将被缩放来适应当前控件的尺寸。当从多图标的 .ICO 文件载入图标的时候，指定宽度和高度可以决定哪个图标将被载入。注意：在最后一个选择项和文件名之间只能使用一个空格或者制表符；其他任何空格或者制表符将被当做文件名的一部分。

Text/Button/GroupBox/StatusBar: 对于 Param3 指定控件的新文本。因为控件不能自动改变大小，所以如果控件需要变宽，请使用 GuiControl, Move, MyText, W300 。对于 StatusBar，这个选项仅设置第一部分的文本。(想要更灵活的实现请使用 SB_SetText() )。

Edit: 为了正常显示 Param3 中缺少之前回车 (`r) 的换行 (`n)，它被自动的转换为 CR+LF (`r`n)。然而，这在通常情况下无需考虑，因为 "Gui Submit" 和 "GuiControlGet OutputVar" 命令能自动撤销这一替换，使 CR+LF 变回 LF (`n)。

Hotkey: Param3 可以为空来清除控件，或者一组有键名的修改器。例如：^!c, ^Numpad1, +Home。支持的修改器仅有 ^ (Control), ! (Alt), 和 + (Shift)。可用键名请参见 key list。

Checkbox: Param3 可以为 0 来不选择按钮，1 来选择，或者 -1 来给它一个灰色的检查标志。另外，Param3 默认是控件的新标题/文本。关于如何重写这一行为，参考下面的 Text 。

Radio: 和上面的 Checkbox 类似。但是，如果单选按钮是选中的 (开启) 而且它是一个单选按钮组中的一项，那么组中其他的单选按钮自动即为未选中的。想要选中一个只有一个变量的单选按钮组中的一个新的按钮并且此按钮不是那个变量直接联系的，请指定按钮的 ControlID 为它的 名字/文本 。

DateTime/MonthCal: 为 Param3 指定一个格式为 YYYYMMDDHH24MISS 的日期-时间标记。指定 %A_Now% 来使用当前的日期和时间 (当天)。对于日期时间控件，Param3 可以省略来使控件不选中日期/时间 (如果它在创建时有 that ability (这一能力))。对于 MonthCal 控件，如果它是 multi-select (多选择的)，那么可以指定一个范围。

UpDown/Slider/Progress: Param3 应当是控件的新位置。如果 Param3 的第一个符号是加号，这个数字就被认为是相对当前位置的偏移值，例如，+10 把位置增加10，而 +-10 (加负十) 把位置减去10。如果新位置在控件的范围之外，控件通常被设置在最近的合法值处。

Tab/DropDownList/ComboBox/ListBox: Param3 应当包含一个管道符分隔的要加在控件后的条目的列表。要替换 (重写) 这个列表，在第一个字符前加上一个管道符 (例如 |Red|Green|Blue)。要将控件置空，只需指定一个管道符 (|)。要预先选定其中一个条目，在它之后加上两个管道符 (例如 Red|Green||Blue)。条目之间的分隔符可以为其他字符，不一定是管道符。比如 Gui +Delimiter`n 可以将它改为换行而 Gui +DelimiterTab 将它改为制表符。

Tab controls: 除了以上段落描述的行为，一个标签页的子控件和它们原始的标签编号相关联；也就是说，它们永远不与它们的标签页的名字关联。因此，重命名或者删除一个标签页不会改变子控件所属的标签页的编号。例如，有三个标签页 "Red|Green|Blue"，第二个标签页通过 "GuiControl,, MyTab, |Red|Blue" 被移除，原来和 Green 标签页联系的子控件不会和 Blue 标签页关联。因为这一行为，通常情况下只有最后一个标签页才能被移除。用这种方法移除的标签随后还可以再被加进来，那时它们会重新声明原来的控件。

ListView 和 TreeView: 当 Sub-command 为空时不支持这两个参数。做为替代，请使用内建的 ListView functions 和 TreeView functions。

GuiControl, Text: 除了下面这几个，效果和上面的一样：
Checkbox/Radio: Param3 被当做新的文本/标题，即使它是 -1, 0, 或 1。
DateTime: Param3 被当做控件中显示的新的 date/time format (日期/时间 格式)。如果 Param3 被省略，任何自定义格式将被移除，短日期格式被使用。
ComboBox: Param3 被当做文本而直接放在下拉列表框的编辑控件中。

GuiControl, Move: 移动 和/或 缩放控件。在 Param3 中指定下面一个或几个可选字母：X (相对于窗口中用户区域的 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 ; 通过 "% " 前缀使用 expression (表达式) 。

GuiControl, MoveDraw: 除了上面 "Move" 的功能，它还重画控件占据的窗口位置。尽管当重复和快速调用时可能会产生闪烁，它解决了在特定控件中绘画的问题，比如在 GroupBoxes 中。

GuiControl, Focus: 将键盘的焦点设置在控件上。要使有效，窗口通常不能被最小化或者被隐藏。

GuiControl, Enable / Disable: 使控件有效或者失效(灰化)。对于标签页控件，此选项还会使标签的子控件有效或失效。然而，任何通过 "GuiControl Disable" 显示禁止的控件在它的标签页被重新生效后仍然保持失效状态。单词 Disable 或者 Enable 后面可以可选的紧跟着 Zero 或 One。Zero 产生相反的效果。例如，Enable 和 Enable%VarContainingOne% 都使控件生效，但是 Enable%VarContainingZero% 将使它失效。

GuiControl, Hide / Show: 隐藏或者显示控件。对于标签页控件将会隐藏或显示标签下所有的子控件。另外如果你还想同时禁用控件的快捷键 (加下线字母)，通过 "GuiControl Disable" 禁用控件。单词 Hide 或者 Show 后面可以可选的紧跟着 0 or 1。产生相反的效果。例如，Show 和 Show%VarContainingOne% 都显示控件，但是 Show%VarContainingZero% 将隐藏它。

GuiControl, Delete (还没有实现): 这个子命令现在还不存在。对于一个工作区，使用上面的 Hide 和/或 Disable，或者通过 Gui Destroy 销毁或重建整个窗口。

GuiControl, Choose, ControlID, N: 设置列表框，下拉列表，复选框或者标签页中的选区为第 N 个入口。第一个入口 N 对应为 1，第二个入口对应为 2，依次类推 (如果 N 不是整数，下面描述的 ChooseString 方法将被作为替代使用)。与 Control Choose 不同，这个子命令不会触发任何与控件关联的 g-label ，除非 N 之前有一个管道符 (即使这样，g-label 仅在新的选区和旧选区不同的情况下被触发，至少对 Tab controls 是这样)。例如：GuiControl, Choose, MyListBox, |3.

此外要产生一个结束的事件，(例如在列表框中的双击)，请包含两个管道符而不是一个(不支持标签页)。

要选择或者取消选择 multi-select ListBox (多选列表框)中的所有 选项，参考下面的例子：

    Gui +LastFound  ; 避免指定下面的 WinTitle 的需要。
    PostMessage, 0x185, 1, -1, ListBox1  ; 选择所有选项。0x185 表示 LB_SETSEL。
    PostMessage, 0x185, 0, -1, ListBox1  ; 取消选择所有选项。

GuiControl, ChooseString, ControlID, String: 设置列表框，下拉列表，复选框或者标签页中主要部分和 String 匹配的选区(选择)为入口。搜索不区分大小写。例如，如果一个控件包含项 "UNIX Text"，指定单词 unix (小写) 就足以选中它了。支持管道符和双管道符 (详细请参考上面的 "Choose" )。

GuiControl, Font: 把控件的字体改变为它所在窗口的当前使用的字体，字号，颜色和样式。例如：

    Gui, Font, s18 cRed Bold, Verdana  ; 如果需要，使用类似这样的排列方式给窗口指定一个新的默认字体。
    GuiControl, Font, MyEdit  ; 使上面的字体对控件生效。

GuiControl, +/-Option1 +/-Option2 ... : 增加或者删除不同的选项或样式。所有的 GUI 选项 (control-specific 和 general) 都将被识别。下面的例子中， AltSubmit 选项被启用但是控件的 g-label 被删除： GuiControl, +AltSubmit -g, MyListBox

下个例子中，OK 按钮被设为新的默认按钮：
GuiControl, +Default, OK

尽管 styles (样式) 和 extended styles (扩展的样式) 也会被识别，它们中一些在控件创建以后不能被应用或者被删除。如果被指定的改变中至少一个被成功应用，ErrorLevel 被设为 0 。否则，它被设为 1 来指示没有应用任何改变。即使一个改变被成功应用，控件仍然可能选择忽视它。

#### 注意

想要根据窗口号码而不是默认窗口进行操作(参加下面)，在子命令前面加上数字和一个冒号，如下面的例子所示：
GuiControl, 2:Show, MyButton
GuiControl, 2:, MyListBox, Item1|Item2

当任何作为 GUI 操作结果的线程被启动时，一个 GUI thread (线程) 被定义。GUI 操作包括选择 GUI 窗口的菜单栏的一项，或者触发它的 g-labels 中的一项(比如按下一个按钮)。

GUI 线程的默认窗口号码是启动线程的窗口号码。非GUI 线程使用 1 做为它们的默认窗口号码。

#### 相关命令

Gui, GuiControlGet, Control

#### 示例

    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" 的控件上。