MessageBoxW 函数 (winuser.h)

显示一个模式对话框，其中包含一个系统图标、一组按钮和一条简短的应用程序特定消息，例如状态或错误信息。 消息框返回一个整数值，指示用户单击的按钮。

语法

int MessageBoxW(
  [in, optional] HWND    hWnd,
  [in, optional] LPCWSTR lpText,
  [in, optional] LPCWSTR lpCaption,
  [in]           UINT    uType
);

parameters

[in, optional] hWnd

类型：HWND

要创建的消息框的所有者窗口的句柄。 如果此参数为 NULL，则消息框没有所有者窗口。

[in, optional] lpText

类型： LPCTSTR

要显示的消息。 如果字符串由多行组成，则可以在每行之间使用回车符和/或换行符分隔行。

[in, optional] lpCaption

类型： LPCTSTR

对话框标题。 如果此参数为 NULL，则默认标题为 Error。

[in] uType

类型： UINT

对话框的内容和行为。 此参数可以是以下标志组的标志的组合。

若要指示消息框中显示的按钮，请指定以下值之一。

值	含义
MB_ABORTRETRYIGNORE 0x00000002L	消息框包含三个按钮： 中止、 重试和 忽略。
MB_CANCELTRYCONTINUE 0x00000006L	消息框包含三个按钮：“取消”、“重试”、“继续”。 使用此消息框类型而不是MB_ABORTRETRYIGNORE。
MB_HELP 0x00004000L	向消息框添加 “帮助 ”按钮。 当用户单击“ 帮助 ”按钮或按 F1 时，系统会向所有者发送 WM_HELP 消息。
MB_OK 0x00000000L	消息框包含一个按钮： “确定”。 这是默认值。
MB_OKCANCEL 0x00000001L	消息框包含两个按钮： “确定” 和“ 取消”。
MB_RETRYCANCEL 0x00000005L	消息框包含两个按钮： 重试 和 取消。
MB_YESNO 0x00000004L	消息框包含两个按钮： “是 ”和“ 否”。
MB_YESNOCANCEL 0x00000003L	消息框包含三个按钮： “是”、“ 否”和 “取消”。

 

若要在消息框中显示图标，请指定以下值之一。

值	含义
MB_ICONEXCLAMATION 0x00000030L	消息框中会显示一个感叹号图标。
MB_ICONWARNING 0x00000030L	消息框中会显示一个感叹号图标。
MB_ICONINFORMATION 0x00000040L	消息框中将显示一个由圆圈中的小写字母 i 组成的图标。
MB_ICONASTERISK 0x00000040L	消息框中将显示一个由圆圈中的小写字母 i 组成的图标。
MB_ICONQUESTION 0x00000020L	消息框中会显示一个问号图标。 不再建议使用问号消息图标，因为这种图标无法清楚地表示特定类型的消息，并且作为问题的消息表述可应用于任何消息类型。 此外，用户可能会将问号消息符号与帮助信息混淆。 因此，不要在消息框中使用问号消息符号。 系统继续支持它包含的内容，只为满足反向兼容性。
MB_ICONSTOP 0x00000010L	消息框中会显示一个停止符号图标。
MB_ICONERROR 0x00000010L	消息框中会显示一个停止符号图标。
MB_ICONHAND 0x00000010L	消息框中会显示一个停止符号图标。

 

若要指示默认按钮，请指定以下值之一。

值	含义
MB_DEFBUTTON1 0x00000000L	第一个按钮是默认按钮。 除非指定了MB_DEFBUTTON2、MB_DEFBUTTON3或MB_DEFBUTTON4，否则MB_DEFBUTTON1为默认值。
MB_DEFBUTTON2 0x00000100L	第二个按钮是默认按钮。
MB_DEFBUTTON3 0x00000200L	第三个按钮是默认按钮。
MB_DEFBUTTON4 0x00000300L	第四个按钮是默认按钮。

 

若要指示对话框的形式，请指定以下值之一。

值	含义
MB_APPLMODAL 0x00000000L	用户必须先响应消息框，然后才能在 hWnd 参数标识的窗口中继续工作。 但是，用户可以移动到其他线程的窗口并在这些窗口中工作。 根据应用程序中窗口的层次结构，用户可能能够移动到线程中的其他窗口。 将自动禁用消息框父级的所有子窗口，但弹出窗口不会禁用。 如果既未指定MB_SYSTEMMODAL，也未指定MB_TASKMODAL，则MB_APPLMODAL为默认值。
MB_SYSTEMMODAL 0x00001000L	与MB_APPLMODAL相同，只是消息框具有 WS_EX_TOPMOST 样式。 使用系统模式消息框通知用户严重、可能具有破坏性的错误，这些错误需要立即关注 (例如内存不足) 。 此标志不会影响用户与与 hWnd 关联的窗口以外的其他窗口交互的能力。
MB_TASKMODAL 0x00002000L	与 MB_APPLMODAL相同， 只不过，如果 hWnd 参数为 NULL，则禁用属于当前线程的所有顶级窗口。 当调用应用程序或库没有可用的窗口句柄，但仍需要阻止输入调用线程中的其他窗口而不挂起其他线程时，请使用此标志。

 

若要指定其他选项，请使用以下一个或多个值。

值	含义
MB_DEFAULT_DESKTOP_ONLY 0x00020000L	与交互式窗口工作站的桌面相同。 有关详细信息，请参阅 窗口工作站。 如果当前输入桌面不是默认桌面，则在用户切换到默认桌面之前 ，MessageBox 不会返回。
MB_RIGHT 0x00080000L	文本右对齐。
MB_RTLREADING 0x00100000L	在希伯来语和阿拉伯语系统上使用从右到左的阅读顺序显示消息和描述文字文本。
MB_SETFOREGROUND 0x00010000L	消息框将成为前台窗口。 在内部，系统为消息框调用 SetForegroundWindow 函数。
MB_TOPMOST 0x00040000L	消息框是使用 WS_EX_TOPMOST 窗口样式创建的。
MB_SERVICE_NOTIFICATION 0x00200000L	调用方是通知用户某个事件的服务。 函数在当前活动桌面上显示一个消息框，即使没有用户登录到计算机也是如此。 终端服务： 如果调用线程具有模拟令牌，函数会将消息框定向到模拟令牌中指定的会话。 如果设置了此标志， 则 hWnd 参数必须为 NULL。 这样，消息框就可以出现在与 hWnd 对应的桌面以外的桌面上。 有关使用此标志的安全注意事项的信息，请参阅 Interactive Services。 具体而言，请注意，此标志可以在锁定的桌面上生成交互式内容，因此应仅用于一组非常有限的方案，例如资源耗尽。

返回值

类型： int

如果消息框有“取消”按钮，则如果按下 ESC 键或选择了“取消”按钮，函数将返回 IDCANCEL 值。 如果消息框没有 “取消 ”按钮，则按 ESC 将不起作用 - 除非存在MB_OK按钮。 如果显示MB_OK按钮，并且用户按下 ESC，则返回值为 IDOK。

如果函数失败，则返回值为零。 要获得更多的错误信息，请调用 GetLastError。

如果函数成功，则返回值是以下菜单项值之一。

返回代码/值	说明
IDABORT 3	已选择 “中止 ”按钮。
IDCANCEL 2	已选择 “取消 ”按钮。
IDCONTINUE 11	已选择 “继续 ”按钮。
IDIGNORE 5	已选择 “忽略 ”按钮。
IDNO 7	已选择 “否 ”按钮。
IDOK 1	已选择 “确定 ”按钮。
IDRETRY 4	已选择 “重试 ”按钮。
IDTRYAGAIN 10	已选择 “重试 ”按钮。
IDYES 6	已选择 “是 ”按钮。

备注

通过将 uType 参数设置为相应的标志值，可以在消息框中使用以下系统图标。

图标	标志值
	MB_ICONHAND、 MB_ICONSTOP或 MB_ICONERROR
	MB_ICONQUESTION
	MB_ICONEXCLAMATION 或 MB_ICONWARNING
	MB_ICONASTERISK 或 MB_ICONINFORMATION

 

在 MessageBox 显示字符串的开头添加两个从右到左的标记 (RPM) ，由 Unicode 格式字符 U+200F 表示，由 MessageBox 呈现引擎解释，使 MessageBox 的阅读顺序呈现为从右到左 (RTL) 。

使用系统模式消息框指示系统内存不足时，不应从资源文件中获取 lpText 和 lpCaption 参数指向的字符串，因为尝试加载资源可能会失败。

如果在对话框存在时创建消息框，请使用对话框的句柄作为 hWnd 参数。 hWnd 参数不应标识子窗口，例如对话框中的控件。

示例

在以下示例中，应用程序显示一个消息框，该消息框在发生错误条件后提示用户执行操作。 消息框显示描述错误条件及其解决方法的消息。 MB_CANCELTRYCONTINUE样式指示 MessageBox 提供三个按钮，用户可以选择如何继续操作。 MB_DEFBUTTON2样式将默认焦点设置为消息框的第二个按钮，在本例中为“重试”按钮。

int DisplayResourceNAMessageBox()
{
    int msgboxID = MessageBox(
        NULL,
        (LPCWSTR)L"Resource not available\nDo you want to try again?",
        (LPCWSTR)L"Account Details",
        MB_ICONWARNING | MB_CANCELTRYCONTINUE | MB_DEFBUTTON2
    );

    switch (msgboxID)
    {
    case IDCANCEL:
        // TODO: add code
        break;
    case IDTRYAGAIN:
        // TODO: add code
        break;
    case IDCONTINUE:
        // TODO: add code
        break;
    }

    return msgboxID;
}

下图显示了上述代码示例的输出：

有关另一个消息框示例，请参阅 显示消息框。

注意

winuser.h 标头将 MessageBox 定义为别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。 将非特定编码别名的使用与非非特定编码的代码混合使用可能会导致不匹配，从而导致编译或运行时错误。 有关详细信息，请参阅 函数原型的约定。

要求

最低受支持的客户端	Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器	Windows 2000 Server [仅限桌面应用]
目标平台	Windows
标头	winuser.h (包括 Windows.h)
Library	User32.lib
DLL	User32.dll
API 集	在 Windows 8) 中引入的 ext-ms-win-ntuser-dialogbox-l1-1-0 (

请参阅

概念性

对话框

FlashWindow

MessageBeep

MessageBoxEx

MessageBoxIndirect

其他资源

引用

SetForegroundWindow