Класс QDialog

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

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

Типы public

Свойства

• modal : bool
• sizeGripEnabled : bool

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

Функции public

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

• 214 функций public, унаследованных от QWidget
• 32 функции public, унаследованных от QObject
• 14 функций public, унаследованных от QPaintDevice

Слот public

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

Сигналы

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

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

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

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

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

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

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

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

Беспрепятственные диалоги

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

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

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

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

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

Кнопка Esc

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

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

Расширяемость — это возможность отображения диалога двумя способами: частичный диалог, показывающий наиболее часто используемые параметры, и полный диалог, показывающий все параметры. Как правило, расширяемый диалог первоначально отображается как частичный диалог, но с кнопкой переключения «Ещё». Если пользователь нажимает кнопку «Ещё», диалог расширяется. Пример расширяемых диалогов с использованием 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, SIGNAL(findNext()), this, SLOT(findNext()));
    }

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

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

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

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

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

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

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()

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

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

[signal] void QDialog::accepted()

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

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

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

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

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

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

[override 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().

[override 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)

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

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

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

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

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

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

[override 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().

[override 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().

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

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

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

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

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

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