Класс QDialog

Класс QDialog является базовым классом диалоговых окон. Подробнее...

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

Типы публичного доступа

Свойства

• modal : bool
• sizeGripEnabled : bool

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

Переопределенные публичные функции

Публичные слоты

Сигналы

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

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

Диалоговое окно — это окно верхнего уровня, в основном используемое для краткосрочных задач и краткой коммуникации с пользователем. QDialogs могут быть модальными или бескомпромиссными. QDialogs могут предоставлять значение возврата, и у них могут быть кнопки по умолчанию. QDialogs также могут иметь QSizeGrip в правом нижнем углу, используя setSizeGripEnabled().

Обратите внимание, что QDialog (и любой другой виджет с типом Qt::Dialog) использует родительский виджет немного иначе, чем другие классы в Qt. Диалог всегда является виджетом верхнего уровня, но если у него есть родитель, его стандартное расположение — по центру над родительским виджетом верхнего уровня (если он сам не является виджетом верхнего уровня). Он также будет совмещать запись родителя в панели задач.

Используйте перегрузку функции QWidget::setParent() для изменения владения виджетом QDialog. Эта функция позволяет явно установить флаги окна переданного виджета; использование перегруженной функции очистит флаги окна, определяющие свойства окна системы для виджета (в частности, это сбросит флаг Qt::Dialog).

Примечание: Взаимоотношение родителя и диалога не подразумевает, что диалог всегда будет расположен поверх окна родителя. Чтобы убедиться, что диалог всегда находится поверх, сделайте его модальным. Это также относится к дочерним окнам самого диалога. Чтобы убедиться, что дочерние окна диалога остаются поверх диалога, сделайте дочерние окна модальными тоже.

Модальные диалоги

Модальный диалог — это диалог, который блокирует ввод в другие видимые окна в том же приложении. Диалоги, используемые для запроса имени файла от пользователя или для настройки настроек приложения, обычно являются модальными. Диалоги могут быть модальными для приложения (по умолчанию) или модальными для окна.

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

Наиболее распространенный способ отображения модального диалога — вызов его функции exec(). Когда пользователь закрывает диалог, exec() предоставит полезное значение возврата. Чтобы закрыть диалог и вернуть соответствующее значение, вы должны подключить кнопку по умолчанию, например, кнопку ОК к слоту accept(), а кнопку Отмена — к слоту reject(). В качестве альтернативы, вы можете вызвать слот done() со значениями Accepted или Rejected.

Альтернативный способ — вызвать setModal(true) или setWindowModality(), а затем show(). В отличие от exec(), show() сразу же возвращает управление вызывающему коду. Вызов setModal(true) особенно полезен для диалогов прогресса, где пользователь должен иметь возможность взаимодействовать с диалогом, например, для отмены длительной операции. Если вы используете show() и setModal(true) вместе для выполнения длительной операции, вы должны периодически вызывать QCoreApplication::processEvents() во время обработки, чтобы дать пользователю возможность взаимодействовать с диалогом. (См. QProgressDialog.)

Бескомпромиссные диалоги

Бескомпромиссный диалог — это диалог, который работает независимо от других окон в том же приложении. Диалоги поиска и замены в текстовых редакторах часто являются бескомпромиссными, чтобы позволить пользователю взаимодействовать как с основным окном приложения, так и с диалогом.

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

Если вы вызываете функцию show() после скрытия диалога, диалог будет отображен в его исходном положении. Это связано с тем, что менеджер окон определяет положение окон, которые не были явно размещены программистом. Чтобы сохранить положение диалога, перемещенного пользователем, сохраните его позицию в обработчике closeEvent(), а затем переместите диалог в это положение перед его повторным отображением.

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

Кнопка по умолчанию диалогового окна — это кнопка, которая нажимается при нажатии пользователем клавиши Enter (Возврат). Эта кнопка используется для обозначения того, что пользователь принимает настройки диалогового окна и хочет его закрыть. Для установки и управления кнопкой по умолчанию диалогового окна используйте QPushButton::setDefault(), QPushButton::isDefault() и QPushButton::autoDefault().

Клавиша Esc

Если пользователь нажимает клавишу Esc в диалоговом окне, вызывается QDialog::reject(). Это приведет к закрытию окна: событие закрытия не может быть проигнорировано (ignored).

Возможность расширения

Возможность расширения — это способность отображать диалоговое окно двумя способами: частичное диалоговое окно, отображающее наиболее часто используемые параметры, и полное диалоговое окно, отображающее все параметры. Обычно расширяемое диалоговое окно первоначально отображается как частичное диалоговое окно, но с кнопкой переключения «Ещё». Если пользователь нажимает кнопку «Ещё», диалоговое окно расширяется. Пример расширения показан здесь и демонстрирует, как создавать расширяемые диалоговые окна с помощью Qt.

Значение возврата (модальные диалоговые окна)

Модальные диалоговые окна часто используются в ситуациях, когда требуется значение возврата, например, для указания того, нажал ли пользователь кнопку «ОК» или «Отмена». Диалоговое окно можно закрыть, вызвав слоты accept() или reject(), а exec() вернёт Accepted или Rejected соответственно. Вызов exec() возвращает результат диалогового окна. Результат также доступен из result(), если диалоговое окно ещё не уничтожено.

Для изменения поведения закрытия диалогового окна можно переопределить функции accept(), reject() или done(). Функцию closeEvent() следует переопределять только для сохранения позиции диалогового окна или для переопределения стандартного поведения закрытия или отмены.

Примеры кода

Модальное диалоговое окно:

void EditorWindow::countWords()
{
    WordCountDialog dialog(this);
    dialog.setWordCount(document().wordCount());
    dialog.exec();
}

Бесmodal диалоговое окно:

void EditorWindow::find()
{
    if (!findDialog) {
        findDialog = new FindDialog(this);
        connect(findDialog, &FindDialog::findNext,
                this, &EditorWindow::findNext);
    }

    findDialog->show();
    findDialog->raise();
    findDialog->activateWindow();
}

См. также QDialogButtonBox, QTabWidget, QWidget, QProgressDialog, Справочник по проектированию графического интерфейса: Диалоговые окна, Стандартные, Пример расширения и Пример стандартных диалоговых окон.

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

enum QDialog::DialogCode

Значение, возвращаемое модальным диалоговым окном.

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

QDialog::QDialog(QWidget *parent = nullptr, Qt::WindowFlags f = Qt::WindowFlags())

Конструирует диалоговое окно с родителем parent.

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

Флаги виджетов f передаются конструктору QWidget. Например, если вы не хотите, чтобы в заголовке диалогового окна была кнопка «Что это?», передайте Qt::WindowTitleHint | Qt::WindowSystemMenuHint в f.

См. также QWidget::setWindowFlags().

[virtual slot] void QDialog::accept()

Скрывает модальное диалоговое окно и устанавливает код результата в Accepted.

См. также reject() и done().

[signal] void QDialog::accepted()

Этот сигнал испускается, когда диалоговое окно было принято либо пользователем, либо путем вызова accept() или done() с аргументом QDialog::Accepted.

Обратите внимание, что этот сигнал не испускается при скрытии диалогового окна с помощью hide() или setVisible(false). Это включает удаление диалогового окна, когда оно видимо.

См. также finished() и rejected().

[virtual slot] void QDialog::done(int r)

Закрывает диалоговое окно и устанавливает его код результата в r. Сигнал finished() будет испускать r; если r равен QDialog::Accepted или QDialog::Rejected, соответственно, будут испущены сигналы accepted() или rejected().

Если это диалоговое окно показано с помощью exec(), done() также заставляет локальную очередь событий завершиться, и exec() вернуть r.

Как и в случае с QWidget::close(), done() удаляет диалоговое окно, если установлен флаг Qt::WA_DeleteOnClose. Если диалоговое окно является основным виджетом приложения, приложение завершается. Если диалоговое окно является последним закрытым окном, испускается сигнал QApplication::lastWindowClosed().

См. также accept(), reject(), QApplication::activeWindow() и QCoreApplication::quit().

[virtual slot] int QDialog::exec()

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

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

Примечание: Избегайте использования этой функции; вместо неё используйте open(). В отличие от exec(), open() является асинхронным и не запускает дополнительную очередь событий. Это предотвращает возникновение ряда опасных ошибок (например, удаления родителя диалогового окна, пока диалоговое окно открыто через exec()). При использовании open() можно подключиться к сигналу finished() диалогового окна QDialog, чтобы получать уведомления о его закрытии.

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

[signal] void QDialog::finished(int result)

Этот сигнал испускается, когда код результата диалогового окна result установлен, либо пользователем, либо вызовом done(), accept() или reject().

Обратите внимание, что этот сигнал не испускается при скрытии диалогового окна с помощью hide() или setVisible(false). Это включает удаление диалогового окна, когда оно видимо.

См. также accepted() и rejected().

[virtual slot] void QDialog::open()

Отображает диалоговое окно как модальное диалоговое окно и возвращает значение немедленно.

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

[virtual slot] void QDialog::reject()

Скрывает модальное диалоговое окно и устанавливает код результата в Rejected.

См. также accept() и done().

[signal] void QDialog::rejected()

Этот сигнал испускается, когда диалоговое окно было отклонено пользователем или при вызове reject() или done() с аргументом QDialog::Rejected.

Обратите внимание, что этот сигнал не испускается при скрытии диалогового окна с помощью hide() или setVisible(false). Это включает удаление диалогового окна, когда оно отображено.

См. также finished() и accepted().

[virtual] QDialog::~QDialog()

Уничтожает QDialog, удаляя все его дочерние элементы.

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

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

[override virtual protected] void QDialog::contextMenuEvent(QContextMenuEvent *e)

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

[override virtual protected] bool QDialog::eventFilter(QObject *o, QEvent *e)

Переопределяет: QObject::eventFilter(QObject *watched, QEvent *event).

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

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

[override virtual] QSize QDialog::minimumSizeHint() const

Переопределяет функцию доступа к свойству: QWidget::minimumSizeHint.

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

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

int QDialog::result() const

В общем случае возвращает код результата модального диалогового окна, Accepted или Rejected.

Примечание: При вызове на экземпляре QMessageBox возвращаемое значение является значением перечисления QMessageBox::StandardButton.

Не вызывайте эту функцию, если диалоговое окно было создано с атрибутом Qt::WA_DeleteOnClose.

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

void QDialog::setResult(int i)

Устанавливает код результата модального диалогового окна в i.

Примечание: Рекомендуется использовать одно из значений, определенных в QDialog::DialogCode.

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

[override virtual] void QDialog::setVisible(bool visible)

Переопределяет функцию доступа к свойству: QWidget::visible.

[override virtual protected] void QDialog::showEvent(QShowEvent *event)

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

[override virtual] QSize QDialog::sizeHint() const

Переопределяет функцию доступа к свойству: QWidget::sizeHint.