이 페이지에서

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

속성

공개 함수

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 가로 방향가로로 배치된 버튼 상자 GnomeLayout
KdeLayout 수평 레이아웃을 사용하는 여러 개의 버튼 KdeLayout 가로버튼 상자가 가로 방향으로 배치된 경우 KdeLayout
MacLayout 수평 레이아웃을 사용하는 여러 개의 버튼 MacLayout 가로버튼 박스가 가로로 배치됨 MacLayout
WinLayout 수평 레이아웃을 사용하는 여러 개의 버튼 WinLayout 가로버튼 박스가 가로로 배치됨 WinLayout

버튼 상자가 세로 방향인 경우 버튼은 다음과 같이 배열됩니다:

또한, ` ActionRole ` 또는 ` HelpRole ` 속성이 적용된 버튼만 포함된 버튼 상자는 모달이 아닌 것으로 간주되며, macOS에서는 다른 모양으로 표시됩니다:

모달이 아닌 가로형 MacLayoutmacOS에서 가로형 무모드 스타일을 사용하는 여러 개의 버튼 비모달 수평 모드 스크린샷 MacLayout
모달이 아닌 수직 MacLayoutmacOS에서 가로 방향의 모달리스 스타일을 적용한 여러 개의 버튼 비모달 수직형 스크린샷 MacLayout

버튼 박스 내의 버튼이 클릭되면, 실제로 눌린 버튼에 대해 clicked() 신호가 발생합니다. 편의상, 버튼에 AcceptRole, RejectRole 또는 HelpRole 가 설정되어 있는 경우, 각각 accepted(), rejected() 또는 helpRequested() 신호가 발생합니다.

특정 버튼을 기본값으로 설정하려면 해당 버튼에 대해 직접 ` QPushButton::setDefault()`를 호출해야 합니다. 그러나 기본 버튼이 설정되어 있지 않은 경우, ` QPushButton::autoDefault ` 속성을 사용할 때 플랫폼 간에 기본 버튼이 일관되게 유지되도록 하기 위해, `QDialogButtonBox`가 표시될 때 `accept` 역할을 가진 첫 번째 푸시 버튼이 기본 버튼으로 지정됩니다.

QMessageBox, QPushButton 및 QDialog도 참조하십시오 .

멤버 유형 문서

enum QDialogButtonBox::ButtonLayout

이 열거형은 버튼 상자에 포함된 버튼을 배치할 때 사용할 레이아웃 정책을 설명합니다.

상수값설명
QDialogButtonBox::WinLayout0Windows 애플리케이션에 적합한 정책을 사용합니다.
QDialogButtonBox::MacLayout1macOS 애플리케이션에 적합한 정책을 사용합니다.
QDialogButtonBox::KdeLayout2KDE의 애플리케이션에 적합한 정책을 사용합니다.
QDialogButtonBox::GnomeLayout3GNOME의 애플리케이션에 적합한 정책을 사용합니다.
QDialogButtonBox::AndroidLayout4Android 애플리케이션에 적합한 정책을 사용합니다. 이 열거형 값은 Qt 5.10에서 추가되었습니다.

버튼 레이아웃은 ` current style`에 의해 지정됩니다. 그러나 X11 플랫폼에서는 데스크톱 환경의 영향을 받을 수 있습니다.

enum QDialogButtonBox::ButtonRole

이 열거형은 버튼 상자 내의 버튼을 설명하는 데 사용할 수 있는 역할을 정의합니다. 이러한 역할의 조합은 버튼 동작의 다양한 측면을 설명하는 데 사용되는 플래그 역할을 합니다.

상수값설명
QDialogButtonBox::InvalidRole-1버튼이 유효하지 않습니다.
QDialogButtonBox::AcceptRole0버튼을 클릭하면 대화 상자가 수락됩니다(예: 확인).
QDialogButtonBox::RejectRole1이 버튼을 클릭하면 대화 상자가 거부됩니다(예: 취소).
QDialogButtonBox::DestructiveRole2이 버튼을 클릭하면 되돌릴 수 없는 변경(예: 변경 내용 취소)이 발생하고 대화 상자가 닫힙니다.
QDialogButtonBox::ActionRole3이 버튼을 클릭하면 대화 상자 내의 요소가 변경됩니다.
QDialogButtonBox::HelpRole4이 버튼을 클릭하면 도움말을 요청할 수 있습니다.
QDialogButtonBox::YesRole5이 버튼은 “예”와 유사한 버튼입니다.
QDialogButtonBox::NoRole6이 버튼은 "아니요"와 유사한 버튼입니다.
QDialogButtonBox::ApplyRole8이 버튼을 누르면 현재 변경 사항이 적용됩니다.
QDialogButtonBox::ResetRole7이 버튼을 누르면 대화 상자의 필드가 기본값으로 재설정됩니다.

StandardButton도 참조하십시오 .

enum QDialogButtonBox::StandardButton
flags QDialogButtonBox::StandardButtons

이 열거형들은 표준 버튼에 대한 플래그를 설명합니다. 각 버튼에는 정의된 ButtonRole 가 있습니다.

상수값설명
QDialogButtonBox::Ok0x00000400AcceptRole 로 정의된 "OK" 버튼.
QDialogButtonBox::Open0x00002000AcceptRole 로 정의된 "열기" 버튼입니다.
QDialogButtonBox::Save0x00000800AcceptRole 로 정의된 "Save" 버튼.
QDialogButtonBox::Cancel0x00400000RejectRole 로 정의된 “Cancel” 버튼.
QDialogButtonBox::Close0x00200000RejectRole 로 정의된 "닫기" 버튼.
QDialogButtonBox::Discard0x00800000플랫폼에 따라 "취소" 또는 "저장하지 않음" 버튼으로, DestructiveRole 로 정의됩니다.
QDialogButtonBox::Apply0x02000000ApplyRole 로 정의된 "적용" 버튼.
QDialogButtonBox::Reset0x04000000ResetRole 로 정의된 "Reset" 버튼.
QDialogButtonBox::RestoreDefaults0x08000000ResetRole 로 정의된 "기본값 복원" 버튼.
QDialogButtonBox::Help0x01000000HelpRole 으로 정의된 "도움말" 버튼.
QDialogButtonBox::SaveAll0x00001000AcceptRole 로 정의된 "모두 저장" 버튼.
QDialogButtonBox::Yes0x00004000YesRole 로 정의된 "예" 버튼.
QDialogButtonBox::YesToAll0x00008000YesRole 로 정의된 "모두 예" 버튼.
QDialogButtonBox::No0x00010000NoRole 로 정의된 "아니요" 버튼.
QDialogButtonBox::NoToAll0x00020000NoRole 로 정의된 "모두 아니오" 버튼.
QDialogButtonBox::Abort0x00040000RejectRole 로 정의된 "취소" 버튼.
QDialogButtonBox::Retry0x00080000AcceptRole 로 정의된 "재시도" 버튼.
QDialogButtonBox::Ignore0x00100000AcceptRole 로 정의된 "Ignore" 버튼.
QDialogButtonBox::NoButton0x00000000유효하지 않은 버튼입니다.

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.