Класс QDialog

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

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

Типы Public

Свойства

• modal : bool
• sizeGripEnabled : bool

Функции Public

Реализованные функции Public

Слот Public

Сигналы

Реализованные защищенные функции

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

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

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

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

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

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

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

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

Наиболее распространенный способ отображения модального диалога — вызов его функции exec(). Когда пользователь закрывает диалог, exec() предоставляет полезное возвращаемое значение. Чтобы закрыть диалог и вернуть соответствующее значение, вы должны подключить кнопку по умолчанию, например, кнопку OK к слоту 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() для установки и управления кнопкой по умолчанию диалогового окна.

Клавиша Escape

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

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

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

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

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

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

Примеры кода

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

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

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

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)

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