Класс QDialog

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

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

Типы

Свойства

• modal : bool
• sizeGripEnabled : bool

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

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

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

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

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

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

Сигналы

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Ключ Esc

Если пользователь нажимает клавишу 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();
}

Бесприоритетный диалог:

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. Если этот диалог показан с помощью 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)

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