Класс 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 на основе свойств, потому что сигнатуры статических функций не содержат параметров для установки свойств informative text и detailed text. Одним из решений этой проблемы было использование параметра title в качестве основного текста окна сообщения и параметра text в качестве информативного текста окна сообщения. Поскольку это очевидным образом ухудшает читабельность окна сообщения, руководства по платформам не рекомендуют его. Руководства по интерфейсу пользователя Microsoft Windows рекомендуют использовать имя приложения application name в качестве заголовка окна window's title, что означает, что если у вас есть информативный текст в дополнение к основному тексту, вы должны его конкатенировать с параметром text.

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

Доступны статические функции для создания окон сообщений information(), question(), warning() и critical().

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. Если есть ровно одна кнопка с ролью Reject или ролью No, она активируется при нажатии Esc.

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

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

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

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

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

См. также StandardButton.

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

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

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

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

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

Этот перечисление был введён или изменён в 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 его 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

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

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

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

QAbstractButton *QMessageBox::clickedButton() const

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

Если функция 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, возвращается кнопка escape.

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

Предупреждение: Не удаляйте 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, возвращается кнопка выхода.

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

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