Класс QMessageBox

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

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

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

Свойства

Публичные функции

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

Сигналы

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

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

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

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

Для использования 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;
}

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

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

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

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

Обратите внимание, что для некоторых текстовых строк, содержащих 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. Если есть ровно одна кнопка с ролью Отклонения или ролью Нет, она активируется при нажатии Esc.

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

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

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

enum QMessageBox::ButtonRole

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

См. также StandardButton.

enum QMessageBox::Icon

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

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

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

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

Этот перечисление был введен или изменен в Qt 4.2.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

QCheckBox *QMessageBox::checkBox() const

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

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

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

QAbstractButton *QMessageBox::clickedButton() const

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

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

Пример:

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

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

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

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

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

QPushButton *QMessageBox::defaultButton() const

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

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

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

QAbstractButton *QMessageBox::escapeButton() const

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

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

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

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

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

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

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

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

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

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

Функция была добавлена в Qt 4.2.

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

void QMessageBox::removeButton(QAbstractButton *button)

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

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

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

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

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

void QMessageBox::setCheckBox(QCheckBox *cb)

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

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

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

void QMessageBox::setDefaultButton(QPushButton *button)

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

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

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

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

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

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

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

void QMessageBox::setEscapeButton(QAbstractButton *button)

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

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

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

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

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

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

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

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

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

Устанавливает модальный режим диалогового окна на windowModality.

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

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

void QMessageBox::setWindowTitle(const QString &title)

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

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

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

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

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

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

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

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

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

Функция была добавлена в Qt 4.2.

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