Класс QMessageBox

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

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

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

Свойства

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

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

• 8 публичных функций унаследовано от QDialog
• 214 публичных функций унаследовано от QWidget
• 31 публичных функций унаследовано от 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
• 9 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

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

• 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

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

Класс 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;
}

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

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

Текст форматирования и свойство формата текста

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

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

Уровни серьезности и свойства иконки и пиксельной карты

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

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

В общем, для установки иконки, используйте либо setIcon() для одной из стандартных иконок, либо setIconPixmap() для пользовательской иконки.

API статических функций

Создание окон сообщений с помощью API статических функций, хотя и удобно, менее гибко, чем использование API на основе свойств, так как сигнатуры статических функций не имеют параметров для установки свойств информативного текста и подробного текста. Одним из решений этой проблемы было использование параметра title в качестве основного текста окна сообщения и параметра text в качестве информативного текста окна сообщения. Поскольку это очевидно ухудшает читаемость окна сообщения, руководства по платформам не рекомендуют этого. Руководства по пользовательскому интерфейсу Microsoft Windows рекомендуют использовать имя приложения applicationName в качестве заголовка окна, что означает, что если у вас есть информативный текст в дополнение к основному тексту, вы должны объединить его с параметром 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. Если ровно одна кнопка имеет роль Отклонить или роль Нет, она активируется при нажатии 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 с заданным заголовком и центрированным по отношению к parent (если parent не равно 0). Сообщение включает номер версии Qt, используемой приложением.

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

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

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

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

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

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

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

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

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

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

Создаёт кнопку с заданным текстом, добавляет её в окно сообщения для указанного 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 и не была установлена кнопка escape button.

Если 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().

[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, возвращается кнопка escape button.

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

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

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

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

QPushButton *QMessageBox::defaultButton() const

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

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

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

QAbstractButton *QMessageBox::escapeButton() const

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

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

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

Когда кнопку выхода нельзя автоматически определить, нажатие 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, возвращается кнопка выхода.

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

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

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

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