# MsgBox

在含有一个或多个按钮(例如 "是" 和 "否") 的小窗口中显示指定的文本.

    MsgBox Text, Title, Options
    Result := MsgBox(Text, Title, Options)

## 参数

Text

  类型: 字符串

  要在消息框中显示的文本. 如果未设置或省略, 如果 "OK" 是存在的唯一按钮, 则默认文本是 "Press OK to continue.", 否则为空.

  可以使用转义序列来表示特殊字符. 例如, `n 表示换行符, 它结束当前行并开始一个新行. 因此, 使用 `text1`n`ntext2` 会在 text1 和 text2 之间添加一个空行.

  如果 Text 较长, 可以通过延续片段的方法将其分解成较短的几行, 这样可以增加可读性和可维护性.

Title

  类型: 字符串

  如果未设置或省略, 则默认为 A_ScriptName 的当前值. 否则, 请指定消息框的标题.

Options

  类型: 字符串

  如果未设置或省略, 则默认为 0(只显示 OK 按钮)). 否则, 从下表中指定值的组合(总和) 或一个或多个选项的字符串, 以指示消息框的类型和可能的按钮组合.

  此外, 还可以指定以下零个或多个选项:

  Owner: 要为消息框指定所有者窗口, 请使用单词 Owner 后接 HWND(窗口 ID).

  T: 超时. 如果用户在指定的时间内没有关闭消息框, 要让消息框自动关闭, 请使用字母 T 后接超时秒数, 可以包含小数点. 如果这个值超过 2147483(24.8 天), 将被设置为 2147483. 如果消息框超时, 返回值为单词 Timeout.

## Options 参数的值

Options 参数可以是以下组的数字值的组合(和), 这些值直接传递给操作系统的 MessageBox 函数, 也可以是由至少一个空格或制表符分隔的不区分大小写的选项组成的字符串. 字符串中还可以包含一个或多个数字选项.

### 组 #1: 按钮

若要指定在消息框中显示的按钮, 请添加以下值之一:

功能 | 十进制 | 十六进制 | 字符串
--- | --- | --- | ---
OK(即, 仅显示一个 OK(确认) 按钮) | 0 | 0x0 | `OK` 或 `O`
确认和 Cancel(取消) | 1 | 0x1 | `OKCancel`, `O/C` 或 `OC`
Abort(中止(A)), Retry(重试(R)) 和 Ignore(忽略(I)) | 2 | 0x2 | `AbortRetryIgnore`, `A/R/I` 或 `ARI`
Yes(是(Y)), No(否(N)) 和取消 | 3 | 0x3 | `YesNoCancel`, `Y/N/C` 或 `YNC`
是(Y) 和否(N) | 4 | 0x4 | `YesNoCancel`, `Y/N/C` 或 `YNC`
重试(R) 和取消 | 5 | 0x5 | `RetryCancel`, `R/C` 或 `RC`
取消, Try Again(重试(T)) 和 Continue(继续(N)) | 6 | 0x6 | `CancelTryAgainContinue`, `C/T/C` 或 `CTC`

### 组 #2: 图标

要在消息框中显示一个图标, 请添加以下值之一:

功能 | 十进制 | 十六进制 | 字符串
--- | --- | --- | ---
停止/错误图标. | 16 | 0x10 | `Iconx`
问号图标. | 32 | 0x20 | `Icon?`
惊叹号图标. | 48 | 0x30 | `Icon!`
星号图标(信息). | 64 | 0x40 | `Iconi`

### 组 #3: 默认按钮

若要指定默认按钮, 请添加以下值之一:

功能 | 十进制 | 十六进制 | 字符串
--- | --- | --- | ---
使第二个按钮成为默认按钮. | 256 | 0x100 | `Default2`
使第三个按钮成为默认按钮. | 512 | 0x200 | `Default3`
使第四个按钮为默认的. 需要存在 Help(帮助) 按钮 | 768 | 0x300 | `Default4`

### 组 #4: 模式

若要指定对话框的模式, 请添加以下值之一:

功能 | 十进制 | 十六进制 | 字符串
--- | --- | --- | ---
系统模式(始终置顶) | 4096 | 0x1000 | N/A
任务模式 | 8192 | 0x2000 | N/A
置顶(WS_EX_TOPMOST 样式) (和系统模式类似, 但省略了标题栏图标) | 262144 | 0x40000 | N/A

### 组 #5: 其他选项

若要指定其他选项, 请添加以下值中的一个或多个:

功能 | 十进制 | 十六进制 | 字符串
--- | --- | --- | ---
添加帮助按钮(请参阅下面的备注) | 16384 | 0x4000 | N/A
让文本右对齐显示. | 524288 | 0x80000 | N/A
用于希伯来语/阿拉伯语的从右向左的阅读顺序. | 1048576 | 0x100000 | N/A

## 返回值

类型: 字符串

该函数返回以下字符串中之一来表示用户按下了哪个按钮:

- OK
- Cancel
- Yes
- No
- Abort
- Retry
- Ignore
- TryAgain
- Continue
- Timeout(即, 如果消息框超时, 则返回单词 "timeout")

如果对话框无法显示, 返回空字符串. 这通常只发生在 MsgBox 达到限制的情况下, 但也可能是特殊情况.

## 错误处理

失败时抛出 Error, 如选项无效, 达到 MsgBox 限制, 或由于其他原因无法显示消息框.

## 备注

消息框通常看起来像这样:

要确定用户按下了哪个按钮, 请使用函数的返回值. 例如:

    Result := MsgBox("Would you like to continue? (press Yes or No)",, "YesNo")
    if Result = "Yes"
        MsgBox "You pressed Yes."
    else
        MsgBox "You pressed No."

    if MsgBox("Retry or cancel?",, "R/C") = "Retry"
        MsgBox("You pressed Retry.")

若要自定义按钮的名称, 请参阅Changing MsgBox's Button Names.

注意: 当消息框窗口处于活动状态时, 按下 `Ctrl`+`C` 将复制其中的文本到剪贴板. 这适用于所有的消息框, 而不仅是 AutoHotkey 生成的那些.

GUI 窗口当作 MsgBox: 通过使用 OwnDialogs 选项的方法 GUI 窗口可以显示为 modal(模式) 消息框. 模式 消息框在其消失之前会阻止用户与原来的 GUI 窗口进行交互. 此时, 不需要指定上表中的系统模式或任务模式选项.

当 OwnDialogs 选项 无效 时, 任务模式选项(8192) 可用于禁用所有脚本的窗口, 直到用户取消消息框.

如果指定了 `OwnerHWND` 选项, 它将优先于任何其他设置. HWND 可以是任何窗口的 HWND, 即使不是脚本所拥有的窗口.

帮助按钮: 在 Options 中使用了帮助按钮选项(16384) 时, 只有符合下面两个条件, 那么按下帮助按钮才会有效果:

1. 消息框是使用 OwnDialogs 选项的方法为 Gui 窗口所有.
2. 脚本正在监控 WM_HELP 消息(0x0053). 例如: `OnMessage(0x0053, "WM_HELP")`. 当 WM_HELP 函数被调用时, 可能会通过诸如显示另一个窗口或消息框等方式引导用户.

关闭按钮(在消息框的标题栏): 由于消息框窗口是操作系统内置的特性, 所以它的 X 按钮只有在某些按钮存在时才会被启用. 如果只有一个 OK(确认) 按钮, 点击 X 按钮等同于点击 OK 按钮. 否则, X 按钮将被禁用, 除非有一个取消按钮, 在这种情况下, 点击 X 按钮就等同于按下取消.

最大持续调用数 7: 显示消息框的线程通常可以被中断, 从而允许新线程在前一个调用返回之前显示自己的消息框. 最多允许对 MsgBox 进行 7 次进行中的调用, 任何第 7 次以后的调用都会抛出 Error. 注意, 在中断的线程中, 对 MsgBox 的调用只有在线程恢复后才能返回.

## 相关

InputBox, FileSelect, DirSelect, ToolTip, Gui 对象

## 示例

显示一个带有特定文字的信息框. 一种快速简单的信息显示方式. 用户可以按确定按钮关闭信息框并继续执行.

    MsgBox "This is a string."

显示一个带有特定文本和标题的消息框.

    MsgBox "This MsgBox has a custom title.", "A Custom Title"

显示一个带有默认文本的消息框. 主要用于调试目的, 例如快速设置脚本中的断点.

    MsgBox ; "Press OK to continue."

显示一个带有特定文本, 标题和信息图标的消息框. 此外, 延续片段用于更清晰地显示多行文本.

    MsgBox "
      (
        第一个参数显示为信息.
        第二个参数成为窗口标题.
        第三个参数决定了消息框的类型.
      )", "Window Title", "iconi"

使用返回值来确定用户在消息框中按了哪个按钮. 注意, 在这种情况下, MsgBox 函数调用必须用括号来指定.

    result := MsgBox("Do you want to continue? (Press YES or NO)",, "YesNo")
    if (result = "No")
        return

使用 T(超时) 选项, 在一定秒数后自动关闭消息框.

    result := MsgBox("This MsgBox will time out in 5 seconds.  Continue?",, "Y/N T5")
    if (result = "Timeout")
        MsgBox "You didn't press YES or NO within the 5-second period."
    else if (result = "No")
        return

在消息中包含一个变量或子表达式. 另请参阅: 连接

    var := 10
    MsgBox "The initial value is: " var
    MsgBox "The result is: " var * 2
    MsgBox Format("The result is: {1}", var * 2)

dftg