Функция SHMessageBoxCheckW (shlwapi.h)

[SHMessageBoxCheck доступно для использования в операционных системах, указанных в разделе "Требования". Он может быть изменен или недоступен в последующих версиях.]

Отображает окно сообщения, которое дает пользователю возможность подавлять дальнейшие вхождения. Если пользователь уже отказался от поля сообщения, функция не отображает диалоговое окно и вместо этого просто возвращает значение по умолчанию.

Синтаксис

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

Параметры

[in, optional] hwnd

Тип: HWND

Дескриптор окна владельцу поля сообщения. Это значение может быть NULL.

[in] pszText

Тип: LPCTSTR

Указатель на строку, завершающуюся значением NULL, содержащую отображаемое сообщение.

[in] pszCaption

Тип: LPCTSTR

Указатель на строку, завершающуюся значением NULL, которая содержит заголовок поля сообщения. Если для этого параметра задано значение NULL, заголовок имеет значение Error!.

uType

Тип: UINT

Флаги, указывающие содержимое и поведение поля сообщения. Эта функция поддерживает только подмножество флагов, поддерживаемых MessageBox. Если вы используете какие-либо флаги, которые не перечислены ниже, поведение функции не определено.

Необходимо указать кнопки для отображения, задав один и только один из следующих флагов.

MB_OKCANCEL

Отображение поля сообщения с кнопками OK и кнопками отмены .

MB_YESNO

Отображение поля сообщения с кнопками Да и нет.

MB_OK

Отображение поля сообщения с кнопкой ОК.

Вы можете отобразить необязательный значок, задав один и только один из следующих флагов.

MB_ICONHAND

Отображение значка знака остановки.

MB_ICONQUESTION

Отображение значка вопросительного знака.

MB_ICONEXCLAMATION

Отображение значка восклицательного знака.

MB_ICONINFORMATION

Отображение значка с нижним регистром "i" в круге.

iDefault

Тип: int

Значение, возвращаемое функцией, когда пользователь отказался отображать окно сообщения снова. Если пользователь не отказался от поля сообщения, отображается поле сообщения, а функция игнорирует iDefault.

[in] pszRegVal

Тип: LPCTSTR

Указатель на строку, завершающуюся значением NULL, которая содержит уникальное строковое значение для связывания с этим сообщением. Чтобы избежать конфликтов со значениями, используемыми корпорацией Майкрософт, эта строка должна содержать 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 означает, что iDefault следует задать для идентификатора, если вы указали флаг MB_OK или MB_OKCANCEL. Значение iDefault должно иметь значение IDYES, если установлен флаг MB_YESNO.

SHMessageBoxCheck записывает поля сообщений, которые пользователь выбрал для подавления в следующем разделе реестра.

HKEY_CURRENT_USER
   Software
      Microsoft
         Windows
            CurrentVersion
               Explorer
                  LowRegistry
                     DontShowMeThisDialogAgain

Заметка

Заголовок shlwapi.h определяет SHMessageBoxCheck как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows XP [только классические приложения]
минимальный поддерживаемый сервер	Windows Server 2003 [только классические приложения]
целевая платформа	Виндоус
заголовка	shlwapi.h
DLL	Shlwapi.dll (версия 5.0 или более поздняя версия)