Класс 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 кнопка Сохранить отображается слева от кнопки Отмена, а в macOS — наоборот.

Укажите одну из стандартных кнопок как по умолчанию.

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 рекомендуют использовать имя приложения qCoreApplication в качестве заголовка окна, что означает, что если у вас есть дополнительный текст помимо основного текста, вам нужно объединить его с параметром 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);

Пример Standard Dialogs показывает, как использовать 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 пытается найти её на основе ролей кнопок, используемых в окне сообщения.

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

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

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

См. также QDialogButtonBox, GUI Design Handbook: Message Box, Пример Standard Dialogs и Пример Application.

Описание типов элементов

enum QMessageBox::Icon

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

enum QMessageBox::StandardButtonflags QMessageBox::StandardButtons

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

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

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

Тип StandardButtons является typedef для QFlags<StandardButton>. Он хранит комбинацию значений StandardButton, объединённых оператором OR.

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

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

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

См. также StandardButton.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Добавляет стандартную 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 и кнопка выхода не была задана.

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

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

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

Предупреждение: Не удаляйте 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().