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

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

enum QMessageBox::ButtonRole

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

См. также StandardButton.

enum QMessageBox::Icon

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

enum QMessageBox::StandardButtonflags QMessageBox::StandardButtons

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

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

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

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

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

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

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

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

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

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

QMessageBox::QMessageBox(QWidget *parent = nullptr)

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

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

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

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

[override virtual slot] int QMessageBox::exec()

Переопределяет: QDialog::exec().

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

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

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

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

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

[virtual] QMessageBox::~QMessageBox()

Уничтожает окно сообщения.

[static] void QMessageBox::about(QWidget *parent, const QString &title, const QString &text)

Отображает простое окно «О программе» с заголовком title и текстом text. Родительским окном окна «О программе» является parent.

Функция about() ищет подходящий значок в четырёх местах:

1. Предпочитает parent->icon(), если он существует.
2. Если нет, пытается найти верхнее окно, содержащее parent.
3. Если это не удаётся, пытается найти активное окно.
4. В качестве последнего средства использует значок «Информация».

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

См. также QWidget::windowIcon() и QApplication::activeWindow().

[static] void QMessageBox::aboutQt(QWidget *parent, const QString &title = QString())

Отображает простое окно сообщения о Qt с заданным title и центрированное над parent (если parent не nullptr). Сообщение включает номер версии Qt, используемой приложением.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

[since 5.2] 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) {
    ...
}

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

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

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

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

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

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

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

QPushButton *QMessageBox::defaultButton() const

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

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

QAbstractButton *QMessageBox::escapeButton() const

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

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

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

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

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

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

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

void QMessageBox::removeButton(QAbstractButton *button)

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

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

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

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

[since 5.2] void QMessageBox::setCheckBox(QCheckBox *cb)

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

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

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

void QMessageBox::setDefaultButton(QPushButton *button)

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

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

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

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

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

void QMessageBox::setEscapeButton(QAbstractButton *button)

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

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

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

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

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

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

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

Устанавливает режим работы окна сообщения в windowModality.

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

void QMessageBox::setWindowTitle(const QString &title)

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

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

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

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

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

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

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

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

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

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