Класс QMessageBox

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

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

Типы

Свойства

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

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

Переопределённые открытые функции

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

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

• 5 public slots унаследованы от QDialog
• 19 public slots унаследованы от QWidget
• 1 public slot унаследован от QObject

Сигналы

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

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

• 5 static public members унаследованы от QWidget
• 11 static public members унаследованы от QObject

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

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

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

• 7 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 унаследован от QWidget

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

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

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

Предоставляются два API для использования QMessageBox: API на основе свойств и статические функции. Вызов одной из статических функций — более простой подход, но он менее гибкий, чем использование API на основе свойств, и результат менее информативный. Рекомендуется использовать API на основе свойств.

API на основе свойств

Для использования API на основе свойств создайте экземпляр QMessageBox, задайте необходимые свойства и вызовите exec() для отображения сообщения. Самый простой способ — задать только свойство текста сообщения.

QMessageBox msgBox;
msgBox.setText("The document has been modified.");
msgBox.exec();

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

Лучше, чем просто информировать пользователя о событии, — также спросить его, что делать с ним. Сохраните вопрос в свойстве информационного текста и установите свойство стандартных кнопок на набор кнопок, который вы хотите, как набор ответов пользователя. Кнопки задаются путём объединения значений из 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 родительского элемента, установите модальность окна диалогового окна с сообщением на 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

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

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

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

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

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

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

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

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

[virtual] void QMessageBox::setVisible(bool visible)

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

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.

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

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

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

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

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

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