Класс QDialog

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

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

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

Свойства

• modal : bool
• sizeGripEnabled : bool

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

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

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

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

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

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

Сигналы

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

Статические открытые члены

• 5 статических открытых членов унаследовано от QWidget
• 9 статических открытых членов унаследовано от QObject

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

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

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

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

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

Класс QDialog — базовый класс диалоговых окон.

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

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

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

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

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

Стандартная кнопка

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

Клавиша Escape

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

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

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

Значение возврата (модальные диалоговые окна)

Модальные диалоговые окна часто используются в ситуациях, когда требуется значение возврата, например, для указания того, нажал ли пользователь кнопку OK или Отмена. Диалоговое окно можно закрыть, вызвав слоты 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, SIGNAL(findNext()), this, SLOT(findNext()));
    }

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

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

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

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

Возвращаемое значение модального диалогового окна.

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

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

Создаёт диалоговое окно с родителем parent.

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

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

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

[virtual] 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. Сигнал 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().

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

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

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

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