Класс QMessageBox

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

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

Открытые типы

Свойства

• 2 свойства унаследованы от QDialog
• 59 свойств унаследованы от QWidget
• 1 свойство унаследовано от QObject

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

• 8 открытых функций унаследовано от QDialog
• 214 открытых функций унаследовано от QWidget
• 34 открытых функций унаследовано от QObject
• 14 открытых функций унаследовано от QPaintDevice

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

• 5 public slots inherited from QDialog
• 19 public slots inherited from QWidget
• 1 public slot inherited from QObject

Сигналы

• 3 signals inherited from QDialog
• 3 signals inherited from QWidget
• 2 signals inherited from QObject

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

• 5 static public members inherited from QWidget
• 10 static public members inherited from QObject

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

• 6 protected functions inherited from QDialog
• 35 protected functions inherited from QWidget
• 9 protected functions inherited from QObject
• 1 protected function inherited from QPaintDevice

Дополнительные унаследованные члены

• 1 public variable inherited from QObject
• 6 protected functions inherited from QDialog
• 35 protected functions inherited from QWidget
• 9 protected functions inherited from QObject
• 1 protected function inherited from QPaintDevice
• 1 protected slot inherited from QWidget
• 2 protected variables inherited from QObject
• 1 protected type inherited from QPaintDevice

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

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

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

Предоставляются два API для использования QMessageBox, основанный на свойствах и статические функции. Вызов одной из статических функций является более простым подходом, но он менее гибкий, чем использование 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 и свойство формата текста

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

Обратите внимание, что для некоторых строк простого текста, содержащих метасимволы 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
}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

См. также StandardButton.

QMessageBox::QMessageBox(QWidget *parent = nullptr)

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

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

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

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

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

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

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

[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 не 0). Сообщение включает номер версии Qt, используемой приложением.

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

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

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

См. также 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, или 0, если стандартная кнопка не существует в этом диалоговом окне с сообщением.

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

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

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

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

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

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

Эта функция была добавлена в 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().

QCheckBox *QMessageBox::checkBox() const

Возвращает поле флажка, отображаемое в диалоговом окне. 0, если поле флажка не задано.

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

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

QAbstractButton *QMessageBox::clickedButton() const

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

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

Пример:

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().

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

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

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

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

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

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

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

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

QPushButton *QMessageBox::defaultButton() const

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

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

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

QAbstractButton *QMessageBox::escapeButton() const

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

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

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

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

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

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

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

Переопределено из QWidget::event().

[virtual slot] int QMessageBox::exec()

Переопределено из QDialog::exec().

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Переопределено из QDialog::keyPressEvent().

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 = ..., 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().

void QMessageBox::setCheckBox(QCheckBox *cb)

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

Эта функция была введена в 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().

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, 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().