Класс 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() для установки и управления кнопкой по умолчанию диалогового окна.

Клавиша Escape

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

Расширяемость

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

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

перечисление 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. Если диалоговое окно является основным виджетом приложения, приложение завершается. Если диалоговое окно является последним закрытым окном, испускается сигнал QGuiApplication::lastWindowClosed().

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

[virtual slot] int QDialog::exec()

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

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

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

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

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

void QDialog::setResult(int i)

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

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