Share via

Функция 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

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

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 должно быть установлено значение IDOK, если вы указали флаг MB_OK или MB_OKCANCEL. Если вы установили флаг MB_YESNO, для параметра iDefault должно быть установлено значение IDYES.

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

HKEY_CURRENT_USER
   Software
      Microsoft
         Windows
            CurrentVersion
               Explorer
                  LowRegistry
                     DontShowMeThisDialogAgain

Примечание

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

Требования

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