QDialogButtonBox Class
QDialogButtonBox 클래스는 현재 위젯 스타일에 적합한 레이아웃으로 버튼을 표시하는 위젯입니다. 더 보기...
| 헤더: | #include <QDialogButtonBox> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Widgets) target_link_libraries(mytarget PRIVATE Qt6::Widgets) |
| qmake: | QT += widgets |
| 상속: | QWidget |
공개 유형
| enum | ButtonLayout { WinLayout, MacLayout, KdeLayout, GnomeLayout, AndroidLayout } |
| enum | ButtonRole { InvalidRole, AcceptRole, RejectRole, DestructiveRole, ActionRole, …, ResetRole } |
| enum | StandardButton { Ok, Open, Save, Cancel, Close, …, NoButton } |
| flags | StandardButtons |
속성
- centerButtons : bool
- orientation : Qt::Orientation
- standardButtons : StandardButtons
공개 함수
| QDialogButtonBox(QWidget *parent = nullptr) | |
| QDialogButtonBox(QDialogButtonBox::StandardButtons buttons, QWidget *parent = nullptr) | |
| QDialogButtonBox(Qt::Orientation orientation, QWidget *parent = nullptr) | |
| QDialogButtonBox(QDialogButtonBox::StandardButtons buttons, Qt::Orientation orientation, QWidget *parent = nullptr) | |
| virtual | ~QDialogButtonBox() |
| QPushButton * | addButton(QDialogButtonBox::StandardButton button) |
| void | addButton(QAbstractButton *button, QDialogButtonBox::ButtonRole role) |
| QPushButton * | addButton(const QString &text, QDialogButtonBox::ButtonRole role) |
| QPushButton * | button(QDialogButtonBox::StandardButton which) const |
| QDialogButtonBox::ButtonRole | buttonRole(QAbstractButton *button) const |
| QList<QAbstractButton *> | buttons() const |
| bool | centerButtons() const |
| void | clear() |
| Qt::Orientation | orientation() const |
| void | removeButton(QAbstractButton *button) |
| void | setCenterButtons(bool center) |
| void | setOrientation(Qt::Orientation orientation) |
| void | setStandardButtons(QDialogButtonBox::StandardButtons buttons) |
| QDialogButtonBox::StandardButton | standardButton(QAbstractButton *button) const |
| QDialogButtonBox::StandardButtons | standardButtons() const |
신호
| void | accepted() |
| void | clicked(QAbstractButton *button) |
| void | helpRequested() |
| void | rejected() |
정적 공용 멤버
(since 6.12) QKeySequence | standardButtonShortcut(QDialogButtonBox::StandardButton button) |
(since 6.12) QString | standardButtonText(QDialogButtonBox::StandardButton button) |
재구현된 보호 함수
| virtual void | changeEvent(QEvent *event) override |
| virtual bool | event(QEvent *event) override |
상세 설명
대화 상자와 메시지 상자는 일반적으로 해당 플랫폼의 인터페이스 지침에 부합하는 레이아웃으로 버튼을 표시합니다. 플랫폼마다 대화 상자의 레이아웃은 항상 서로 다릅니다. QDialogButtonBox를 사용하면 개발자가 버튼을 추가할 수 있으며, 사용자의 데스크톱 환경에 적합한 레이아웃이 자동으로 적용됩니다.
대화 상자의 대부분의 버튼은 특정 역할을 수행합니다. 이러한 역할에는 다음이 포함됩니다:
- 대화 상자를 수락하거나 거부하는 역할.
- 도움을 요청하는 것.
- 대화 상자 자체에 대한 작업 수행(예: 필드 재설정 또는 변경 사항 적용).
또한 대화 상자를 닫는 다른 방법이 있을 수 있으며, 이는 치명적인 결과를 초래할 수도 있습니다.
대부분의 대화 상자에는 거의 표준으로 간주될 수 있는 버튼들이 있습니다(예: '확인(Accept)' OK 및 '취소(Cancel)' Cancel 버튼). 때로는 이러한 버튼들을 표준적인 방식으로 생성하는 것이 편리합니다.
QDialogButtonBox를 사용하는 방법에는 몇 가지가 있습니다. 한 가지 방법은 버튼(또는 버튼 텍스트)을 직접 생성하여 역할을 지정하고 버튼 상자에 추가하는 것입니다.
QDialogButtonBox *buttonBox = new QDialogButtonBox(Qt::Vertical);
buttonBox->addButton(findButton, QDialogButtonBox::ActionRole);
buttonBox->addButton(moreButton, QDialogButtonBox::ActionRole);또는 QDialogButtonBox가 제공하는 여러 표준 버튼(예: OK, Cancel, Save)을 사용할 수도 있습니다. 이 버튼들은 플래그 형태로 존재하므로 생성자에서 OR 연산을 통해 조합할 수 있습니다.
buttonBox = new QDialogButtonBox(QDialogButtonBox::Ok
| QDialogButtonBox::Cancel);
connect(buttonBox, &QDialogButtonBox::accepted, this, &QDialog::accept);
connect(buttonBox, &QDialogButtonBox::rejected, this, &QDialog::reject);일반 버튼과 표준 버튼을 혼합하여 사용할 수 있습니다.
현재 버튼 상자가 가로 방향인 경우, 버튼은 다음과 같은 방식으로 배열됩니다:
GnomeLayout 가로 방향 | 가로로 배치된 버튼 상자 GnomeLayout |
KdeLayout 가로 | 버튼 상자가 가로 방향으로 배치된 경우 KdeLayout |
MacLayout 가로 | 버튼 박스가 가로로 배치됨 MacLayout |
WinLayout 가로 | 버튼 박스가 가로로 배치됨 WinLayout |
버튼 상자가 세로 방향인 경우 버튼은 다음과 같이 배열됩니다:
또한, ` ActionRole ` 또는 ` HelpRole ` 속성이 적용된 버튼만 포함된 버튼 상자는 모달이 아닌 것으로 간주되며, macOS에서는 다른 모양으로 표시됩니다:
버튼 박스 내의 버튼이 클릭되면, 실제로 눌린 버튼에 대해 clicked() 신호가 발생합니다. 편의상, 버튼에 AcceptRole, RejectRole 또는 HelpRole 가 설정되어 있는 경우, 각각 accepted(), rejected() 또는 helpRequested() 신호가 발생합니다.
특정 버튼을 기본값으로 설정하려면 해당 버튼에 대해 직접 ` QPushButton::setDefault()`를 호출해야 합니다. 그러나 기본 버튼이 설정되어 있지 않은 경우, ` QPushButton::autoDefault ` 속성을 사용할 때 플랫폼 간에 기본 버튼이 일관되게 유지되도록 하기 위해, `QDialogButtonBox`가 표시될 때 `accept` 역할을 가진 첫 번째 푸시 버튼이 기본 버튼으로 지정됩니다.
QMessageBox, QPushButton 및 QDialog도 참조하십시오 .
멤버 유형 문서
enum QDialogButtonBox::ButtonLayout
이 열거형은 버튼 상자에 포함된 버튼을 배치할 때 사용할 레이아웃 정책을 설명합니다.
| 상수 | 값 | 설명 |
|---|---|---|
QDialogButtonBox::WinLayout | 0 | Windows 애플리케이션에 적합한 정책을 사용합니다. |
QDialogButtonBox::MacLayout | 1 | macOS 애플리케이션에 적합한 정책을 사용합니다. |
QDialogButtonBox::KdeLayout | 2 | KDE의 애플리케이션에 적합한 정책을 사용합니다. |
QDialogButtonBox::GnomeLayout | 3 | GNOME의 애플리케이션에 적합한 정책을 사용합니다. |
QDialogButtonBox::AndroidLayout | 4 | Android 애플리케이션에 적합한 정책을 사용합니다. 이 열거형 값은 Qt 5.10에서 추가되었습니다. |
버튼 레이아웃은 ` current style`에 의해 지정됩니다. 그러나 X11 플랫폼에서는 데스크톱 환경의 영향을 받을 수 있습니다.
enum QDialogButtonBox::ButtonRole
이 열거형은 버튼 상자 내의 버튼을 설명하는 데 사용할 수 있는 역할을 정의합니다. 이러한 역할의 조합은 버튼 동작의 다양한 측면을 설명하는 데 사용되는 플래그 역할을 합니다.
| 상수 | 값 | 설명 |
|---|---|---|
QDialogButtonBox::InvalidRole | -1 | 버튼이 유효하지 않습니다. |
QDialogButtonBox::AcceptRole | 0 | 버튼을 클릭하면 대화 상자가 수락됩니다(예: 확인). |
QDialogButtonBox::RejectRole | 1 | 이 버튼을 클릭하면 대화 상자가 거부됩니다(예: 취소). |
QDialogButtonBox::DestructiveRole | 2 | 이 버튼을 클릭하면 되돌릴 수 없는 변경(예: 변경 내용 취소)이 발생하고 대화 상자가 닫힙니다. |
QDialogButtonBox::ActionRole | 3 | 이 버튼을 클릭하면 대화 상자 내의 요소가 변경됩니다. |
QDialogButtonBox::HelpRole | 4 | 이 버튼을 클릭하면 도움말을 요청할 수 있습니다. |
QDialogButtonBox::YesRole | 5 | 이 버튼은 “예”와 유사한 버튼입니다. |
QDialogButtonBox::NoRole | 6 | 이 버튼은 "아니요"와 유사한 버튼입니다. |
QDialogButtonBox::ApplyRole | 8 | 이 버튼을 누르면 현재 변경 사항이 적용됩니다. |
QDialogButtonBox::ResetRole | 7 | 이 버튼을 누르면 대화 상자의 필드가 기본값으로 재설정됩니다. |
StandardButton도 참조하십시오 .
enum QDialogButtonBox::StandardButton
flags QDialogButtonBox::StandardButtons
이 열거형들은 표준 버튼에 대한 플래그를 설명합니다. 각 버튼에는 정의된 ButtonRole 가 있습니다.
| 상수 | 값 | 설명 |
|---|---|---|
QDialogButtonBox::Ok | 0x00000400 | AcceptRole 로 정의된 "OK" 버튼. |
QDialogButtonBox::Open | 0x00002000 | AcceptRole 로 정의된 "열기" 버튼입니다. |
QDialogButtonBox::Save | 0x00000800 | AcceptRole 로 정의된 "Save" 버튼. |
QDialogButtonBox::Cancel | 0x00400000 | RejectRole 로 정의된 “Cancel” 버튼. |
QDialogButtonBox::Close | 0x00200000 | RejectRole 로 정의된 "닫기" 버튼. |
QDialogButtonBox::Discard | 0x00800000 | 플랫폼에 따라 "취소" 또는 "저장하지 않음" 버튼으로, DestructiveRole 로 정의됩니다. |
QDialogButtonBox::Apply | 0x02000000 | ApplyRole 로 정의된 "적용" 버튼. |
QDialogButtonBox::Reset | 0x04000000 | ResetRole 로 정의된 "Reset" 버튼. |
QDialogButtonBox::RestoreDefaults | 0x08000000 | ResetRole 로 정의된 "기본값 복원" 버튼. |
QDialogButtonBox::Help | 0x01000000 | HelpRole 으로 정의된 "도움말" 버튼. |
QDialogButtonBox::SaveAll | 0x00001000 | AcceptRole 로 정의된 "모두 저장" 버튼. |
QDialogButtonBox::Yes | 0x00004000 | YesRole 로 정의된 "예" 버튼. |
QDialogButtonBox::YesToAll | 0x00008000 | YesRole 로 정의된 "모두 예" 버튼. |
QDialogButtonBox::No | 0x00010000 | NoRole 로 정의된 "아니요" 버튼. |
QDialogButtonBox::NoToAll | 0x00020000 | NoRole 로 정의된 "모두 아니오" 버튼. |
QDialogButtonBox::Abort | 0x00040000 | RejectRole 로 정의된 "취소" 버튼. |
QDialogButtonBox::Retry | 0x00080000 | AcceptRole 로 정의된 "재시도" 버튼. |
QDialogButtonBox::Ignore | 0x00100000 | AcceptRole 로 정의된 "Ignore" 버튼. |
QDialogButtonBox::NoButton | 0x00000000 | 유효하지 않은 버튼입니다. |
StandardButtons 유형은 QFlags<StandardButton>에 대한 typedef입니다. 이 유형은 StandardButton 값들의 OR 조합을 저장합니다.
ButtonRole 및 standardButtons도 참조하십시오 .
속성 문서
centerButtons : bool
이 속성은 버튼 상자 내의 버튼이 중앙에 정렬되는지 여부를 결정합니다.
기본적으로 이 속성의 값은 ` false`입니다. 이 동작은 대부분의 대화 상자 유형에 적합합니다. 주목할 만한 예외는 대부분의 플랫폼(예: Windows)에서 메시지 상자의 경우로, 이때 버튼 상자는 수평으로 중앙 정렬됩니다.
Access 함수:
| bool | centerButtons() const |
| void | setCenterButtons(bool center) |
QMessageBox도 참조하십시오 .
orientation : Qt::Orientation
이 속성은 버튼 상자의 방향을 지정합니다.
기본적으로 배향은 가로 방향입니다(즉, 버튼이 나란히 배치됨). 가능한 배향으로는 Qt::Horizontal 및 Qt::Vertical 가 있습니다.
액세스 함수:
| Qt::Orientation | orientation() const |
| void | setOrientation(Qt::Orientation orientation) |
standardButtons : StandardButtons
버튼 상자에 포함된 표준 버튼 모음
이 속성은 버튼 상자에서 사용할 표준 버튼을 제어합니다.
Access 함수:
| QDialogButtonBox::StandardButtons | standardButtons() const |
| void | setStandardButtons(QDialogButtonBox::StandardButtons buttons) |
addButton()도 참조하십시오 .
멤버 함수 설명서
QDialogButtonBox::QDialogButtonBox(QWidget *parent = nullptr)
지정된 ` parent`를 사용하여 빈 가로형 버튼 상자를 생성합니다.
orientation 및 addButton()도 참조하십시오 .
[explicit] QDialogButtonBox::QDialogButtonBox(QDialogButtonBox::StandardButtons buttons, QWidget *parent = nullptr)
지정된 ` parent`를 사용하여 ` buttons`에 명시된 표준 버튼이 포함된 가로형 버튼 상자를 생성합니다.
orientation 및 addButton()도 참조하십시오 .
QDialogButtonBox::QDialogButtonBox(Qt::Orientation orientation, QWidget *parent = nullptr)
지정된 ` orientation ` 및 ` parent`을 사용하여 빈 버튼 상자를 생성합니다.
orientation 및 addButton()도 참조하십시오 .
QDialogButtonBox::QDialogButtonBox(QDialogButtonBox::StandardButtons buttons, Qt::Orientation orientation, QWidget *parent = nullptr)
지정된 ` orientation ` 및 ` parent`을 사용하여, ` buttons`에 명시된 표준 버튼들을 포함하는 버튼 상자를 생성합니다.
orientation 및 addButton()도 참조하십시오 .
[virtual noexcept] QDialogButtonBox::~QDialogButtonBox()
버튼 상자를 파괴합니다.
[signal] void QDialogButtonBox::accepted()
이 신호는 버튼 상자 내부의 버튼이 클릭되었을 때, 해당 버튼이 AcceptRole 또는 YesRole 로 정의된 경우에만 발생합니다.
rejected(), clicked(), helpRequested()도 참조하십시오 .
QPushButton *QDialogButtonBox::addButton(QDialogButtonBox::StandardButton button)
가능한 경우 버튼 박스에 표준 button 를 추가하고, 푸시 버튼을 반환합니다. button 가 유효하지 않은 경우, 버튼 박스에 추가되지 않으며 0이 반환됩니다.
removeButton() 및 clear()도 참조하십시오 .
void QDialogButtonBox::addButton(QAbstractButton *button, QDialogButtonBox::ButtonRole role)
지정된 역할( button )을 지정된 버튼 상자( role)에 추가합니다. 역할이 유효하지 않은 경우, 버튼은 추가되지 않습니다.
버튼이 이미 추가된 경우, 해당 버튼은 제거된 후 새로운 역할로 다시 추가됩니다.
참고: 버튼상자가 버튼의 소유권을 갖습니다.
removeButton() 및 clear()도 참조하십시오 .
QPushButton *QDialogButtonBox::addButton(const QString &text, QDialogButtonBox::ButtonRole role)
지정된 ` text`을 사용하여 푸시 버튼을 생성하고, 이를 지정된 ` role`의 버튼 상자에 추가한 다음, 해당 푸시 버튼을 반환합니다. ` role `이 유효하지 않은 경우, 버튼이 생성되지 않고 0이 반환됩니다.
removeButton() 및 clear()도 참조하십시오 .
QPushButton *QDialogButtonBox::button(QDialogButtonBox::StandardButton which) const
표준 버튼 which 에 해당하는 QPushButton 를 반환하거나, 해당 표준 버튼이 이 버튼 상자에 존재하지 않을 경우 nullptr 를 반환합니다.
standardButton(), standardButtons(), buttons()도 참조하십시오 .
QDialogButtonBox::ButtonRole QDialogButtonBox::buttonRole(QAbstractButton *button) const
지정된 button 의 버튼 역할을 반환합니다. 이 함수는 button 이 nullptr 이거나 버튼 박스에 추가되지 않은 경우 InvalidRole 을 반환합니다.
buttons() 및 addButton()도 참조하십시오 .
QList<QAbstractButton *> QDialogButtonBox::buttons() const
버튼 상자에 추가된 모든 버튼의 목록을 반환합니다.
buttonRole(), addButton(), removeButton()도 참조하십시오 .
[override virtual protected] void QDialogButtonBox::changeEvent(QEvent *event)
QWidget::changeEvent(QEvent *event)를 재구현합니다.
void QDialogButtonBox::clear()
버튼 상자를 지워, 그 안에 있는 모든 버튼을 삭제합니다.
removeButton() 및 addButton()도 참조하십시오 .
[signal] void QDialogButtonBox::clicked(QAbstractButton *button)
이 신호는 버튼 상자 내부의 버튼이 클릭될 때 발생합니다. 누른 구체적인 버튼은 ` button`로 지정됩니다.
accepted(), rejected(), helpRequested()도 참조하십시오 .
[override virtual protected] bool QDialogButtonBox::event(QEvent *event)
QWidget::event(QEvent *event)를 재구현합니다.
[signal] void QDialogButtonBox::helpRequested()
이 신호는 버튼 상자 내부의 버튼이 클릭되었을 때, 해당 버튼이 ` HelpRole`로 정의된 경우에만 발생합니다.
accepted(), rejected(), clicked()도 참조하십시오 .
[signal] void QDialogButtonBox::rejected()
이 신호는 버튼 상자 내부의 버튼이 클릭되었을 때, 해당 버튼이 RejectRole 또는 NoRole 로 정의된 경우에만 발생합니다.
accepted(), helpRequested() 및 clicked()도 참조하십시오 .
void QDialogButtonBox::removeButton(QAbstractButton *button)
button 를 삭제하지 않고 버튼 상자에서 제거하며, 해당 요소의 부모를 null로 설정합니다.
clear(), buttons(), addButton()도 참조하십시오 .
QDialogButtonBox::StandardButton QDialogButtonBox::standardButton(QAbstractButton *button) const
주어진 button 에 해당하는 표준 버튼 열거형 값을 반환하거나, 주어진 button 가 표준 버튼이 아닌 경우 NoButton 를 반환합니다.
button(), buttons(), standardButtons()도 참조하십시오 .
[static, since 6.12] QKeySequence QDialogButtonBox::standardButtonShortcut(QDialogButtonBox::StandardButton button)
표준 button 에 대한 키보드 단축키를 반환합니다. 단축키는 플랫폼에 따라 다릅니다. button 에 할당된 단축키가 없거나 인식 가능한 표준 버튼이 아닌 경우, 빈 QKeySequence 를 반환합니다.
이 함수는 Qt 6.12에서 도입되었습니다.
standardButtonText() 및 StandardButton도 참조하십시오 .
[static, since 6.12] QString QDialogButtonBox::standardButtonText(QDialogButtonBox::StandardButton button)
표준 ‘ button ’ 버튼의 레이블에 표시되는 텍스트를 반환합니다. 이 텍스트는 플랫폼 및 로케일에 따라 달라집니다.
button 가 인식 가능한 표준 버튼이 아닌 경우 빈 문자열을 반환합니다.
이 함수는 Qt 6.12에서 도입되었습니다.
standardButtonShortcut() 및 StandardButton도 참조하십시오 .
© 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.
비모달 수평 모드 스크린샷
비모달 수직형 스크린샷