Функция 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. |
|
Добавляет в окно сообщения кнопку Справка . Когда пользователь нажимает кнопку Справка или клавишу 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;
}
На следующем рисунке показаны выходные данные из предыдущего примера кода:
Другой пример окна сообщения см. в разделе Отображение окна сообщения.
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | 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) |
См. также раздел
Основные понятия
Другие ресурсы
Справочные материалы