# GuiControl 对象

    class Gui.Control extends Object

提供用于修改 GUI 控件并检索有关控件的信息的接口. Gui.Add, Gui.__Item 和 GuiCtrlFromHwnd 返回这种类型的对象.

下面使用 "GuiCtrl" 作为任何 `Gui.Control` 类实例的占位符.

`Gui.Control` 作为所有 GUI 控件的基类, 但是每种类型的控件都有自己的类. 以下一些方法是由适当的类的原型, 或 `Gui.List` 基类定义的. 有关完整列表, 请参阅内置的类.

除了从 Object 继承的方法和属性外, GuiControl 对象还具有以下预定义的方法和属性.

## 目录

- 方法:
  - Add: 在列表框, 下拉列表, 组合框或选项卡控件的当前列表中追加指定的项.
  - Choose: 设置 ListBox, DropDownList, ComboBox 或 Tab 控件中的选择为指定值.
  - Delete: 删除 ListBox, DropDownList, ComboBox 或 Tab 控件的指定项或所有项.
  - Focus: 设置键盘焦点到控件上.
  - GetPos: 获取控件的位置和大小.
  - Move: 移动和/或调整控件的大小.
  - OnCommand: 注册一个函数或方法, 当通过 WM_COMMAND 消息接收到控件通知时调用.
  - OnEvent: 注册给定事件触发时要调用的函数或方法.
  - OnNotify: 注册一个函数或方法, 当通过 WM_NOTIFY 消息接收到控件通知时调用.
  - Opt: 为控件的外观和行为设置各种选项和样式.
  - Redraw: 重绘控件所占的 GUI 窗口区域.
  - SetFont: 设置控件的字体字体, 大小, 样式和/或颜色.
  - SetFormat: 设置 DateTime 控件的显示格式.
  - UseTab: 导致随后添加的控件属于选项卡控件的指定选项卡.
- 属性:
  - ClassNN: 检索控件的 ClassNN.
  - Enabled: 检索控件当前交互状态, 或启用或禁用(灰色) 控件.
  - Focused: 检索控件当前焦点状态.
  - Gui: 检索控件的 Gui 父控件.
  - Hwnd: 检索控件的 HWND.
  - Name: 检索或设置控件的显式名称.
  - Text: 检索或设置控件的文本/标题.
  - Type: 检索控件的类型.
  - Value: 检索控件的值或设置新内容到一个包含值的控件中.
  - Visible: 检索控件的当前可见状态, 或显示或隐藏它.
- 备注:
  - Redraw: 关于控件重绘行为的性能相关注释.

## 方法

### Add

将列表项目添加到 ListBox, DropDownList 或 ComboBox, 或将标签添加到 Tab 控件中.

    GuiCtrl.Add(Items)

Items

  类型: Array(数组)

  要插入到控件列表末尾的字符串数组(例如 `["Red","Green","Blue"]`). 要替换(覆盖) 列表, 请事先使用 GuiCtrl.Delete.

使用 GuiCtrl.Choose 选择一个项目.

相关: ListView.Add, TreeView.Add

### Choose

设置 ListBox, DropDownList, ComboBox 或 Tab 控件中的选择为指定值.

    GuiCtrl.Choose(Value)

Value

  类型: 整数或字符串

  参数为 1 表示第一个条目, 2 表示第二个, 等等.

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

  如果 Value 为零或为空, 则当前选择将被移除.

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

    PostMessage 0x185, 1, -1, ListBox  ; 选择所有项目. 0x185 是 LB_SETSEL.
    PostMessage 0x185, 0, -1, ListBox  ; 取消选择所有项目.
    ListBox.Choose(0)  ; 取消选择所有项目.

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

### Delete

删除 ListBox, DropDownList, ComboBox 或 Tab 控件的指定项或所有项.

    GuiCtrl.Delete(Value)

Value

  类型: 整数

  参数为 1 表示第一个条目, 2 表示第二个, 等等. 如果省略, 则删除所有条目.

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

相关: ListView.Delete, TreeView.Delete

### Focus

设置键盘焦点到控件上.

    GuiCtrl.Focus()

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

### GetPos

获取控件的位置和大小.

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

每个参数都应该是一个变量引用, 在其中存储各自的坐标. 位置是相对于 GUI 窗口的客户端区域而言的, 客户端区域是不包括标题栏, 菜单栏和边框的区域.

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

示例:

    MyEdit.GetPos(&x, &y, &w, &h)
    MsgBox "The X coordinate is " x ". The Y coordinate is " y ". The width is " w ". The height is " h "."

### Move

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

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

X, Y

  类型: 整数

  新的位置, 相对于 GUI 窗口的客户端区域, 即不包括标题栏, 菜单栏, 和边框的区域.

Width, Height

  类型: 整数

  新的尺寸.

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

示例:

    MyEdit.Move(10, 20, 200, 100)
    MyEdit.Move(VarX+10, VarY+5, VarW*2, VarH*1.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

  类型: 字符串

  控件专用或通用选项和样式.

在下面的例子中, 该控件被禁用, 并且它的 background 恢复为系统默认值:

    MyEdit.Opt("+Disabled -Background")

在下一个例子中, OK 按钮被变成了新的默认按钮:

    OKButton.Opt("+Default")

虽然样式和扩展样式也被识别, 但其中一些样式在控件创建后无法应用或删除. 即使成功应用了某项更改, 控件也可能选择忽略它.

### Redraw

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

    GuiCtrl.Redraw()

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

### SetFont

设置控件的字体字体, 大小, 样式和/或颜色.

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

    GuiCtrl.SetFont(Options, FontName)

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

### SetFormat

设置 DateTime 控件的显示格式.

    GuiCtrl.SetFormat(Format)

有关详情, 请参阅 SetFormat.

### UseTab

使随后添加的控件属于 Tab 控件的指定标签.

    GuiCtrl.UseTab(Value, ExactMatch)

Value

  类型: 整数或字符串

  参数为 1 表示第一个条目, 2 表示第二个, 等等. 如果 Value 不是一个整数, 前面部分与 Value 匹配的标签将被使用. 搜索不区分大小写. 例如, 如果一个控件包含 "UNIX Text" 标签, 指定单词 unix(小写) 就可以使用它. 如果 Value 为 0, 是一个空白字符串或被省略, 随后的控件将被添加到 Tab 控件之外.

ExactMatch

  类型: 布尔值

  如果该参数为 true, Value 必须完全匹配, 但不区分大小写.

## 属性

### ClassNN

检索控件的 ClassNN.

    ClassNN := GuiCtrl.ClassNN

### Enabled

检索控件当前交互状态, 或启用或禁用(灰色) 控件.

    RetrievedState := GuiCtrl.Enabled

    GuiCtrl.Enabled := NewState

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

### Focused

检索控件当前焦点状态.

    RetrievedState := GuiCtrl.Focused

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

### Gui

检索控件的父 GUI 窗口的 Gui 对象.

    GuiObj := GuiCtrl.Gui

### Hwnd

检索控件的窗口句柄(HWND).

    Hwnd := GuiCtrl.Hwnd

控件的 HWND, 通常与 PostMessage, SendMessage 和 DllCall 一起使用.

### Name

检索或设置控件的名称.

    RetrievedName := GuiCtrl.Name

    GuiCtrl.Name := NewName

控件的名称可以与 Gui.__Item 一起使用, 以检索 GuiControl 对象. 对于大多数具有输入功能的控件, 该名称也被 Gui.Submit.

### Text

检索或设置控件的文本/标题.

    RetrievedText := GuiCtrl.Text

    GuiCtrl.Text := NewText

注意: 如果控件没有可见的标题文本和文本值, 则此属性对应于控件的隐藏标题文本(如 ControlGetText/ControlSetText).

标题/显示文本: Text 属性可检索或设置以下控件类型的标题/显示文本: Button, Checkbox, Edit, GroupBox, Link, Radio, Text. 由于控件不会自动展开, 请使用 `GuiCtrl.Move("w300")` 或类似的方法.

DateTime: Text 属性检索了控件显示的格式化文本. 不支持为控件指定格式化的日期/时间字符串. 要更改显示的日期/时间, 请为 GuiCtrl.Value 指定一个 YYYYMMDDHH24MISS 格式的日期-时间戳.

Edit: 与其他控件一样, 文本按原样检索或设置; 不用预先进行尾转换. 要检索或设置多行 Edit 控件的文本, 同时在 ``r`n` 和 ``n` 之间进行转换, 请使用 GuiCtrl.Value.

StatusBar: Text 属性仅检索或设置第一部分的文本(使用 SB.SetText 可获得更大的灵活性).

List 项目文本: Text 属性为以下控件类型检索或设置当前选中的项目/标签: Tab, DropDownList, ComboBox, ListBox.

NewText 应该是要选择的项目/标签的全部文本(不区分大小写).

对于 ComboBox, 如果没有选中的项目, 则会检索控件编辑栏中的文本. 对于其他控件, RetrievedText 为空/空白. 同样, 如果 NewText 为空/空白, 则当前项/标签将被取消选择.

对于一个多选 ListBox, RetrievedText 是一个数组. NewText 不能是一个数组, 但如果多个项目匹配, 它们都会被选择. 要用不同的文本选择多个项目, 请重复调用 GuiCtrl.Choose.

要根据项目的位置编号而不是文本选择项目, 请使用 GuiCtrl.Value.

### Type

检索控件的类型.

    RetrievedType := GuiCtrl.Type

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

### Value

检索或设置控件的内容.

    RetrievedValue := GuiCtrl.Value

    GuiCtrl.Value := NewValue

注意: 如果控件不包含值, RetrievedValue 将是空白, 并且赋值 NewValue 将引发错误. 无效的值会抛出异常.

以下控件类型包含值:

Picture

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

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

Text

RetrievedValue 是 Text 控件的的文本/标题.

NewValue 是控件的新文本. 由于控件不会自动展开, 所以如果需要扩大控件, 请使用 `GuiCtrl.Move("w300")`.

Edit

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

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

要检索或设置文本, 而不将 `n 转换为 `r`n, 请使用 GuiCtrl.Text.

Hotkey

如果 Hotkey 控件中有热键, 则 RetrievedValue 为修饰符和键名; 否则为空. 例如: `^!C`, `^Home`, `+^NumpadHome`.

NewValue 可以是一组修饰符和键名, 或空白以清空该控件. 例如: `^!c`, `^Numpad1`, `+Home`. 支持的修饰符仅包含 ^(Control), !(Alt), 和 +(Shift). 请参阅按键列表了解可用的按键名称.

Checkbox / Radio

如果选中了 Checkbox 或 Radio 控件, 则 RetrievedValue 为 1, 如果未选中, 则为 0, 如果有灰色复选标记, 则为 -1.

NewValue 可以是 0 来取消选中按钮, 1 来选中它, 或者 -1 来给它一个灰色的复选标记. 对于 Radio 按钮, 如果有一个按钮被选中(打开) 并且它是一个多个单选按钮组的成员, 那么该组中的其他单选按钮将被自动取消选中.

如果要获取或设置控件的文本/标题, 请使用 GuiCtrl.Text.

DateTime / MonthCal

RetrievedValue 是当前在 DateTime 或 MonthCal 控件中选择的 YYYYMMDDHH24MISS 格式的日期-时间戳.

NewValue 是 YYYYMMDDHH24MISS 格式的日期-时间戳. 指定 `A_Now` 来使用当前日期和时间(今天). 对于 DateTime 控件, NewValue 可以是一个空字符串, 以使该控件没有选择日期/时间(如果它在创建时含有这个能力). 对于 MonthCal 控件, 如果控件是多选的, 则可以指定一个日期范围.

UpDown / Slider / Progress

RetrievedValue是 UpDown, Slider 或 Progress 控件的当前位置.

NewValue 是控件的新位置, 例如 `MySlider.Value := 10`. 要调整一个相对的数值, 请使用运算符 `+=`, `-=`, `++` 或 `--` 代替 `:=`. 如果新的位置超出了控件的范围, 控件一般会被设置为最近的有效值.

Tab / DropDownList / ComboBox / ListBox

RetrievedValue 是当前选中的项目/标签在 Tab, DropDownList, ComboBox 或 ListBox 控件中的位置. 如果没有选择, 则返回 0. 如果在 ComboBox 中输入了文本, 则使用第一个匹配文本的项目. 如果没有匹配的项目, 即使控件中有文本, 结果也是 0. 对于一个多选 ListBox, 结果是一个数字数组(如果没有选择任何项目, 则为空).

NewValue 是要选择的单个项目/标签的位置, 或者为零来清除当前的选择(即使对 Tab 控件也有效). 要选择多个项目, 请重复调用 GuiCtrl.Choose.

要获取或设置选中项的文本而不是其位置, 请使用 GuiCtrl.Text.

ActiveX

RetrievedValue 是 ActiveX 控件的 ActiveX 对象. 例如, 如果控件是用文本 Shell.Explorer 创建的, 这是一个 WebBrowser 对象. 每次都返回相同的包装器对象.

### Visible

检索控件的当前可见状态, 或显示或隐藏它.

    RetrievedState := GuiCtrl.Visible

    GuiCtrl.Visible := NewState

对于 Tab 控件, 这也将显示或隐藏该 Tab 的所有子控件. 如果您还想阻止一个控件的快捷键(下划线字母) 工作, 通过 `GuiCtrl.Enabled := false` 禁用该控件.

## 备注

### Redraw

当向控件(如 ListView, TreeView 或 ListBox) 添加大量项目时, 可以通过防止在进行更改时重绘控件来提高性能. 这是通过在添加项目之前使用 `GuiCtrl.Opt("-Redraw")` 和在添加项目之后使用 `GuiCtrl.Opt("+Redraw")` 来实现的. 对控件的更改, 如果在禁用重绘前还未显示, 一般在重绘重新启用后才会显示.

出于性能原因, 即使启用了重绘, 对控件内容的更改通常也不会立即重绘该控件. 相反, 当程序检查其内部消息队列时, 控件的部分区域被 "失效", 通常在短暂延迟后重新绘制. 脚本可以通过调用 `Sleep -1` 立即强制执行此操作.

dftg