对话框(02)：【类】QDialog [官翻]

QDialog Class

QDialog类是对话框窗口的基类。

Header	#include < QDialog >
qmake	QT += widgets
Inherits	QWidget
Inherited By	QColorDialog, QErrorMessage, QFileDialog, QFontDialog, QInputDialog, QMessageBox, QProgressDialog, and QWizard

详细说明

对话框窗口是一个顶层窗口，主要用于短期任务和简短地与用户的通信。QDialogs可以是模态的，也可以是非模态的。

QDialogs可以提供一个返回值，可以有默认按钮。QDialogs也可以使用setSizeGripEnabled() 在右下角有一个QSizeGrip。

请注意，QDialog(以及任何其他具有Qt::Dialog类型的小部件）使用的父小部件与Qt中的其他类稍有不同。对话框始终是顶级小部件，但如果它有父级小部件，则其默认位置位于父级的顶级小部件的顶部(如果它本身不是顶级小部件）。它还将共享父级的任务栏条目。

使用QWidget::setParent() 函数的重载来更改QDialog小部件的所有权。 此功能使您可以显式设置父级窗口小部件的窗口标志。 使用重载函数将清除为小部件指定窗口系统属性的窗口标志(特别是将重置Qt::Dialog标志）。

注意:对话框的父级关系并不意味着对话框总是堆叠在父窗口的顶部。要确保对话框始终位于顶部，请将对话框设为模态。这也适用于对话框本身的子窗口。若要确保对话框的子窗口位于对话框的顶部，请同时使子窗口成为模态窗口。

模态对话框

模态对话框是一种对话框，它阻止输入到同一应用程序中其他可见窗口的内容。用于向用户请求文件名或用于设置应用程序首选项的对话框通常是模式对话框。对话框可以是应用程序模式(默认）或窗口模式。

当打开应用程序模式对话框时，用户必须完成与对话框的交互并关闭它，然后才能访问应用程序中的任何其他窗口。窗口模式对话框仅阻止访问与该对话框关联的窗口，从而允许用户继续使用应用程序中的其他窗口。

显示模态对话框的最常见方法是调用其exec() 函数。当用户关闭对话框时，exec() 将提供有用的返回值。要关闭对话框并返回适当的值，您必须连接一个默认按钮，例如单击OK(确定）到accept() 插槽，然后单击Cancel(取消）。或者，您可以使用Accepted或Rejected调用done() 插槽。

另一种方法是调用setModal(true）或setWindowModality() ，然后调用show() 。与exec() 不同，show() 立即将控制权返回给调用者。调用setModal(true）对于进度对话框特别有用，在该对话框中用户必须具有与对话框进行交互的能力，例如取消长时间运行的操作。如果同时使用show() 和setModal(true）来执行较长的操作，则必须在处理期间定期调用QCoreApplication::processEvents() ，以使用户能够与对话框进行交互。 (请参阅QProgressDialog。）

非模态对话框

无模式对话框是独立于同一应用程序中其他窗口运行的对话框。 在文字处理器中查找和替换对话框通常是无模式的，以允许用户与应用程序的主窗口和对话框进行交互。

使用show() 显示无模式对话框，该控件立即将控制权返回给调用者。

如果在隐藏对话框后调用show() 函数，该对话框将以其原始位置显示。 这是因为窗口管理器决定了程序员未明确放置的窗口的位置。 要保留用户已移动的对话框的位置，请将其位置保存在closeEvent() 处理函数中，然后将对话框移至该位置，然后再次显示它。

默认按钮

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

Escape 键

如果用户在对话框中按Esc键，则将调用QDialog::reject() 。 这将导致窗口关闭：close事件不能忽略。

可扩展性

可扩展性是通过两种方式显示对话框的能力：显示最常用选项的部分对话框，以及显示所有选项的完整对话框。 通常，可扩展对话框最初将显示为部分对话框，但带有“More”切换按钮。 如果用户按下“More”按钮，则对话框将展开。 扩展示例【Extension Example】展示了如何使用Qt实现可扩展对话框。

返回值（模态对话框）

模态对话框通常用于需要返回值的情况，例如 指示用户按下“确定”还是“取消”。 可以通过调用accept() 或reject() 插槽关闭对话框，并且exec() 将视情况返回Accepted或Rejected。 exec() 调用返回对话框的结果。 如果对话框尚未销毁，结果也可从result() 获得。

为了修改对话框的关闭行为，您可以重新实现功能accept() ，reject() 或done() 。 仅应重新实现closeEvent() 函数，以保留对话框的位置或覆盖标准的关闭或拒绝行为。

Code Examples

// A modal dialog:
 void EditorWindow::countWords()
 {
     WordCountDialog dialog(this);
     dialog.setWordCount(document().wordCount());
     dialog.exec();
 }
// A modeless dialog:
 void EditorWindow::find()
 {
     if (!findDialog) {
         findDialog = new FindDialog(this);
         connect(findDialog, &FindDialog::findNext,
                 this, &EditorWindow::findNext);
     }

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

公共类型

enum DialogCode

模态对话框返回的值。

Constant	Value
QDialog::Rejected	0
QDialog::Accepted	1

属性

1. modal: bool show() 是否应以模式或无模式方式弹出对话框

   默认情况下，此属性为false，并且show() 弹出对话框为无模式。 将此属性设置为true等效于将QWidget::windowModality设置为Qt::ApplicationModal。

   exec() 忽略此属性的值，并始终以模式方式弹出对话框。

   • bool isModal() const
   • void setModal(bool modal)

2. sizeGripEnabled: bool 是否启用尺寸夹点

   启用此属性后，将在对话框的右下角放置一个QSizeGrip。 默认情况下，尺寸夹点是禁用的。

   • bool isSizeGripEnabled() const
   • void setSizeGripEnabled(bool)

公共函数

构造和析构

• QDialog(QWidget *parent = nullptr, Qt::WindowFlags f = Qt::WindowFlags())
• virtual ~QDialog()

属性相关

• bool isModal() const
  void setModal(bool modal)
• bool isSizeGripEnabled() const
  void setSizeGripEnabled(bool)

返回值

• int result() const
• void setResult(int i)

重写的公共函数

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

公共槽

• virtual void accept() 隐藏模式对话框，并将结果代码设置为“已接受”

• virtual void reject() 隐藏模式对话框，并将结果代码设置为“拒绝”

• virtual void done(int r) 关闭对话框并将其结果代码设置为 r

  finish() 信号将发出r; 如果r为QDialog::Accepted或QDialog::Rejected，则将分别发出accept() 或rejected() 信号。
  如果此对话框与exec() 一起显示，则done() 也会导致本地事件循环完成，并且exec() 返回r。

  与QWidget::close() 一样，如果设置了Qt::WA_DeleteOnClose标志，则done() 会删除对话框。 如果对话框是应用程序的主窗口小部件，则该应用程序终止。 如果对话框是最后关闭的窗口，则发出QApplication::lastWindowClosed() 信号。

• virtual int exec() 将对话框显示为模态对话框，直到用户将其关闭为止一直处于阻塞状态

  该函数返回DialogCode结果。
  如果对话框是应用程序模式的，则用户在关闭对话框之前无法与同一应用程序中的任何其他窗口进行交互。 如果对话框是窗口模式的，则在打开对话框时仅阻止与父窗口的交互。 默认情况下，对话框是应用程序模式的。

  注意：避免使用此功能； 而是使用open() 。 与exec() 不同，open() 是异步的，并且不会旋转其他事件循环。 这样可以防止发生一系列危险的错误（例如，在通过exec() 打开对话框时删除对话框的父级）。 使用open() 时，您可以连接到QDialog的finish() 信号，以在关闭对话框时得到通知。

• virtual void open() 将对话框显示为窗口模式对话框，立即返回

信号

• 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

参考

• 扩展示例 【Extension Example】
• 标准对话框示例【Standard Dialogs Example.】