QPushButton Class
QPushButton 위젯은 명령 버튼을 제공합니다. 더 보기...
| 헤더: | #include <QPushButton> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Widgets) target_link_libraries(mytarget PRIVATE Qt6::Widgets) |
| qmake: | QT += widgets |
| 상속: | QAbstractButton |
| 상속받는 클래스: |
속성
- autoDefault : bool
- default : bool
- flat : bool
공개 함수
| QPushButton(QWidget *parent = nullptr) | |
| QPushButton(const QString &text, QWidget *parent = nullptr) | |
| QPushButton(const QIcon &icon, const QString &text, QWidget *parent = nullptr) | |
| virtual | ~QPushButton() |
| bool | autoDefault() const |
| bool | isDefault() const |
| bool | isFlat() const |
| QMenu * | menu() const |
| void | setAutoDefault(bool) |
| void | setDefault(bool) |
| void | setFlat(bool) |
| void | setMenu(QMenu *menu) |
재구현된 공용 함수
| virtual QSize | minimumSizeHint() const override |
| virtual QSize | sizeHint() const override |
공개 슬롯
| void | showMenu() |
보호된 함수
| virtual void | initStyleOption(QStyleOptionButton *option) const |
재구현된 보호된 함수
| virtual bool | event(QEvent *e) override |
| virtual void | focusInEvent(QFocusEvent *e) override |
| virtual void | focusOutEvent(QFocusEvent *e) override |
| virtual bool | hitButton(const QPoint &pos) const override |
| virtual void | keyPressEvent(QKeyEvent *e) override |
| virtual void | mouseMoveEvent(QMouseEvent *e) override |
| virtual void | paintEvent(QPaintEvent *) override |
상세 설명
푸시 버튼 또는 명령 버튼은 아마도 모든 그래픽 사용자 인터페이스에서 가장 흔히 사용되는 위젯일 것입니다. 버튼을 누르거나(클릭) 하면 컴퓨터가 특정 동작을 수행하거나 질문에 응답하도록 지시합니다. 대표적인 버튼으로는 ‘확인’, ‘적용’, ‘취소’, ‘닫기’, ‘예’, ‘아니오’ 및 ‘도움말’이 있습니다.
명령 버튼은 직사각형 모양이며, 일반적으로 해당 동작을 설명하는 텍스트 레이블이 표시됩니다. 텍스트 내에서 원하는 문자 앞에 앰퍼샌드(&)를 붙이면 단축키를 지정할 수 있습니다. 예를 들어:
QPushButton *button = new QPushButton("&Download", this);이 예에서 단축키는 Alt+D입니다. 자세한 내용은 QShortcut 문서를 참조하십시오(실제 앰퍼샌드를 표시하려면 '&&'를 사용하십시오).
푸시 버튼은 텍스트 레이블을 표시하며, 선택적으로 작은 아이콘을 표시할 수도 있습니다. 이러한 설정은 생성자를 사용하여 지정할 수 있으며, 나중에 setText() 및 setIcon()를 사용하여 변경할 수 있습니다. 버튼이 비활성화된 경우, 텍스트와 아이콘의 모양은 GUI 스타일에 따라 조정되어 버튼이 “비활성화된” 것처럼 보이게 됩니다.
푸시 버튼은 마우스, 스페이스바 또는 키보드 단축키로 활성화될 때 clicked() 신호를 발생시킵니다. 이 신호에 연결하여 버튼의 동작을 수행할 수 있습니다. 또한 푸시 버튼은 pressed() 및 released()과 같이 덜 자주 사용되는 신호들도 제공합니다.
connect(dispenseButton, &QPushButton::clicked, this, &IceCreamMaker::dispense);대화 상자의 명령 버튼은 기본적으로 자동 기본값 버튼으로, 키보드 입력 포커스를 받으면 자동으로 기본 푸시 버튼이 됩니다. 기본 버튼은 사용자가 대화 상자에서 Enter 또는 Return 키를 누를 때 활성화되는 푸시 버튼입니다. 이 설정은 setAutoDefault()를 사용하여 변경할 수 있습니다. 자동 기본 버튼은 기본 버튼 표시기를 그리는 데 필요한 약간의 추가 공간을 확보한다는 점에 유의하십시오. 버튼 주위에 이 공간을 원하지 않는 경우, setAutoDefault(false)를 호출하십시오.
버튼 위젯은 그 중요성만큼이나 지난 10년 동안 매우 다양한 형태로 발전해 왔습니다. 현재 Microsoft 스타일 가이드에는 Windows 푸시 버튼의 약 10가지 상태가 나와 있으며, 문구를 미루어 볼 때 기능의 모든 조합을 고려하면 수십 가지가 더 존재할 것으로 보입니다.
가장 중요한 모드나 상태는 다음과 같습니다.
- 사용 가능 여부(회색으로 표시됨, 비활성화됨).
- 표준 푸시 버튼, 토글 푸시 버튼 또는 메뉴 버튼.
- 켜기 또는 끄기(토글 푸시 버튼에만 해당).
- 기본 또는 일반. 대화 상자의 기본 버튼은 일반적으로 Enter 또는 Return 키를 사용하여 “클릭”할 수 있습니다.
- 자동 반복 여부.
- 누른 상태인지 여부.
일반적으로, 사용자가 버튼을 클릭했을 때 애플리케이션이나 대화 상자 창에서 동작이 수행되는 경우(예: 적용, 취소, 닫기, 도움말) 와 위젯이 텍스트 레이블이 있는 넓은 직사각형 모양이어야 하는 경우에는 푸시 버튼을 사용합니다. 작고, 대개 정사각형인 버튼으로, 특정 동작을 수행하는 대신 창의 상태를 변경하는 버튼(예: QFileDialog 의 오른쪽 상단 모서리에 있는 버튼)은 명령 버튼이 아니라 도구 버튼입니다. Qt는 이러한 버튼을 위해 특수한 클래스(QToolButton)를 제공합니다.
토글 동작( setCheckable() 참조)이 필요하거나, 스크롤 바의 화살표처럼 눌려진 상태에서 활성화 신호를 자동으로 반복하는 버튼( setAutoRepeat() 참조)이 필요한 경우, 명령 버튼은 적합하지 않을 수 있습니다. 확실하지 않은 경우에는 도구 버튼을 사용하십시오.
참고: macOS에서 푸시 버튼의 너비가 50보다 작아지거나 높이가 30보다 작아지면, 버튼의 모서리가 둥근 모양에서 사각형 모양으로 바뀝니다. 이 동작을 방지하려면 setMinimumSize() 함수를 사용하십시오.
명령 버튼의 변형으로 메뉴 버튼이 있습니다. 이 버튼은 클릭 시 옵션 메뉴가 표시되므로 하나의 명령뿐만 아니라 여러 명령을 제공합니다. setMenu() 메서드를 사용하여 푸시 버튼에 팝업 메뉴를 연결하십시오.
다른 종류의 버튼으로는 옵션 버튼( QRadioButton 참조)과 체크박스( QCheckBox 참조)가 있습니다.
Qt에서 QAbstractButton 기본 클래스는 대부분의 모드와 기타 API를 제공하며, QPushButton은 GUI 로직을 제공합니다. API에 대한 자세한 내용은 QAbstractButton 를 참조하십시오.
QToolButton, QRadioButton 및 QCheckBox도 참조하십시오 .
속성 문서
autoDefault : bool
이 속성은 푸시 버튼이 자동 기본값 버튼인지 여부를 나타냅니다.
이 속성이 true로 설정되면 해당 푸시 버튼은 자동 기본값 버튼이 됩니다.
일부 GUI 스타일에서는 기본 버튼 주위에 최대 3픽셀 이상의 추가 테두리가 그려집니다. Qt GUI는 자동 기본 버튼 주위의 이 공간을 자동으로 비워 둡니다. 즉, 자동 기본 버튼의 크기 힌트가 약간 더 클 수 있습니다.
QDialog 를 부모로 갖는 버튼의 경우 이 속성의 기본값은 true이며, 그렇지 않은 경우 기본값은 false입니다.
default 와 auto-default가 어떻게 상호 작용하는지에 대한 자세한 내용은 default 속성을 참조하십시오.
액세스 함수:
| bool | autoDefault() const |
| void | setAutoDefault(bool) |
default : bool
이 속성은 푸시 버튼이 기본 버튼인지 여부를 나타냅니다.
기본 버튼과 자동 기본 버튼은 사용자가 대화 상자에서 Enter 키를 누를 때 어떤 동작이 발생할지를 결정합니다.
이 속성이 true로 설정된 버튼(즉, 대화 상자의 기본 버튼)은 사용자가 Enter 키를 누르면 자동으로 선택되지만, 한 가지 예외가 있습니다. 바로 ‘ autoDefault ’ 버튼이 현재 포커스를 가지고 있는 경우, ‘ autoDefault ’ 버튼이 선택됩니다. 다이얼로그에 ' autoDefault ' 버튼이 있지만 기본 버튼이 없는 경우, Enter 키를 누르면 현재 포커스가 있는 ' autoDefault ' 버튼이 눌리거나, 포커스가 있는 버튼이 없는 경우에는 포커스 체인에서 다음 순서의 ' autoDefault ' 버튼이 눌립니다.
대화 상자에서는 한 번에 하나의 푸시 버튼만 기본 버튼으로 지정될 수 있습니다. 이 버튼은 (GUI 스타일에 따라) 추가적인 테두리와 함께 표시됩니다.
기본 버튼 동작은 대화 상자에서만 제공됩니다. 버튼에 포커스가 있을 때 스페이스바를 누르면 언제든지 키보드로 버튼을 클릭할 수 있습니다.
대화 상자가 표시된 상태에서 현재 기본 버튼의 default 속성이 false로 설정되어 있으면, 대화 상자 내의 푸시 버튼이 다음에 포커스를 받을 때 새로운 기본 버튼이 자동으로 지정됩니다.
이 속성의 기본값은 false입니다.
액세스 함수:
| bool | isDefault() const |
| void | setDefault(bool) |
flat : bool
이 속성은 버튼 테두리가 돌출되어 있는지 여부를 나타냅니다.
이 속성의 기본값은 false입니다. 이 속성이 설정된 경우, 버튼이 눌려진 상태가 아닌 한 대부분의 스타일은 버튼 배경을 렌더링하지 않습니다. ` setAutoFillBackground()`를 사용하면 ` QPalette::Button ` 브러시를 사용하여 배경이 채워지도록 할 수 있습니다.
액세스 함수:
| bool | isFlat() const |
| void | setFlat(bool) |
멤버 함수 문서
[explicit] QPushButton::QPushButton(QWidget *parent = nullptr)
텍스트가 없고 ` parent` 속성이 지정된 푸시 버튼을 생성합니다.
[explicit] QPushButton::QPushButton(const QString &text, QWidget *parent = nullptr)
parent 를 부모 요소로 하고, “ text ”라는 텍스트가 표시되는 푸시 버튼을 생성합니다.
QPushButton::QPushButton(const QIcon &icon, const QString &text, QWidget *parent = nullptr)
icon, text 및 parent 을 사용하여 푸시 버튼을 생성합니다.
(C++에서 제공하는 암시적 형 변환 덕분에) QPixmap 객체를 아이콘으로 전달할 수도 있다는 점에 유의하십시오.
[virtual noexcept] QPushButton::~QPushButton()
푸시 버튼을 파손합니다.
[override virtual protected] bool QPushButton::event(QEvent *e)
QAbstractButton::event(QEvent *e)를 재구현합니다.
[override virtual protected] void QPushButton::focusInEvent(QFocusEvent *e)
QAbstractButton::focusInEvent(QFocusEvent *e)를 재구현합니다.
[override virtual protected] void QPushButton::focusOutEvent(QFocusEvent *e)
QAbstractButton::focusOutEvent(QFocusEvent *e)를 재구현합니다.
[override virtual protected] bool QPushButton::hitButton(const QPoint &pos) const
QAbstractButton::hitButton(const QPoint &pos) const를 재구현합니다.
[virtual protected] void QPushButton::initStyleOption(QStyleOptionButton *option) const
option 를 QPushButton 에 있는 값들로 초기화합니다. 이 메서드는 하위 클래스에서 QStyleOptionButton 가 필요하지만, 모든 정보를 직접 입력하고 싶지 않을 때 유용합니다.
QStyleOption::initFrom()도 참조하십시오 .
[override virtual protected] void QPushButton::keyPressEvent(QKeyEvent *e)
QAbstractButton::keyPressEvent(QKeyEvent *e)를 재구현합니다.
QMenu *QPushButton::menu() const
버튼에 연결된 팝업 메뉴를 반환하거나, 팝업 메뉴가 설정되어 있지 않은 경우 ` nullptr `를 반환합니다.
setMenu()도 참조하십시오 .
[override virtual] QSize QPushButton::minimumSizeHint() const
QWidget::minimumSizeHint 속성에 대한 액세스 함수를 다시 구현합니다.
[override virtual protected] void QPushButton::mouseMoveEvent(QMouseEvent *e)
QAbstractButton::mouseMoveEvent(QMouseEvent *e)를 재구현합니다.
[override virtual protected] void QPushButton::paintEvent(QPaintEvent *)
QAbstractButton::paintEvent(QPaintEvent *e)를 재구현합니다.
void QPushButton::setMenu(QMenu *menu)
menu 팝업 메뉴를 이 푸시 버튼에 연결합니다. 이렇게 하면 버튼이 메뉴 버튼으로 변환되며, 일부 스타일에서는 버튼 텍스트 오른쪽에 작은 삼각형이 표시됩니다.
메뉴의 소유권은 푸시 버튼으로 이전되지 않습니다.
Fusion 위젯 스타일에서 표시되는 팝업 메뉴가 있는 푸시 버튼.
menu()도 참조하십시오 .
[slot] void QPushButton::showMenu()
관련된 팝업 메뉴를 표시합니다. 해당 메뉴가 없는 경우, 이 함수는 아무 작업도 수행하지 않습니다. 이 함수는 사용자가 팝업 메뉴를 닫을 때까지 반환되지 않습니다.
[override virtual] QSize QPushButton::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.
