Функция MessageBoxA (winuser.h)
Отображает модальное диалоговое окно, содержащее системный значок, набор кнопок и краткое сообщение для конкретного приложения, например сведения о состоянии или ошибке. Окно сообщения возвращает целочисленное значение, указывающее, какую кнопку нажал пользователь.
Синтаксис
int MessageBoxA(
[in, optional] HWND hWnd,
[in, optional] LPCSTR lpText,
[in, optional] LPCSTR lpCaption,
[in] UINT uType
);
Параметры
[in, optional] hWnd
Тип: HWND
Дескриптор для окна владельца создаваемого окна сообщения. Если этот параметр имеет значение NULL, окно сообщения не имеет окна владельца.
[in, optional] lpText
Тип: LPCTSTR
Отображаемое сообщение. Если строка состоит из нескольких строк, можно разделить строки с помощью символа возврата каретки и (или) перевода строк между каждой строкой.
[in, optional] lpCaption
Тип: LPCTSTR
Заголовок диалогового окна. Если этот параметр имеет значение NULL, по умолчанию используется название Error.
[in] uType
Тип: UINT
Содержимое и поведение диалогового окна. Этот параметр может быть сочетанием флагов из следующих групп флагов.
Чтобы указать кнопки, отображаемые в окне сообщения, укажите одно из следующих значений.
| Значение | Значение |
|---|---|
|
Окно сообщения содержит три кнопки: "Прервать", "Повторить" и "Пропустить". |
|
Окно сообщения содержит три кнопки: "Отмена", "Повторить попытку", "Продолжить". Используйте этот тип окна сообщения вместо MB_ABORTRETRYIGNORE. |
|
Добавляет кнопку Справка в окно сообщения. Когда пользователь нажимает кнопку Справка или нажимает клавишу F1, система отправляет владельцу сообщение WM_HELP . |
|
Окно сообщения содержит одну кнопку: ОК. Это значение по умолчанию. |
|
Окно сообщения содержит две кнопки: ОК и Отмена. |
|
Окно сообщения содержит две кнопки: "Повторить" и "Отмена". |
|
Окно сообщения содержит две кнопки: Да и Нет. |
|
Окно сообщения содержит три кнопки: Да, Нет и Отмена. |
Чтобы отобразить значок в окне сообщения, укажите одно из следующих значений.
Чтобы указать кнопку по умолчанию, укажите одно из следующих значений.
Чтобы указать модальность диалогового окна, укажите одно из следующих значений.
Чтобы указать другие параметры, используйте одно или несколько из следующих значений.
| Значение | Значение |
|---|---|
|
Аналогично рабочему столу интерактивной оконной станции. Дополнительные сведения см. в разделе Оконные станции.
Если текущий рабочий стол ввода не является рабочим столом по умолчанию, MessageBox не возвращается, пока пользователь не переключится на рабочий стол по умолчанию. |
|
Текст оправдан по правому краю. |
|
Отображает сообщение и подпись текст в порядке чтения справа налево в системах иврита и арабского языка. |
|
Окно сообщения становится окном переднего плана. Внутренне система вызывает функцию SetForegroundWindow для окна сообщения. |
|
Окно сообщения создается в стиле окна WS_EX_TOPMOST . |
|
Вызывающий объект — это служба, которая уведомляет пользователя о событии. Функция отображает окно сообщения на текущем активном рабочем столе, даже если пользователь не вошел в систему.
Службы терминалов: Если вызывающий поток имеет токен олицетворения, функция направляет окно сообщения в сеанс, указанный в маркере олицетворения. Если этот флаг установлен, параметр hWnd должен иметь значение NULL. Это необходимо, чтобы окно сообщения отображалось на рабочем столе, отличном от рабочего стола, соответствующего hWnd. Сведения о безопасности при использовании этого флага см. в разделе Интерактивные службы. В частности, имейте в виду, что этот флаг может создавать интерактивное содержимое на заблокированном рабочем столе и поэтому должен использоваться только для очень ограниченного набора сценариев, таких как исчерпание ресурсов. |
Возвращаемое значение
Тип: int
Если в окне сообщения есть кнопка Отмена , функция возвращает значение IDCANCEL , если нажата клавиша ESC или выбрана кнопка Отмена . Если в окне сообщения нет кнопки Отмена , нажатие клавиши ESC не повлияет, если нет кнопки MB_OK. Если отображается кнопка MB_OK и пользователь нажимает клавишу ESC, возвращаемым значением будет IDOK.
Если функция выполняется неудачно, возвращается нулевое значение. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.
Если функция выполнена успешно, возвращаемое значение будет одним из следующих значений пункта меню.
| Возвращаемый код/значение | Описание |
|---|---|
|
Была выбрана кнопка Прерывание . |
|
Была выбрана кнопка Отмена . |
|
Была выбрана кнопка Продолжить . |
|
Была выбрана кнопка Пропустить . |
|
Кнопка Нет выбрана. |
|
Была выбрана кнопка ОК . |
|
Была выбрана кнопка Повторить . |
|
Была выбрана кнопка Повторить попытку. |
|
Была выбрана кнопка Да . |
Комментарии
Следующие системные значки можно использовать в окне сообщения, задав для параметра uType соответствующее значение флага.
| Значок | Значения флагов |
|---|---|
 |
MB_ICONHAND, MB_ICONSTOP или MB_ICONERROR |
 |
MB_ICONQUESTION |
 |
MB_ICONEXCLAMATION или MB_ICONWARNING |
 |
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;
}
На следующем рисунке показаны выходные данные из предыдущего примера кода:
Еще один пример окна сообщений см. в разделе Отображение окна сообщения.
Примечание
Заголовок winuser.h определяет MessageBox как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора UNICODE. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.
Требования
| Минимальная версия клиента | 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) |
См. также раздел
Основные понятия
Другие ресурсы
Справочные материалы