SHMessageBoxCheckA 函数 (shlwapi.h)

  • 项目

[SHMessageBoxCheck 可用于“要求”部分中指定的操作系统。 在后续版本中，它可能已更改或不可用。]

显示一个消息框，该消息框为用户提供了禁止进一步出现的选项。 如果用户已选择取消显示消息框，则函数不会显示对话框，而只是返回默认值。

语法

int SHMessageBoxCheckA(
  [in, optional] HWND   hwnd,
  [in]           LPCSTR pszText,
  [in]           LPCSTR pszCaption,
                 UINT   uType,
                 int    iDefault,
  [in]           LPCSTR pszRegVal
);

参数

[in, optional] hwnd

类型：HWND

消息框所有者的窗口句柄。 此值可以为 NULL。

[in] pszText

类型： LPCTSTR

指向包含要显示的消息的以 null 结尾的字符串的指针。

[in] pszCaption

类型： LPCTSTR

指向包含消息框标题的以 null 结尾的字符串的指针。 如果此参数设置为 NULL，则游戏将设置为 Error！。

uType

类型： UINT

指定消息框的内容和行为的标志。 此函数仅支持 MessageBox 支持的一部分标志。 如果使用下面未列出的任何标志，则函数的行为是未定义的。

必须通过设置一个和仅设置以下标志之一来指定要显示的按钮。

MB_OKCANCEL

显示带有 “确定” 和“ 取消 ”按钮的消息框。

MB_YESNO

显示带有 “是 ”和“ 否 ”按钮的消息框。

MB_OK

显示带有 “确定” 按钮的消息框。

可以通过设置一个和仅设置以下标志之一来显示可选图标。

MB_ICONHAND

显示停止符号图标。

MB_ICONQUESTION

显示问号图标。

MB_ICONEXCLAMATION

显示感叹号图标。

MB_ICONINFORMATION

在圆圈中显示带有小写“i”的图标。

iDefault

类型： int

当用户选择不再显示消息框时函数返回的值。 如果用户尚未选择禁止显示消息框，则会显示消息框，并且函数将忽略 iDefault。

[in] pszRegVal

类型： LPCTSTR

指向以 null 结尾的字符串的指针，该字符串包含要与此消息关联的唯一字符串值。 为了避免与 Microsoft 使用的值发生冲突，此字符串应包含 GUID。 此字符串的长度不得超过 REGSTR_MAX_VALUE_LENGTH 个字符，包括终止 null 字符。

返回值

类型： int

如果用户已选择取消显示消息框，则函数会立即返回分配给 iDefault 的值。

如果用户单击“确定”、“取消”、“是”或“否”按钮，该函数将分别返回 IDOK、IDCANCEL、IDYES 或 IDNO。

如果用户通过单击描述文字中的 X 按钮关闭消息框，则函数将返回 IDCANCEL。 在这种情况下，即使尚未设置MB_OKCANCEL标志，也会返回此值。

如果发生错误，则返回值通常为 –1。 但是，在某些内存不足的条件下，函数可能会返回 iDefault。

注解

安全警告： 如果函数返回 –1 或 iDefault，请不要执行任何危险操作。 如果在尝试显示消息框时出错， SHMessageBoxCheck 将返回 –1，或者在某些情况下返回 iDefault。 此类错误可能是由内存或资源不足引起的。 如果获得其中一个返回值，应注意用户不一定看到对话框，因此不积极同意任何操作。

不要将“不显示此对话框”与“记住此答案”混淆。 SHMessageBoxCheck 不提供“记住此答案”功能。 如果用户选择再次禁止显示消息框，则函数不会保留他们单击的按钮。 相反， SHMessageBoxCheck 的后续调用只返回 iDefault 指定的值。 请看下面的示例。


int iResult = SHMessageBoxCheck(hwnd, 
                                TEXT("Do you want to exit without saving?"),
                                TEXT("Warning"), 
                                MB_YESNO, 
                                IDNO,
                                TEXT("{d9108ba3-9a61-4398-bfbc-b02102c77e8a}");

如果用户选择 “将来不显示此 对话框”并单击“ 是 ”按钮， SHMessageBoxCheck 将返回 IDYES。 但是，下次执行此代码时， SHMessageBoxCheck 不会返回 IDYES，即使用户最初选择了 “是 ”。 而是返回 IDNO，因为这是 iDefault 指定的值。

消息框显示的默认按钮应与 iDefault 值一致。 缺少对 MB_DEFBUTTON2 标志的支持意味着，如果指定了 MB_OK 或 MB_OKCANCEL 标志，则应将 iDefault 设置为 IDOK。 如果已设置 MB_YESNO 标志，则应将 iDefault 值设置为 IDYES。

SHMessageBoxCheck 记录用户选择在以下注册表项下取消显示的消息框：

HKEY_CURRENT_USER
   Software
      Microsoft
         Windows
            CurrentVersion
               Explorer
                  DontShowMeThisDialogAgain

注意

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

要求

   
最低受支持的客户端 Windows XP [仅限桌面应用]
最低受支持的服务器 Windows Server 2003 [仅限桌面应用]
目标平台 Windows
标头 shlwapi.h
DLL Shlwapi.dll (5.0 或更高版本)