Класс QMessageBox

Класс QMessageBox предоставляет модальное диалоговое окно для информирования пользователя или для задавания ему вопроса и получения ответа. Подробнее...

• Список всех членов, включая унаследованные
• Устаревшие члены

Типы публичного доступа

Свойства

Функции общего доступа

Открытые слоты

Сигналы

Статические публичные члены

Переопределённые защищённые функции

Подробное описание

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

Предоставляются два API для использования QMessageBox: API на основе свойств и статические функции. Вызов одной из статических функций является более простым подходом, но он менее гибкий, чем использование API на основе свойств, и результат менее информативен. Рекомендуется использовать API на основе свойств.

API на основе свойств

Для использования API на основе свойств создайте экземпляр QMessageBox, установите необходимые свойства и вызовите exec() для отображения сообщения. Самый простой вариант — установить только свойство текста сообщения.

QMessageBox msgBox;
msgBox.setText("The document has been modified.");
msgBox.exec();

Пользователь должен нажать кнопку OK, чтобы закрыть диалоговое окно. Остальная часть графического интерфейса заблокирована до тех пор, пока диалоговое окно не будет закрыто.

Лучший подход, чем просто оповещение пользователя о событии, заключается в том, чтобы также спросить пользователя, что делать с этим событием. Сохраните вопрос в свойстве информативный текст, и установите свойство стандартные кнопки в набор кнопок, которые вы хотите использовать в качестве набора ответов пользователя. Кнопки задаются путём комбинирования значений из StandardButtons с использованием побитового оператора ИЛИ. Порядок отображения кнопок зависит от платформы. Например, в Windows кнопка Сохранить отображается слева от кнопки Отмена, а в Mac OS порядок обратный.

Отметьте одну из ваших стандартных кнопок как стандартную кнопку по умолчанию.

QMessageBox msgBox;
msgBox.setText("The document has been modified.");
msgBox.setInformativeText("Do you want to save your changes?");
msgBox.setStandardButtons(QMessageBox::Save | QMessageBox::Discard | QMessageBox::Cancel);
msgBox.setDefaultButton(QMessageBox::Save);
int ret = msgBox.exec();

Этот подход рекомендуется в руководстве по macOS. Аналогичные рекомендации применяются для других платформ, но обратите внимание на различные способы обработки информативного текста для разных платформ.

Слот exec() возвращает значение StandardButtons нажатой кнопки.

switch (ret) {
  case QMessageBox::Save:
      // Save was clicked
      break;
  case QMessageBox::Discard:
      // Don't Save was clicked
      break;
  case QMessageBox::Cancel:
      // Cancel was clicked
      break;
  default:
      // should never be reached
      break;
}

Чтобы предоставить пользователю больше информации, чтобы помочь ему ответить на вопрос, установите свойство подробный текст. Если свойство подробный текст установлено, будет отображаться кнопка Показать подробности…

Нажатие кнопки Показать подробности… отображает подробный текст.

Форматированный текст и свойство формата текста

Свойство подробный текст всегда интерпретируется как обычный текст. Свойства основной текст и информативный текст могут быть как обычным, так и форматированным текстом. Эти строки интерпретируются в соответствии с настройкой свойства формат текста. Значение по умолчанию — автоматический формат.

Обратите внимание, что для некоторых текстовых строк, содержащих метасимволы XML, тест распознавания форматированного текста тест распознавания форматированного текста может завершиться неудачей, что приведёт к неверному интерпретированию вашей текстовой строки как форматированного текста. В редких случаях используйте Qt::convertFromPlainText() для преобразования вашей текстовой строки в визуально эквивалентную строку форматированного текста или явно задайте свойство формат текста с помощью setTextFormat().

Уровни серьезности и свойства Иконки и Пиксельмапа

QMessageBox поддерживает четыре предопределённых уровня серьезности сообщений или типа сообщения, которые фактически отличаются только предопределённой иконкой, которую они показывают. Укажите один из четырёх предопределённых типов сообщений, установив свойство иконка на одну из предопределённых иконок. Следующие правила являются руководством:

Предопределённые иконки не определяются QMessageBox, а предоставляются стилем. Значение по умолчанию — Без иконки. Окна сообщений в остальных случаях одинаковы. При использовании стандартной иконки используйте рекомендуемую в таблице или рекомендуемую руководством по стилю для вашей платформы. Если ни одна из стандартных иконок не подходит для вашего окна сообщения, вы можете использовать пользовательскую иконку, установив свойство пиксельмапа иконки вместо свойства иконка.

Подводя итог, для установки иконки используйте либо setIcon() для одной из стандартных иконок, либо setIconPixmap() для пользовательской иконки.

API статических функций

Создание диалоговых окон с использованием статических функций API, хотя и удобно, менее гибко, чем использование API на основе свойств, так как сигнатуры статических функций не имеют параметров для установки свойств информационного текста и подробного текста. Одним из обходных путей было использование параметра title в качестве основного текста диалогового окна и параметра text в качестве информационного текста. Поскольку это очевидным образом ухудшает читаемость диалогового окна, рекомендации платформы не рекомендуют его использовать. Руководство по интерфейсу пользователя Microsoft Windows рекомендует использовать имя приложения в качестве заголовка окна, что означает, что если у вас есть информационный текст в дополнение к основному тексту, вы должны объединить его с параметром text.

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

Доступны статические функции для создания диалоговых окон информационного(), вопроса(), предупреждения() и критического() типов.

int ret = QMessageBox::warning(this, tr("My Application"),
                               tr("The document has been modified.\n"
                                  "Do you want to save your changes?"),
                               QMessageBox::Save | QMessageBox::Discard
                               | QMessageBox::Cancel,
                               QMessageBox::Save);

Пример Стандартных диалоговых окон демонстрирует, как использовать QMessageBox и другие встроенные диалоговые окна Qt.

Дополнительно

Если стандартные кнопки недостаточно гибкие для вашего диалогового окна, вы можете использовать перегрузку addButton(), которая принимает текст и ButtonRole для добавления пользовательских кнопок. ButtonRole используется QMessageBox для определения порядка отображения кнопок на экране (что варьируется в зависимости от платформы). Вы можете проверить значение clickedButton() после вызова exec(). Например,

QMessageBox msgBox;
QPushButton *connectButton = msgBox.addButton(tr("Connect"), QMessageBox::ActionRole);
QPushButton *abortButton = msgBox.addButton(QMessageBox::Abort);

msgBox.exec();

if (msgBox.clickedButton() == connectButton) {
    // connect
} else if (msgBox.clickedButton() == abortButton) {
    // abort
}

Кнопка по умолчанию и клавиша Escape

Кнопку по умолчанию (то есть кнопку, активируемую при нажатии клавиши Enter) можно задать с помощью setDefaultButton(). Если кнопка по умолчанию не задана, QMessageBox пытается найти её на основе ролей кнопок в диалоговом окне.

Кнопку Esc (кнопку, активируемую при нажатии Esc) можно указать с помощью setEscapeButton(). Если кнопка Esc не указана, QMessageBox пытается найти её по следующим правилам:

1. Если кнопка только одна, она активируется при нажатии Esc.
2. Если есть кнопка Отмена, она активируется при нажатии Esc.
3. Если есть ровно одна кнопка с ролью Reject или ролью No, она активируется при нажатии Esc.

Если кнопка Esc не может быть определена по этим правилам, нажатие Esc не оказывает никакого влияния.

См. также QDialogButtonBox, Руководство по разработке графического интерфейса пользователя: Окно сообщения, Пример стандартных диалоговых окон и Пример приложения Qt Widgets.

Документация типов членов

enum QMessageBox::ButtonRole

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

См. также StandardButton.

enum QMessageBox::Icon

Этот перечисление имеет следующие значения:

enum QMessageBox::StandardButtonфлаги QMessageBox::StandardButtons

Эти перечисления описывают флаги для стандартных кнопок. Каждая кнопка имеет определённую роль кнопки.

Следующие значения устарели:

Тип StandardButtons — это псевдоним для QFlags<StandardButton>. Он хранит результат побитового ИЛИ значений StandardButton.

См. также ButtonRole и standardButtons.

Документация по членам-функциям

QMessageBox::QMessageBox(QMessageBox::Icon icon, const QString &title, const QString &text, QMessageBox::StandardButtons buttons = NoButton, QWidget *parent = nullptr, Qt::WindowFlags f = Qt::Dialog | Qt::MSWindowsFixedSizeDialogHint)

Создаёт диалоговое окно сообщения с заданным icon, title, text и стандартными buttons. Стандартные или пользовательские кнопки могут быть добавлены в любое время с помощью addButton(). Аргументы parent и f передаются конструктору QDialog.

Диалоговое окно сообщения является модальным для приложения.

В macOS, если parent не nullptr и вы хотите, чтобы ваше диалоговое окно сообщения отображалось как Qt::Sheet родительского окна, установите модальный режим окна диалогового окна в Qt::WindowModal (по умолчанию). В противном случае диалоговое окно будет стандартным.

См. также setWindowTitle(), setText(), setIcon() и setStandardButtons().

QMessageBox::QMessageBox(QWidget *parent = nullptr)

Создаёт диалоговое окно сообщения без текста и кнопок. parent передаётся конструктору QDialog.

В macOS, если вы хотите, чтобы ваше диалоговое окно сообщения отображалось как Qt::Sheet родительского окна, установите модальный режим окна диалогового окна в Qt::WindowModal или используйте open(). В противном случае диалоговое окно будет стандартным.

[signal] void QMessageBox::buttonClicked(QAbstractButton *button)

Этот сигнал излучается всякий раз, когда нажимается кнопка в QMessageBox. Кнопка, которая была нажата, возвращается в button.

[override virtual slot] int QMessageBox::exec()

Переопределяет: QDialog::exec().

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

При использовании QMessageBox со стандартными кнопками эта функция возвращает значение типа StandardButton, указывающее, какая стандартная кнопка была нажата. При использовании QMessageBox с пользовательскими кнопками функция возвращает неопределённое значение; используйте clickedButton(), чтобы определить, какая кнопка была нажата.

Примечание: Функция result() также возвращает значение типа StandardButton вместо QDialog::DialogCode.

Пользователь не может взаимодействовать ни с каким другим окном в приложении до тех пор, пока не закроет диалоговое окно, нажав кнопку или используя механизм, предоставляемый системой окон.

См. также show() и result().

[virtual] QMessageBox::~QMessageBox()

Удаляет диалоговое окно сообщения.

[static] void QMessageBox::about(QWidget *parent, const QString &title, const QString &text)

Отображает простое диалоговое окно «О программе» с заголовком title и текстом text. Родительским окном диалогового окна является parent.

Функция about() ищет подходящий значок в четырёх местах:

1. В первую очередь используется значок parent->icon(), если он существует.
2. В противном случае, пытается найти значок в верхнем окне, содержащем parent.
3. Если это не удаётся, пытается использовать значок активного окна.
4. В качестве последнего средства используется значок «Информация».

Диалоговое окно «О программе» содержит единственную кнопку «ОК». В macOS это диалоговое окно отображается как бессоставное окно; на других платформах оно в настоящее время является модальным для приложения.

См. также QWidget::windowIcon() и QApplication::activeWindow().

[static] void QMessageBox::aboutQt(QWidget *parent, const QString &title = QString())

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

Это полезно для включения в меню Справка приложения, как показано в примере Меню.

QApplication предоставляет эту функциональность как слот.

В macOS диалоговое окно «О программе» появляется как модальное окно; на других платформах оно в настоящее время является модальным для приложения.

См. также QApplication::aboutQt().

void QMessageBox::addButton(QAbstractButton *button, QMessageBox::ButtonRole role)

Добавляет заданную кнопку в диалоговое окно с заданной ролью.

См. также removeButton(), button() и setStandardButtons().

QPushButton *QMessageBox::addButton(const QString &text, QMessageBox::ButtonRole role)

Это перегруженный метод.

Создаёт кнопку с заданным текстом, добавляет её в диалоговое окно для указанной роли и возвращает её.

QPushButton *QMessageBox::addButton(QMessageBox::StandardButton button)

Это перегруженный метод.

Добавляет стандартную кнопку в диалоговое окно, если это допустимо, и возвращает кнопку.

См. также setStandardButtons().

QAbstractButton *QMessageBox::button(QMessageBox::StandardButton which) const

Возвращает указатель, соответствующий стандартной кнопке which, или nullptr, если стандартная кнопка не существует в этом диалоговом окне.

См. также standardButtons и standardButton().

QMessageBox::ButtonRole QMessageBox::buttonRole(QAbstractButton *button) const

Возвращает роль кнопки для указанной кнопки button. Эта функция возвращает InvalidRole, если button является nullptr или не была добавлена в диалоговое окно.

См. также buttons() и addButton().

QList<QAbstractButton *> QMessageBox::buttons() const

Возвращает список всех кнопок, которые были добавлены в диалоговое окно.

См. также buttonRole(), addButton() и removeButton().

[override virtual protected] void QMessageBox::changeEvent(QEvent *ev)

Переопределяет: QWidget::changeEvent(QEvent *event).

[since 5.2] QCheckBox *QMessageBox::checkBox() const

Возвращает виджет QCheckBox, отображаемый в диалоговом окне. Это nullptr , если чекбокс не установлен.

Эта функция была введена в Qt 5.2.

См. также setCheckBox().

QAbstractButton *QMessageBox::clickedButton() const

Возвращает кнопку, на которую нажал пользователь, или nullptr если пользователь нажал клавишу Esc, а кнопка escape button не была установлена.

Если exec() ещё не вызвана, возвращает nullptr.

Пример:

QMessageBox messageBox(this);
QAbstractButton *disconnectButton =
      messageBox.addButton(tr("Disconnect"), QMessageBox::ActionRole);
...
messageBox.exec();
if (messageBox.clickedButton() == disconnectButton) {
    ...
}

См. также standardButton() и button().

[override virtual protected] void QMessageBox::closeEvent(QCloseEvent *e)

Переопределяет: QDialog::closeEvent(QCloseEvent *e).

[static] QMessageBox::StandardButton QMessageBox::critical(QWidget *parent, const QString &title, const QString &text, QMessageBox::StandardButtons buttons = Ok, QMessageBox::StandardButton defaultButton = NoButton)

Открывает окно с критическим сообщением с заданным title и text перед указанным виджетом parent.

Стандартные buttons добавляются в окно сообщения. defaultButton определяет кнопку, используемую при нажатии Enter. defaultButton должен ссылаться на кнопку, указанную в buttons. Если defaultButton равен QMessageBox::NoButton, QMessageBox автоматически выбирает подходящую по умолчанию.

Возвращает идентификатор стандартной кнопки, на которую был нажат. Если вместо этого была нажата Esc, возвращается кнопка отмены.

Окно сообщения — диалоговое окно модальное для приложения.

Предупреждение: Не удаляйте parent во время выполнения диалога. Если вы хотите это сделать, вы должны создать диалог самостоятельно, используя один из конструкторов QMessageBox.

См. также question(), warning() и information().

QPushButton *QMessageBox::defaultButton() const

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

См. также setDefaultButton(), addButton() и QPushButton::setDefault().

QAbstractButton *QMessageBox::escapeButton() const

Возвращает кнопку, активируемую при нажатии клавиши Escape.

По умолчанию QMessageBox пытается автоматически определить кнопку Esc следующим образом:

1. Если есть только одна кнопка, она становится кнопкой выхода.
2. Если есть кнопка Отмена, она становится кнопкой выхода.
3. Только на macOS, если есть ровно одна кнопка с ролью QMessageBox::RejectRole, она становится кнопкой выхода.

Если кнопку выхода нельзя автоматически определить, нажатие Esc не имеет эффекта.

См. также setEscapeButton() и addButton().

[override virtual protected] bool QMessageBox::event(QEvent *e)

Переопределяет: QWidget::event(QEvent *event).

[static] QMessageBox::StandardButton QMessageBox::information(QWidget *parent, const QString &title, const QString &text, QMessageBox::StandardButtons buttons = Ok, QMessageBox::StandardButton defaultButton = NoButton)

Открывает диалоговое окно сообщения "Информация" с заданным заголовком и текстом перед указанным виджетом parent.

Стандартные кнопки добавляются в диалоговое окно. defaultButton определяет кнопку, используемую при нажатии Enter. defaultButton должен ссылаться на кнопку, заданную в buttons. Если defaultButton равен QMessageBox::NoButton, QMessageBox автоматически выбирает подходящую кнопку по умолчанию.

Возвращает идентификатор стандартной нажатой кнопки. Если вместо этого было нажато Esc, возвращается кнопка выхода.

Диалоговое окно является модальным для приложения.

Предупреждение: Не удаляйте parent во время выполнения диалога. Если вы хотите это сделать, вы должны создать диалоговое окно самостоятельно, используя один из конструкторов QMessageBox.

См. также question(), warning() и critical().

[override virtual protected] void QMessageBox::keyPressEvent(QKeyEvent *e)

Реализует: QDialog::keyPressEvent(QKeyEvent *e).

void QMessageBox::open(QObject *receiver, const char *member)

Открывает диалоговое окно и подключает его сигнал finished() или buttonClicked() к слоту, указанному receiver и member. Если слот в member имеет указатель для первого параметра, подключение происходит к buttonClicked(), в противном случае – к finished().

Сигнал будет отключен от слота при закрытии диалогового окна.

[static] QMessageBox::StandardButton QMessageBox::question(QWidget *parent, const QString &title, const QString &text, QMessageBox::StandardButtons buttons = StandardButtons(Yes | No), QMessageBox::StandardButton defaultButton = NoButton)

Открывает окно сообщения с вопросом с заданным title и text перед указанным виджетом parent.

Стандартные buttons добавляются в окно сообщения. defaultButton указывает кнопку, используемую при нажатии Enter. defaultButton должен ссылаться на кнопку, предоставленную в buttons. Если defaultButton равен QMessageBox::NoButton, QMessageBox автоматически выбирает подходящую по умолчанию.

Возвращает идентификатор стандартной кнопки, которая была нажата. Если вместо этого была нажата Esc, возвращается кнопка Esc.

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

Предупреждение: Не удаляйте parent во время выполнения диалогового окна. Если вы хотите это сделать, вы должны создать диалоговое окно самостоятельно, используя один из конструкторов QMessageBox.

См. также information(), warning() и critical().

void QMessageBox::removeButton(QAbstractButton *button)

Удаляет button из панели кнопок, не удаляя его.

См. также addButton() и setStandardButtons().

[override virtual protected] void QMessageBox::resizeEvent(QResizeEvent *event)

Переопределяет: QDialog::resizeEvent(QResizeEvent *).

[since 5.2] void QMessageBox::setCheckBox(QCheckBox *cb)

Устанавливает флажок cb в диалоговом окне сообщения. Диалоговое окно сообщения берет флажок на себя. Аргумент cb может быть nullptr для удаления существующего флажка из диалогового окна сообщения.

Данная функция была добавлена в Qt 5.2.

См. также checkBox().

void QMessageBox::setDefaultButton(QPushButton *button)

Устанавливает кнопку по умолчанию диалогового окна сообщения в button.

См. также defaultButton(), addButton() и QPushButton::setDefault().

void QMessageBox::setDefaultButton(QMessageBox::StandardButton button)

Устанавливает кнопку по умолчанию диалогового окна сообщения в button.

См. также addButton() и QPushButton::setDefault().

void QMessageBox::setEscapeButton(QAbstractButton *button)

Устанавливает кнопку, которая активируется при нажатии клавиши Escape, в button.

См. также escapeButton(), addButton() и clickedButton().

void QMessageBox::setEscapeButton(QMessageBox::StandardButton button)

Устанавливает кнопки, которые активируются при нажатии клавиши Escape, на button.

См. также addButton() и clickedButton().

void QMessageBox::setWindowModality(Qt::WindowModality windowModality)

Эта функция переопределяет QWidget::setWindowModality().

Устанавливает режим работы диалогового окна сообщения на windowModality.

В macOS, если режим работы установлен на Qt::WindowModal и диалоговое окно сообщения имеет родительское окно, то диалоговое окно будет иметь тип Qt::Sheet, в противном случае — стандартный диалог.

void QMessageBox::setWindowTitle(const QString &title)

Эта функция переопределяет QWidget::setWindowTitle().

Устанавливает заголовок диалогового окна сообщения на title. В macOS заголовок окна игнорируется (в соответствии с рекомендациями macOS).

[override virtual protected] void QMessageBox::showEvent(QShowEvent *e)

Переопределяет: QDialog::showEvent(QShowEvent *event).

QMessageBox::StandardButton QMessageBox::standardButton(QAbstractButton *button) const

Возвращает значение перечисления стандартной кнопки, соответствующей данной кнопке button, или NoButton, если данная кнопка button не является стандартной кнопкой.

См. также button() и standardButtons().

[static] QMessageBox::StandardButton QMessageBox::warning(QWidget *parent, const QString &title, const QString &text, QMessageBox::StandardButtons buttons = Ok, QMessageBox::StandardButton defaultButton = NoButton)

Открывает окно предупреждения с заданным title и text перед указанным виджетом parent.

Стандартные buttons добавляются в окно сообщения. defaultButton определяет кнопку, используемую при нажатии Enter. defaultButton должен ссылаться на кнопку, заданную в buttons. Если defaultButton равен QMessageBox::NoButton, QMessageBox автоматически выбирает подходящую по умолчанию.

Возвращает идентификатор стандартной нажатой кнопки. Если вместо этого была нажата Esc, возвращается кнопка отмены.

Окно сообщения является модальным диалоговым окном приложения.

Предупреждение: Не удаляйте parent во время выполнения диалога. Если вы хотите это сделать, вы должны создать диалог самостоятельно, используя один из конструкторов QMessageBox.

См. также question(), information() и critical().