Класс QMessageBox

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

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

Публичные типы

Свойства

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

Общедоступные функции

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

Общедоступные слоты

• 5 общедоступных слотов унаследовано от QDialog
• 19 общедоступных слотов унаследовано от QWidget
• 1 общедоступный слот унаследовано от QObject

Сигналы

• 3 сигнала унаследовано от QDialog
• 3 сигнала унаследовано от QWidget
• 2 сигнала унаследовано от QObject

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

• 5 статических общедоступных членов унаследовано от QWidget
• 11 статических общедоступных членов унаследовано от QObject

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

• 6 защищённых функций унаследовано от QDialog
• 35 защищённых функций унаследовано от QWidget
• 9 защищённых функций унаследовано от QObject
• 1 защищённая функция унаследовано от QPaintDevice

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

• 6 защищённых функций унаследовано от QDialog
• 35 защищённых функций унаследовано от QWidget
• 9 защищённых функций унаследовано от QObject
• 1 защищённая функция унаследовано от QPaintDevice
• 1 защищённый слот унаследовано от 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 поддерживает четыре предопределённых уровня серьёзности сообщений, или типа сообщений, которые на самом деле отличаются только предопределённым отображаемым значком. Укажите один из четырёх предопределённых типов сообщений, задав свойство значка одному из предопределённых значков. Следующие правила являются рекомендациями:

Предопределённые значки не определены 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, Справочник по разработке пользовательского интерфейса: диалоговые окна, Пример стандартных диалогов и Пример приложения.

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

enum QMessageBox::ButtonRole

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

См. также StandardButton.

enum QMessageBox::Icon

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

enum QMessageBox::StandardButtonflags QMessageBox::StandardButtons

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

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

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

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

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

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

QMessageBox::QMessageBox(QWidget *parent = Q_NULLPTR)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

QPushButton *QMessageBox::addButton(StandardButton button)

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

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

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

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

QAbstractButton *QMessageBox::button(StandardButton which) const

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

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

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

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

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

ButtonRole QMessageBox::buttonRole(QAbstractButton *button) const

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

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

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

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

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

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

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

[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() ещё не вызывалась, возвращает 0.

Пример:

QMessageBox messageBox(this);
QAbstractButton *disconnectButton =
      messageBox.addButton(tr("Disconnect"), QMessageBox::ActionRole);
...
messageBox.exec();
if (messageBox.clickedButton() == disconnectButton) {
    ...
}

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

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

[virtual protected] void QMessageBox::closeEvent(QCloseEvent *e)

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

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

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

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

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

Диалоговое окно — модальное диалоговое окно.

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

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

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

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

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

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

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

[virtual slot] int QMessageBox::exec()

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

void QMessageBox::open(QObject *receiver, const char *member)

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

Открывает диалог и подключает его сигнал finished() или buttonClicked() к слоту, заданному receiver и member. Если слот в member имеет указатель для своего первого параметра, подключение выполняется к buttonClicked(), в противном случае — к finished().

Сигнал будет отключен от слота при закрытии диалога.

[static] StandardButton QMessageBox::question(QWidget *parent, const QString &title, const QString &text, StandardButtons buttons = StandardButtons( Yes | No ), 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().

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

Переопределено из QWidget::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(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(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.

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

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

StandardButton QMessageBox::standardButton(QAbstractButton *button) const

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

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

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

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

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

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

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

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

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

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

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