Класс QDialog

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

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

Открытые типы

Свойства

• modal : bool
• sizeGripEnabled : bool

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

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

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

Сигналы

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

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

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

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

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)

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

[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.