Класс QDialog

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

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

Типы public

Свойства

• modal : bool
• sizeGripEnabled : bool

Public функции

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

Public слоты

Сигналы

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

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

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

Эта функция была представлена в 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.