Класс QMessageBox

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

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

Типы

Свойства

Открытые функции

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

Сигналы

Статические открытые члены

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

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

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

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

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

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

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

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

Лучше, чем просто предупредить пользователя о событии, также спросить его, что делать. Храните вопрос в свойстве дополнительного текста, и установите свойство стандартных кнопок в набор кнопок, которые вы хотите в качестве набора ответов пользователя. Кнопки задаются путем комбинирования значений из 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;
}

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

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

Форматирование Rich Text и свойство Text Format

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

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

Уровни серьезности и свойства Icon и Pixmap

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

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

Подводя итог, чтобы установить значок, используйте либо 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
}

Ключи по умолчанию и Esc

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

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

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

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

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

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

перечисление QMessageBox::ButtonRole

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

См. также StandardButton.

перечисление QMessageBox::Icon

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

перечисление QMessageBox::StandardButtonфлаги QMessageBox::StandardButtons

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

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

Тип 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(), чтобы определить, какая кнопка была нажата.

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

См. также 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 с заданным title и центрированным над parent (если parent не nullptr). Сообщение включает номер версии Qt, используемой приложением.

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

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

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

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

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

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

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

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

Это перегруженная функция.

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

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

Это перегруженная функция.

Добавляет стандартную 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

Возвращает флажок, отображаемый в диалоговом окне. Это 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, возвращается кнопка escape button.

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

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

QPushButton *QMessageBox::defaultButton() const

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

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

QAbstractButton *QMessageBox::escapeButton() const

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

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

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

Когда кнопку Escape не удалось автоматически определить, нажатие 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)

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

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

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

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

См. также 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, возвращается кнопка выхода.

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

См. также 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)

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

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

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

Устанавливает кнопку, которая активируется при нажатии клавиши Esc, в 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, возвращается кнопка escape.

Диалоговое окно — это прикладное модальное диалоговое окно.

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