就业培训     下载中心     Wiki     联络 登录   注册
  1. 首页
  2. Qt 6.2.1
  3. Qt Widgets
  4. C++ 类
  5. QDialog

内容

QDialog 类

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

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

公共类型

enum DialogCode { Accepted, Rejected }

特性

公共函数

  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 () 槽采用 Accepted or Rejected .

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

非模态对话框

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

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

若援引 show() 函数在隐藏对话框之后，对话框将显示在其原始位置。这是因为窗口管理器决定程序员未明确放置窗口的位置。要保留用户已移动对话框的位置，保存其位置在 closeEvent() 处理程序，然后把对话框移到该位置，在再次展示它之前。

默认按钮

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

Esc 键

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

可扩展性

可扩展性是以 2 种方式展示对话框的能力：展示最常用选项的部分对话框，和展示所有选项的完整对话框。通常，可扩展对话框最初以部分对话框形式出现，但带有 更多 触发按钮。若用户按下 更多 按钮，展开对话框。 扩展范例 展示如何使用 Qt 达成可扩展对话框。

返回值 (模态对话框)

模态对话框经常用于要求返回值的状况，如，指示用户是否按下 OK or Cancel 。可以关闭对话框通过调用 accept () 或 reject () 槽，和 exec () 会返回 Accepted or 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, &FindDialog::findNext,
                this, &EditorWindow::findNext);
    }
    findDialog->show();
    findDialog->raise();
    findDialog->activateWindow();
}

另请参阅 QDialogButtonBox , QTabWidget , QWidget , QProgressDialog , GUI 设计手册：对话框、标准 , 扩展范例 ，和 标准对话框范例 .

成员类型文档编制

enum QDialog:: DialogCode

由模态对话框返回的值。

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

特性文档编制

modal : bool

此特性保持是否 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)

成员函数文档编制

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 slot] void QDialog:: accept ()

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

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

[signal] void QDialog:: accepted ()

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

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

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

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

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

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

[虚拟] QDialog:: ~QDialog ()

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

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

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

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

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

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

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

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

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

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

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

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

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

int QDialog:: result () const

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