Класс QDialog

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

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

Типы public

Свойства

• modal : bool
• sizeGripEnabled : bool

Функции public

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

Слот public

Сигналы

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

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

Диалоговое окно — это окно верхнего уровня, в основном используемое для краткосрочных задач и кратких коммуникаций с пользователем. 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) вместе для выполнения длительной операции, вы должны периодически вызывать QApplication::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();
}

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

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). Это включает удаление диалогового окна, пока оно отображается.

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

См. также 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). Это включает удаление диалогового окна, пока оно отображается.

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

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

[virtual slot] void QDialog::open()

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

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

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

[virtual slot] void QDialog::reject()

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

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

[signal] void QDialog::rejected()

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

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

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

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

[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::setVisible(bool visible).

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

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

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

Переопределяет: QWidget::sizeHint() const.