Share via

Функция 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, которая содержит уникальное строковое значение для связи с этим сообщением. Чтобы избежать конфликтов со значениями, используемыми корпорацией Майкрософт, эта строка должна содержать 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
                  DontShowMeThisDialogAgain

Примечание

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

Требования

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