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 } |
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 键, QDialog::reject () 会被调用。这将导致窗口被关闭: 关闭事件 不可以为 ignored .
可扩展性是以 2 种方式展示对话框的能力:展示最常用选项的部分对话框,和展示所有选项的完整对话框。通常,可扩展对话框最初以部分对话框形式出现,但带有 More 触发按钮。若用户按下 More 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:
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);
另请参阅 QDialogButtonBox , QTabWidget , QWidget , QProgressDialog ,和 标准对话框范例 .
由模态对话框返回的值。
常量 | 值 |
---|---|
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 ().
此特性保持是否启用大小握把
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 ().
[虚拟]
QDialog::
~QDialog
()
销毁 QDialog ,删除其所有子级。
[virtual slot]
void
QDialog::
accept
()
隐藏模态对话框并将结果代码设为
接受
.
[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
.
[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).
一般而言,返回模态对话框的结果代码
接受
or
Rejected
.
注意: 当调用 QMessageBox 实例,返回值为 QMessageBox::StandardButton 枚举。
不要调用此函数,若构造对话框具有 Qt::WA_DeleteOnClose 属性。
另请参阅 setResult ().
将模态对话框的结果代码设为 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 .