Поделиться через


Функция MessageBox (winuser.h)

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

Синтаксис

int MessageBox(
  [in, optional] HWND    hWnd,
  [in, optional] LPCTSTR lpText,
  [in, optional] LPCTSTR lpCaption,
  [in]           UINT    uType
);

Параметры

[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_DEFBUTTON1 используется по умолчанию, если не указано MB_DEFBUTTON2, MB_DEFBUTTON3 или MB_DEFBUTTON4 .

MB_DEFBUTTON2
0x00000100L
Вторая кнопка является кнопкой по умолчанию.
MB_DEFBUTTON3
0x00000200L
Третья кнопка является кнопкой по умолчанию.
MB_DEFBUTTON4
0x00000300L
Четвертая кнопка является кнопкой по умолчанию.
 

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

Значение Значение
MB_APPLMODAL
0x00000000L
Пользователь должен ответить на окно сообщения, прежде чем продолжить работу в окне, определяемом параметром hWnd . Однако пользователь может переходить в окна других потоков и работать в этих окнах.

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

MB_APPLMODAL используется по умолчанию, если не указано ни MB_SYSTEMMODAL, ни MB_TASKMODAL.

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.

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

Возвращаемое значение

Тип: int

Если в окне сообщения есть кнопка Отмена , функция возвращает значение IDCANCEL при нажатии клавиши ESC или нажатии кнопки Отмена . Если в окне сообщения нет кнопки Отмена , нажатие клавиши 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_ICONHAND, MB_ICONSTOP или MB_ICONERROR
Значок MB_ICONQUESTION MB_ICONQUESTION
Значок MB_ICONEXCLAMATION и MB_ICONWARNING MB_ICONEXCLAMATION или MB_ICONWARNING
Значок для MB_ICONASTERISK и MB_ICONINFORMATION MB_ICONASTERISK или MB_ICONINFORMATION
 

Добавление двух меток справа налево (RLM), представленных символом форматирования Юникода U+200F, в начале отображаемой строки MessageBox интерпретируется подсистемой отрисовки 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;
}

На следующем рисунке показаны выходные данные из предыдущего примера кода:

Message box

Другой пример окна сообщения см. в разделе Отображение окна сообщения.

Требования

Требование Значение
Минимальная версия клиента Windows 2000 Professional [только классические приложения]
Минимальная версия сервера Windows 2000 Server [только классические приложения]
Целевая платформа Windows
Header winuser.h (включая Windows.h)
Библиотека User32.lib
DLL User32.dll
Набор API ext-ms-win-ntuser-dialogbox-l1-1-0 (представлено в Windows 8)

См. также раздел

Основные понятия

Диалоговые окна

FlashWindow

MessageBeep

MessageBoxEx

MessageBoxIndirect

Другие ресурсы

Справочные материалы

SetForegroundWindow