Класс QDialog

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

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

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

Свойства

• modal : bool
• sizeGripEnabled : bool

• 58 свойств, унаследованных от QWidget
• 1 свойство, унаследованное от QObject

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

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

• 211 открытых функций, унаследованных от QWidget
• 31 открытых функций, унаследованных от QObject
• 14 открытых функций, унаследованных от QPaintDevice

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

• 19 открытых слотов, унаследованных от QWidget
• 1 открытый слот, унаследованный от QObject

Сигналы

• 3 сигнала, унаследованные от QWidget
• 2 сигнала, унаследованные от QObject

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

• 35 защищённых функций, унаследованных от QWidget
• 9 защищённых функций, унаследованных от QObject
• 1 защищённая функция, унаследованная от QPaintDevice

Дополнительные унаследованные члены

• 5 статических открытых членов, унаследованных от QWidget
• 11 статических открытых членов, унаследованных от QObject
• 35 защищённых функций, унаследованных от QWidget
• 9 защищённых функций, унаследованных от QObject
• 1 защищённая функция, унаследованная от QPaintDevice
• 1 защищённый слот, унаследованный от QWidget

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

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

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

Бесmodalные диалоги

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

Бесmodalные диалоги отображаются с помощью show(), который немедленно возвращает управление вызывающей стороне.

Если вы вызываете функцию show() после скрытия диалога, диалог будет отображен в его исходном положении. Это происходит потому, что менеджер окон определяет положение окон, которые не были явно размещены программистом. Чтобы сохранить положение диалога, который был перемещен пользователем, сохраните его положение в обработчике closeEvent(), а затем перед повторным отображением переместите диалог в это положение.

Кнопка по умолчанию

Кнопка по умолчанию диалога — это кнопка, на которую нажимается при нажатии пользователем клавиши Enter (Return). Эта кнопка используется для обозначения того, что пользователь принимает настройки диалога и хочет закрыть диалог. Используйте QPushButton::setDefault(), QPushButton::isDefault() и QPushButton::autoDefault() для установки и управления кнопкой по умолчанию диалога.

Клавиша Escape

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

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

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

Возвращаемое значение (modalные диалоги)

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

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

Примеры кода

Modalный диалог:

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

Бесmodalный диалог:

void EditorWindow::find()
{
    if (!findDialog) {
        findDialog = new FindDialog(this);
        connect(findDialog, SIGNAL(findNext()), this, SLOT(findNext()));
    }

    findDialog->show();
    findDialog->raise();
    findDialog->activateWindow();
}

См. также QDialogButtonBox, QTabWidget, QWidget, QProgressDialog, Руководство по проектированию графического интерфейса пользователя: диалоги, стандартные, Пример расширения и Пример стандартных диалогов.

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

перечисление QDialog::DialogCode

Значение, возвращаемое modalным диалогом.

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

QDialog::QDialog(QWidget *parent = Q_NULLPTR, Qt::WindowFlags f = Qt::WindowFlags())

Конструирует диалог с родителем parent.

Диалог всегда является виджетом верхнего уровня, но если у него есть родитель, его расположение по умолчанию центрируется поверх родителя. Он также будет разделять запись родителя в панели задач.

Флаги виджета f передаются конструктору QWidget. Например, если вы не хотите кнопки «Что это?» в строке заголовка диалога, передайте Qt::WindowTitleHint | Qt::WindowSystemMenuHint в f.

См. также QWidget::setWindowFlags().

QDialog::~QDialog()

Уничтожает QDialog, удаляя все его дочерние элементы.

[virtual slot] void QDialog::accept()

Скрывает modalный диалог и устанавливает код результата в Accepted.

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

[signal] void QDialog::accepted()

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

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

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

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

[virtual protected] void QDialog::closeEvent(QCloseEvent *e)

Переопределено из QWidget::closeEvent().

[virtual protected] void QDialog::contextMenuEvent(QContextMenuEvent *e)

Переопределено из QWidget::contextMenuEvent().

[virtual slot] void QDialog::done(int r)

Закрывает диалог и устанавливает его код результата в r. Если этот диалог показан с помощью exec(), done() завершает локальную очередь событий и exec() возвращает r.

Как и в QWidget::close(), done() удаляет диалог, если установлен флаг Qt::WA_DeleteOnClose. Если диалог является основным виджетом приложения, приложение завершается. Если диалог является последним закрытым окном, испускается сигнал QApplication::lastWindowClosed().

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

[virtual protected] bool QDialog::event(QEvent *e)

Переопределено из QObject::event().

[virtual protected] bool QDialog::eventFilter(QObject *o, QEvent *e)

Переопределено из QObject::eventFilter().

[virtual slot] int QDialog::exec()

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

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

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

[signal] void QDialog::finished(int result)

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

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

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

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

[virtual protected] void QDialog::keyPressEvent(QKeyEvent *e)

Переопределено из QWidget::keyPressEvent().

[virtual] QSize QDialog::minimumSizeHint() const

Переопределено из QWidget::minimumSizeHint().

[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 protected] void QDialog::resizeEvent(QResizeEvent *)

Переопределено из QWidget::resizeEvent().

int QDialog::result() const

В общем случае возвращает код результата модального диалогового окна, Accepted или Rejected.

Примечание: При вызове на экземпляре QMessageBox возвращаемое значение является значением из перечисления QMessageBox::StandardButton.

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

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

void QDialog::setResult(int i)

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

Примечание: Рекомендуется использовать одно из значений, определенных в QDialog::DialogCode.

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

[virtual] void QDialog::setVisible(bool visible)

Переопределено из QWidget::setVisible().

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

Переопределено из QWidget::showEvent().

[virtual] QSize QDialog::sizeHint() const

Переопределено из QWidget::sizeHint().