| 頭： | #include <QDialog> |
| 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 () |
| const QMetaObject | staticMetaObject |
| 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 |
The QDialog 類是對話框窗口的基類。
對話框窗口是頂級窗口，主要用於短期任務和與用戶簡短交流。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
() 將提供有用
返迴值
。通常，為關閉對話框並返迴適當值，連接默認按鈕，如
OK
，到
accept
() 槽和
Cancel
按鈕到
reject
() 槽。另外，可以調用
done
() 槽采用
接受
or
Rejected
.
替代是調用 setModal (true) 或 setWindowModality ()，然後 show ()。不像 exec (), show () 將控製立即返迴給調用者。調用 setModal (true) 對於進度對話框尤其有用，用戶必須擁有與對話框交互的能力 (如：取消長時間運行的操作)。若使用 show () 和 setModal (true) 一起以履行長時間操作，必須調用 QApplication::processEvents () 在處理期間周期性地使用戶能夠與對話框進行交互。(見 QProgressDialog )。
A modeless 對話框是獨立於同一應用程序中其它窗口運轉的對話框。文字處理程序中的查找 替換對話框經常是非模態的，以允許用戶與應用程序主窗口和對話框進行交互。
非模態對話框的顯示是使用 show ()，將控製立即返迴給調用者。
若援引 show() 函數在隱藏對話框之後，對話框將顯示在其原始位置。這是因為窗口管理器決定程序員未明確放置窗口的位置。要保留用戶已移動對話框的位置，保存其位置在 closeEvent() 處理程序，然後把對話框移到該位置，在再次展示它之前。
對話框的 default 按鈕是用戶按下 Enter (Return) 鍵時按下的按鈕。此按鈕用於錶示用戶接受對話框設置並想要關閉對話框。使用 QPushButton::setDefault (), QPushButton::isDefault () 和 QPushButton::autoDefault () 以設置並控製對話框的默認按鈕。
若用戶在對話框中按下 Esc 鍵， QDialog::reject () 會被調用。這將導緻窗口被關閉： 關閉事件 不可以為 ignored .
可擴展性是以 2 種方式展示對話框的能力：展示最常用選項的部分對話框，和展示所有選項的完整對話框。通常，可擴展對話框最初以部分對話框形式齣現，但帶有 更多 觸發按鈕。若用戶按下 更多 按鈕，展開對話框。 擴展範例 展示如何使用 Qt 達成可擴展對話框。
模態對話框經常用於要求返迴值的狀況，如，指示用戶是否按下
OK
or
Cancel
。可以關閉對話框通過調用
accept
() 或
reject
() 槽，和
exec
() 會返迴
接受
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, SIGNAL(findNext()), this, SLOT(findNext())); } findDialog->show(); findDialog->raise(); findDialog->activateWindow(); }
另請參閱 QDialogButtonBox , QTabWidget , QWidget , QProgressDialog , GUI 設計手冊：對話框、標準 , 擴展範例 ，和 標準對話框範例 .
由模態對話框返迴的值。
| 常量 | 值 |
|---|---|
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 ) |
構造對話框采用父級 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)。這包括可見時刪除對話框。
該函數在 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 。 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 小部件，應用程序終止。若對話框是最後關閉窗口， 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()
。不像 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)。這包括可見時刪除對話框。
該函數在 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
.
[signal]
void
QDialog::
rejected
()
此信號被發射當已拒絕對話框由用戶或通過調用 reject () 或 done () 采用 QDialog::Rejected 自變量。
注意，此信號 not 被發射當隱藏對話框采用 hide () 或 setVisible (false)。這包括可見時刪除對話框。
該函數在 Qt 4.1 引入。
另請參閱 finished () 和 accepted ().
[override virtual protected]
void
QDialog::
resizeEvent
(
QResizeEvent *
)
重實現自 QWidget::resizeEvent ().
一般而言，返迴模態對話框的結果代碼
接受
or
Rejected
.
注意： 當調用 QMessageBox 實例，返迴值為 QMessageBox::StandardButton 枚舉。
不要調用此函數，若構造對話框具有 Qt::WA_DeleteOnClose 屬性。
另請參閱 setResult ().
將模態對話框的結果代碼設為 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 ().