QDialog Class
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() |
신호
재구현된 보호 함수
| 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 |
상세 설명
대화 상자(dialog window)는 주로 단기적인 작업이나 사용자와의 간단한 소통을 위해 사용되는 최상위 창입니다. QDialog는 모달(modal)이거나 비모달(modeless)일 수 있습니다. QDialog는 대화 상자 제목( return value)을 제공할 수 있으며, 대화 상자 제목( default buttons)을 가질 수도 있습니다. 또한 QDialog는 setSizeGripEnabled()를 사용하여 오른쪽 하단 모서리에 대화 상자 닫기 버튼( QSizeGrip )을 배치할 수 있습니다.
QDialog(및 ` Qt::Dialog` 유형을 갖는 다른 모든 위젯)는 Qt의 다른 클래스와는 약간 다르게 부모 위젯을 사용한다는 점에 유의하십시오. 대화 상자는 항상 최상위 위젯이지만, 부모가 있는 경우(대화 상자 자체가 최상위 위젯이 아닌 경우) 기본적으로 부모의 최상위 위젯 상단 중앙에 배치됩니다. 또한 부모 위젯의 작업 표시줄 항목도 공유하게 됩니다.
QWidget::setParent() 함수의 오버로드를 사용하여 QDialog 위젯의 소유권을 변경하십시오. 이 함수를 사용하면 부모가 변경된 위젯의 창 플래그를 명시적으로 설정할 수 있습니다. 오버로드된 함수를 사용하면 위젯의 창 시스템 속성을 지정하는 창 플래그가 지워집니다(특히 Qt::Dialog 플래그가 재설정됩니다).
참고: 대화 상자의 부모관계가 있다고 해서 대화 상자가 항상 부모 창 위에 중첩된다는 것을 의미하지는 않습니다. 대화 상자가 항상 최상단에 표시되도록 하려면 대화 상자를 모달로 설정하십시오. 이는 대화 상자 자체의 자식 창에도 적용됩니다. 대화 상자의 자식 창이 대화 상자 위에 항상 표시되도록 하려면 자식 창도 모달로 설정하십시오.
모달 대화 상자
모달 대화 상자는 동일한 애플리케이션 내의 다른 표시된 창에 대한 입력을 차단하는 대화 상자입니다. 사용자에게 파일 이름을 요청하거나 애플리케이션 기본 설정을 지정하는 데 사용되는 대화 상자는 대개 모달입니다. 대화 상자는 application modal (기본값) 또는 window modal 일 수 있습니다.
애플리케이션 모달 대화 상자가 열리면, 사용자는 해당 대화 상자와의 상호 작용을 완료하고 닫아야만 애플리케이션 내의 다른 창에 접근할 수 있습니다. 창 모달 대화 상자는 해당 대화 상자와 연결된 창에 대한 접근만 차단하므로, 사용자는 애플리케이션 내의 다른 창을 계속 사용할 수 있습니다.
모달 대화 상자를 표시하는 가장 일반적인 방법은 open() 함수를 호출하는 것입니다. 또는 setModal(true) 또는 setWindowModality()를 호출한 다음, show()를 호출할 수도 있습니다. 두 경우 모두 대화 상자가 표시되면 제어권은 즉시 호출자에게 반환됩니다. 대화 상자가 언제 닫히는지 및 대화 상자의 return value 가 무엇인지 확인하려면 finished() 신호에 연결해야 합니다. 또는 accepted() 및 rejected() 신호에 연결할 수도 있습니다.
사용자 정의 대화 상자를 구현할 때, 대화 상자를 닫고 적절한 값을 반환하려면 기본 버튼(예: 확인 버튼)을 accept() 슬롯에 연결하고, 취소 버튼을 reject() 슬롯에 연결하십시오. 또는 Accepted 또는 Rejected 을 사용하여 done() 슬롯을 호출할 수도 있습니다.
오래 걸리는 작업을 수행하기 위해 모달 대화 상자를 표시하는 경우, GUI 스레드에 지장을 주지 않도록 백그라운드 작업자 스레드에서 해당 작업을 수행하는 것이 좋습니다.
참고: exec()을 호출하여 모달 대화 상자를 차단 모드로 표시하는 방법이있습니다 . 이 경우, 대화 상자가 닫힐 때만 컨트롤이 GUI 스레드로 돌아갑니다. 그러나 이러한 방식은 중첩된 이벤트 루프를 생성하므로 일부 플랫폼에서 완전히 지원되지 않을 수 있으므로 권장되지 않습니다.
비모달 대화 상자
비모달 대화 상자는 동일한 애플리케이션 내의 다른 창과 독립적으로 작동하는 대화 상자입니다. 워드 프로세서의 찾기 및 바꾸기 대화 상자는 사용자가 애플리케이션의 메인 창과 대화 상자 모두를 동시에 조작할 수 있도록 하기 위해 종종 비모달 방식으로 구현됩니다.
비모드 대화 상자는 ` show()` 함수를 사용하여 표시되며, 이 함수는 호출자에게 즉시 제어권을 반환합니다.
대화 상자를 숨긴 후 ` show()` 함수를 호출하면, 대화 상자는 원래 위치에 표시됩니다. 이는 프로그래머가 명시적으로 위치를 지정하지 않은 창에 대해서는 윈도우 관리자가 위치를 결정하기 때문입니다. 사용자가 이동시킨 대화 상자의 위치를 유지하려면, ` closeEvent()` 핸들러에서 해당 위치를 저장한 다음, 대화 상자를 다시 표시하기 전에 해당 위치로 이동시켜야 합니다.
기본 버튼
대화 상자의 기본 버튼은 사용자가 Enter(Return) 키를 누를 때 선택되는 버튼입니다. 이 버튼은 사용자가 대화 상자의 설정을 수락하고 대화 상자를 닫고자 함을 나타내는 데 사용됩니다. QPushButton::setDefault(), QPushButton::isDefault() 및 QPushButton::autoDefault() 함수를 사용하여 대화 상자의 기본 버튼을 설정하고 제어할 수 있습니다.
Esc 키
사용자가 대화 상자에서 Esc 키를 누르면 QDialog::reject()이 호출됩니다. 이로 인해 창이 닫히게 됩니다. close event 는 ignored 일 수 없습니다.
확장성
확장성은 가장 자주 사용되는 옵션만 표시하는 부분 대화 상자와 모든 옵션을 표시하는 전체 대화 상자, 두 가지 방식으로 대화 상자를 표시할 수 있는 기능을 말합니다. 일반적으로 확장 가능한 대화 상자는 처음에 부분 대화 상자로 나타나지만, ‘ More ’ 토글 버튼이 함께 표시됩니다. 사용자가 ‘ More ’ 버튼을 누르면 대화 상자가 확장됩니다.
반환 값 (모달 대화상자)
모달 대화 상자는 반환 값이 필요한 상황에서 자주 사용됩니다. 예를 들어, 사용자가 ‘ OK ’을 눌렀는지, 아니면 ‘ Cancel ’을 눌렀는지를 나타내는 경우 등이 있습니다. 대화 상자는 accept() 또는 reject() 슬롯을 호출하여 닫을 수 있으며, exec()은 상황에 따라 Accepted 또는 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();
}확장 기능을 갖춘 대화 상자:
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);대화 상자 레이아웃의 ` sizeConstraint ` 속성을 ` SetFixedSize`로 설정하면, 사용자가 대화 상자의 크기를 조정할 수 없게 되며, 확장 프로그램이 숨겨지면 대화 상자가 자동으로 축소됩니다.
QDialogButtonBox, QTabWidget, QWidget, QProgressDialog 및 표준 대화 상자 예제도참조하십시오 .
속성 설명
modal : bool
이 속성은 show() 함수가 대화 상자를 모달 방식으로 표시할지, 아니면 비모달 방식으로 표시할지를 결정합니다.
기본적으로 이 속성은 ` false `이며, ` show()`는 대화 상자를 비모달 방식으로 표시합니다. 이 속성을 `true`로 설정하는 것은 ` QWidget::windowModality `을 ` Qt::ApplicationModal`로 설정하는 것과 동일합니다.
exec()는 이 속성의 값을 무시하고 항상 대화 상자를 모달 방식으로 표시합니다.
액세스 함수:
| bool | isModal() const |
| void | setModal(bool modal) |
QWidget::windowModality, show() 및 exec()도 참조하십시오 .
sizeGripEnabled : bool
이 속성은 크기 조절 손잡이가 활성화되어 있는지 여부를 나타냅니다.
이 속성이 활성화되면 대화 상자의 오른쪽 하단 모서리에 크기 조정 손잡이( QSizeGrip )가 표시됩니다. 기본적으로 크기 조정 손잡이는 비활성화되어 있습니다.
액세스 함수:
| bool | isSizeGripEnabled() const |
| void | setSizeGripEnabled(bool) |
멤버 함수 문서
[explicit] QDialog::QDialog(QWidget *parent = nullptr, Qt::WindowFlags f = Qt::WindowFlags())
parent 를 부모로 하는 대화 상자를 생성합니다.
대화 상자는 항상 최상위 위젯이지만, 부모가 있는 경우 기본적으로 부모 위젯의 중앙에 배치됩니다. 또한 부모의 작업 표시줄 항목도 공유합니다.
위젯 플래그 ` f `는 ` QWidget ` 생성자에 전달됩니다. 예를 들어, 대화 상자의 제목 표시줄에 'What's This' 버튼을 표시하지 않으려면 ` f`에서 ` Qt::WindowTitleHint ` | ` Qt::WindowSystemMenuHint `을 전달하십시오.
QWidget::setWindowFlags()도 참조하십시오 .
[virtual noexcept] QDialog::~QDialog()
QDialog 를 삭제하고, 그 모든 자식 노드를 제거합니다.
[virtual slot] void QDialog::accept()
모달 대화 상자를 숨기고 결과 코드를 ` Accepted`로 설정합니다.
[signal] void QDialog::accepted()
이 신호는 사용자가 대화 상자를 수락했거나, ` QDialog::Accepted ` 인수를 사용하여 ` accept()` 또는 ` done()`를 호출했을 때 발생합니다.
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()` 신호는 ` r`을 발생시킵니다. ` r `가 ` QDialog::Accepted ` 또는 ` QDialog::Rejected`인 경우, 각각 ` accepted()` 또는 ` rejected()` 신호도 발생합니다.
이 대화 상자가 exec()을 통해 표시된 경우, done()은 로컬 이벤트 루프를 종료시키고, exec()이 r 을 반환하도록 합니다.
QWidget::close()와 마찬가지로, Qt::WA_DeleteOnClose 플래그가 설정된 경우 done()은 대화 상자를 삭제합니다. 대화 상자가 애플리케이션의 메인 위젯인 경우, 애플리케이션이 종료됩니다. 대화 상자가 마지막으로 닫힌 창인 경우, 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()
이 대화 상자를 ‘ modal dialog ’ 모드로 표시하며, 사용자가 닫을 때까지 다른 작업을 차단합니다. 이 함수는 ‘ DialogCode ’ 결과를 반환합니다.
대화 상자가 ‘ application modal ’인 경우, 사용자는 대화 상자를 닫을 때까지 동일한 애플리케이션 내의 다른 창과 상호작용할 수 없습니다. 대화 상자가 ‘ window modal ’인 경우, 대화 상자가 열려 있는 동안 부모 창과의 상호작용만 차단됩니다. 기본적으로 대화 상자는 애플리케이션 모달입니다.
참고: 이 함수의 사용은피하고 , 대신 ` open()`를 사용하십시오. `exec()`와 달리 ` open()`는 비동기적이며, 추가적인 이벤트 루프를 생성하지 않습니다. 이를 통해 일련의 위험한 버그(예: `exec()`를 통해 대화 상자가 열려 있는 동안 대화 상자의 부모 창을 삭제하는 경우)가 발생하는 것을 방지할 수 있습니다. open()을 사용할 때는 QDialog 의 finished() 신호에 연결하여 대화 상자가 닫혔을 때 알림을 받을 수 있습니다.
open(), show(), result(), setWindowModality()도 참조하십시오 .
[signal] void QDialog::finished(int result)
이 신호는 사용자가 직접 설정했거나 done(), accept(), reject()를 호출하여 대화 상자의 result 코드가 설정되었을 때 발생합니다.
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()
window modal dialog 로 대화 상자를 표시하고 즉시 반환합니다.
exec(), show(), result(), setWindowModality()도 참조하십시오 .
[virtual slot] void QDialog::reject()
모달 대화 상자를 숨기고 결과 코드를 ` Rejected`로 설정합니다.
[signal] void QDialog::rejected()
이 신호는 사용자가 대화 상자를 닫았거나, ` QDialog::Rejected ` 인수를 사용하여 ` reject()` 또는 ` done()`를 호출하여 대화 상자가 닫혔을 때 발생합니다.
hide() 또는 setVisible(false)를 사용하여 대화 상자를 숨길 때는 이 신호가 발생하지 않는다는 점에 유의하십시오. 여기에는 대화 상자가 표시된 상태에서 삭제하는 경우도 포함됩니다.
finished() 및 accepted()도 참조하십시오 .
[override virtual protected] void QDialog::resizeEvent(QResizeEvent *)
QWidget::resizeEvent(QResizeEvent *event)를 재구현합니다.
int QDialog::result() const
일반적으로 모달 대화 상자의 결과 코드인 ` Accepted ` 또는 ` 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 속성에 대한 액세스 함수를 다시 구현합니다.
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.