QDialog 类

QDialog 类是对话框窗口的基类。更多...

头：	#include <QDialog>
CMake:	find_package(Qt6 REQUIRED COMPONENTS Widgets) target_link_libraries(mytarget PRIVATE Qt6::Widgets)
qmake:	QT += widgets
继承：	QWidget
继承者：	QColorDialog , QErrorMessage , QFileDialog , QFontDialog , QInputDialog , QMessageBox , QProgressDialog ，和 QWizard

所有成员列表，包括继承成员

公共类型

enum	DialogCode { Accepted, Rejected }

特性

modal : bool
sizeGripEnabled : bool

公共函数

	QDialog (QWidget * parent = nullptr, Qt::WindowFlags f = Qt::WindowFlags())
virtual	~QDialog ()
bool	isSizeGripEnabled () const
int	result () const
void	setModal (bool modal )
void	setResult (int i )
void	setSizeGripEnabled (bool)

重实现公共函数

virtual QSize	minimumSizeHint () const override
virtual void	setVisible (bool visible ) override
virtual QSize	sizeHint () const override

公共槽

virtual void	accept ()
virtual void	done (int r )
virtual int	exec ()
virtual void	open ()
virtual void	reject ()

信号

void	accepted ()
void	finished (int result )
void	rejected ()

重实现保护函数

virtual void	closeEvent (QCloseEvent * e ) override
virtual void	contextMenuEvent (QContextMenuEvent * e ) override
virtual bool	eventFilter (QObject * o , QEvent * e ) override
virtual void	keyPressEvent (QKeyEvent * e ) override
virtual void	resizeEvent (QResizeEvent *) override
virtual void	showEvent (QShowEvent * event ) override

详细描述

对话框窗口是顶级窗口，主要用于短期任务和与用户简短交流。QDialogs 可以是模态 (或非模态) 的。QDialogs 可以提供返回值，且它们可以有默认按钮。QDialog 也可拥有 QSizeGrip 在其右下角，使用 setSizeGripEnabled ().

注意：QDialog (及任何其它 Widget 有类型 Qt::Dialog ) 使用父级 Widget 稍微异于其它 Qt 类。对话框始终是顶层 Widget，但若有父级，默认位置居中父级的顶层 Widget 顶部 (若它本身不在顶层)。它还会共享父级的任务栏条目。

使用重载 QWidget::setParent () 函数改变所有权对于 QDialog 小部件。此函数允许明确设置要重设父级的 Widget 的窗口标志；使用重载函数将清零 Widget 的窗口系统特性指定窗口标志 (尤其，将重置 Qt::Dialog 标志)。

注意： 对话框的父级关系 not 隐含对话框将始终被堆叠在父级窗口顶部。要确保对话框始终在顶部，使对话框模态。这也适用于对话框本身的子级窗口。要确保对话框的子级窗口停留在对话框顶部，也使子级窗口模态。

A modal 对话框是阻塞同一应用程序中其它可见窗口输入的对话框。通常用于从用户请求文件名 (或用于设置应用程序首选项) 的，是模态对话框。对话框可以为应用程序模态 (默认) 或窗口模态 .

打开应用程序模态对话框时，用户必须完成与对话框的交互并关闭对话框，在它们可以访问应用程序中的任何其它窗口之前。窗口模态对话框仅阻塞访问对话框关联的窗口，允许用户继续使用应用程序中的其它窗口。

显示模态对话框的最常见方式，是调用它的 exec () 函数。当用户关闭对话框时， exec () 将提供有用返回值 . To close the dialog and return the appropriate value, you must connect a default button, e.g. an OK 按钮到 accept () 槽和 Cancel 按钮到 reject () slot. Alternatively, you can call the done () 槽采用 接受 or Rejected .

替代是调用 setModal (true) 或 setWindowModality ()，然后 show ()。不像 exec (), show () 将控制立即返回给调用者。调用 setModal (true) 对于进度对话框尤其有用，用户必须拥有与对话框交互的能力 (如：取消长时间运行的操作)。若使用 show () 和 setModal (true) 一起以履行长时间操作，必须调用 QCoreApplication::processEvents () 在处理期间周期性地使用户能够与对话框进行交互。(见 QProgressDialog )。

非模态对话框

A modeless 对话框是独立于同一应用程序中其它窗口运转的对话框。文字处理程序中的查找替换对话框经常是非模态的，以允许用户与应用程序主窗口和对话框进行交互。

非模态对话框的显示是使用 show ()，将控制立即返回给调用者。

若援引 show () function after hiding a dialog, the dialog will be displayed in its original position. This is because the window manager decides the position for windows that have not been explicitly placed by the programmer. To preserve the position of a dialog that has been moved by the user, save its position in your closeEvent () handler and then move the dialog to that position, before showing it again.

默认按钮

对话框的 default 按钮是用户按下 Enter (Return) 键时按下的按钮。此按钮用于表示用户接受对话框设置并想要关闭对话框。使用 QPushButton::setDefault (), QPushButton::isDefault () 和 QPushButton::autoDefault () 以设置并控制对话框的默认按钮。

Esc 键

若用户在对话框中按下 Esc 键， QDialog::reject () 会被调用。这将导致窗口被关闭：关闭事件不可以为 ignored .

可扩展性

可扩展性是以 2 种方式展示对话框的能力：展示最常用选项的部分对话框，和展示所有选项的完整对话框。通常，可扩展对话框最初以部分对话框形式出现，但带有更多触发按钮。若用户按下更多 button down, the dialog is expanded.

模态对话框经常用于要求返回值的状况，如，指示用户是否按下 OK or Cancel 。可以关闭对话框通过调用 accept () 或 reject () 槽，和 exec () 会返回 接受 or Rejected 酌情。 exec () 调用返回对话框的结果。结果还可获取自 result () 若对话框未被销毁。

为修改对话框的关闭行为，可以重实现函数 accept (), reject () 或 done ()。 closeEvent () function should only be reimplemented to preserve the dialog's position or to override the standard close or reject behavior.

代码范例

模态对话框：

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

非模态对话框：

void EditorWindow::find()
{
    if (!findDialog) {
        findDialog = new FindDialog(this);
        connect(findDialog, &FindDialog::findNext,
                this, &EditorWindow::findNext);
    }
    findDialog->show();
    findDialog->raise();
    findDialog->activateWindow();
}

A dialog with an extension:

    mainLayout->setSizeConstraint(QLayout::SetFixedSize);
    findButton = new QPushButton(tr("&Find"));
    moreButton = new QPushButton(tr("&More..."));
    moreButton->setCheckable(true);
    extension = new ExtendedControls;
    mainLayout->addWidget(extension);
    extension->hide();
    connect(moreButton, &QAbstractButton::toggled, extension, &QWidget::setVisible);

By setting the sizeConstraint property of the dialog's layout to SetFixedSize , the dialog will not be resizable by the user, and will automatically shrink when the extension gets hidden.

另请参阅 QDialogButtonBox , QTabWidget , QWidget , QProgressDialog ，和标准对话框范例 .

成员类型文档编制

enum QDialog:: DialogCode

由模态对话框返回的值。

常量	值
`QDialog::Accepted`	`1`
`QDialog::Rejected`	`0`

特性文档编制

此特性保持是否 show () 应该以模态 (或非模态) 方式弹出对话框

默认情况下，此特性为 false and show () 以非模态方式弹出对话框。将此特性设为 true 相当于设置 QWidget::windowModality to Qt::ApplicationModal .

exec () 忽略此特性的值，并始终以模态方式弹出。

访问函数：

bool	isModal () const
void	setModal (bool modal )

另请参阅 QWidget::windowModality , show ()，和 exec ().

sizeGripEnabled : bool

此特性保持是否启用大小握把

A QSizeGrip 被放置在对话框右下角，当此属性被启用时。默认情况下，大小握把是禁用的。

访问函数：

bool	isSizeGripEnabled () const
void	setSizeGripEnabled (bool)

成员函数文档编制

`[explicit]` QDialog:: QDialog ( QWidget * parent = nullptr, Qt::WindowFlags f = Qt::WindowFlags())

构造对话框采用父级 parent .

对话框始终是顶层 Widget，但若有父级，默认位置居中父级顶部。它还会共享父级的任务栏条目。

Widget 标志 f 被传递给 QWidget 构造函数。例如，若不想要对话框标题栏中的 What's This 按钮，传递 Qt::WindowTitleHint | Qt::WindowSystemMenuHint in f .

另请参阅 QWidget::setWindowFlags ().

`[virtual noexcept]` QDialog:: ~QDialog ()

销毁 QDialog ，删除其所有子级。

`[virtual slot]` void QDialog:: accept ()

隐藏模态对话框并将结果代码设为 接受 .

另请参阅 reject () 和 done ().

`[signal]` void QDialog:: accepted ()

此信号被发射当已接受对话框由用户或通过调用 accept () 或 done () 采用 QDialog::Accepted 自变量。

注意，此信号 not 被发射当隐藏对话框采用 hide () 或 setVisible (false)。这包括可见时删除对话框。

另请参阅 finished () 和 rejected ().

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

重实现： QWidget::closeEvent (QCloseEvent *event).

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

重实现： QWidget::contextMenuEvent (QContextMenuEvent *event).

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

关闭对话框并将其结果代码设为 r 。 finished () signal will emit r ; if r is QDialog::Accepted or QDialog::Rejected ， accepted () 或 rejected () signals will also be emitted, respectively.

If this dialog is shown with exec (), done() also causes the local event loop to finish, and exec () 返回 r .

就像 QWidget::close ()，done() 删除对话框若 Qt::WA_DeleteOnClose 标志有设置。若对话框是应用程序 main 小部件，应用程序终止。若对话框是最后关闭窗口， QGuiApplication::lastWindowClosed () 信号发射。

另请参阅 accept (), reject (), QApplication::activeWindow ()，和 QCoreApplication::quit ().

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

重实现： QObject::eventFilter (QObject *watched, QEvent *event).

`[virtual slot]` int QDialog:: exec ()

把对话框展示成模态对话框，阻塞直到用户关闭它。函数返回 DialogCode 结果。

若对话框为应用程序模态，用户无法与同一应用程序中的任何其它窗口交互，直到关闭对话框为止。若对话框为窗口模态，仅阻塞与父级窗口的交互，当打开对话框时。默认情况下，对话框为应用程序模态。

注意： 避免使用此函数；取而代之，使用 open() 。不像 exec()， open () 是异步的，且不会产生额外的事件循环。这可以阻止发生一系列的危险 Bug (如：删除对话框的父级，当对话框凭借 exec() 打开时)。当使用 open (), 可以连接 finished () 信号对于 QDialog 到通知，当关闭对话框时。

另请参阅 open (), show (), result ()，和 setWindowModality ().

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

此信号被发射当对话框的 result 代码有设置，由用户或通过调用 done (), accept ()，或 reject ().

注意，此信号 not 被发射当隐藏对话框采用 hide () 或 setVisible (false)。这包括可见时删除对话框。

另请参阅 accepted () 和 rejected ().

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

重实现： QWidget::keyPressEvent (QKeyEvent *event).

`[override virtual]` QSize QDialog:: minimumSizeHint () const

重实现访问函数为特性： QWidget::minimumSizeHint .

`[virtual slot]` void QDialog:: open ()

把对话框展示成窗口模态对话框，立即返回。

另请参阅 exec (), show (), result ()，和 setWindowModality ().

`[virtual slot]` void QDialog:: reject ()

隐藏模态对话框并将结果代码设为 Rejected .

另请参阅 accept () 和 done ().

`[signal]` void QDialog:: rejected ()

此信号被发射当已拒绝对话框由用户或通过调用 reject () 或 done () 采用 QDialog::Rejected 自变量。

注意，此信号 not 被发射当隐藏对话框采用 hide () 或 setVisible (false)。这包括可见时删除对话框。

另请参阅 finished () 和 accepted ().

`[override virtual protected]` void QDialog:: resizeEvent ( QResizeEvent *)

重实现： QWidget::resizeEvent (QResizeEvent *event).

int QDialog:: result () const

一般而言，返回模态对话框的结果代码 接受 or 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 .

QDialog 类

公共类型

特性

公共函数

重实现公共函数

公共槽

信号

重实现保护函数

详细描述

模态对话框

非模态对话框

默认按钮

Esc 键

可扩展性

返回值 (模态对话框)

代码范例

成员类型文档编制

enum QDialog:: DialogCode

特性文档编制

modal : bool

sizeGripEnabled : bool

成员函数文档编制

[explicit] QDialog:: QDialog ( QWidget * parent = nullptr, Qt::WindowFlags f = Qt::WindowFlags())

[virtual noexcept] QDialog:: ~QDialog ()

[virtual slot] void QDialog:: accept ()

[signal] void QDialog:: accepted ()

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

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

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

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

[virtual slot] int QDialog:: exec ()

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

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

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

[virtual slot] void QDialog:: open ()

[virtual slot] void QDialog:: reject ()

[signal] void QDialog:: rejected ()

[override virtual protected] void QDialog:: resizeEvent ( QResizeEvent *)

int QDialog:: result () const

void QDialog:: setResult ( int i )

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

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

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

内容

`[explicit]` QDialog:: QDialog ( QWidget * parent = nullptr, Qt::WindowFlags f = Qt::WindowFlags())

`[virtual noexcept]` QDialog:: ~QDialog ()

`[virtual slot]` void QDialog:: accept ()

`[signal]` void QDialog:: accepted ()

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

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

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

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

`[virtual slot]` int QDialog:: exec ()

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

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

`[override virtual]` QSize QDialog:: minimumSizeHint () const

`[virtual slot]` void QDialog:: open ()

`[virtual slot]` void QDialog:: reject ()

`[signal]` void QDialog:: rejected ()

`[override virtual protected]` void QDialog:: resizeEvent ( QResizeEvent *)

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

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

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