이 페이지에서

QToolButton Class

QToolButton 클래스는 명령어나 옵션에 대한 빠른 액세스 버튼을 제공하며, 주로 QToolBar 내에서 사용됩니다. 더 보기...

헤더: #include <QToolButton>
CMake: find_package(Qt6 REQUIRED COMPONENTS Widgets)
target_link_libraries(mytarget PRIVATE Qt6::Widgets)
qmake: QT += widgets
상속: QAbstractButton

공개 타입

enum ToolButtonPopupMode { DelayedPopup, MenuButtonPopup, InstantPopup }

속성

공개 함수

QToolButton(QWidget *parent = nullptr)
virtual ~QToolButton()
Qt::ArrowType arrowType() const
bool autoRaise() const
QAction *defaultAction() const
QMenu *menu() const
QToolButton::ToolButtonPopupMode popupMode() const
void setArrowType(Qt::ArrowType type)
void setAutoRaise(bool enable)
void setMenu(QMenu *menu)
void setPopupMode(QToolButton::ToolButtonPopupMode mode)
Qt::ToolButtonStyle toolButtonStyle() const

재구현된 공용 함수

virtual QSize minimumSizeHint() const override
virtual QSize sizeHint() const override

공개 슬롯

void setDefaultAction(QAction *action)
void setToolButtonStyle(Qt::ToolButtonStyle style)
void showMenu()

신호

void triggered(QAction *action)

보호된 함수

virtual void initStyleOption(QStyleOptionToolButton *option) const

재구현된 보호 함수

virtual void actionEvent(QActionEvent *event) override
virtual void changeEvent(QEvent *e) override
virtual void checkStateSet() override
virtual void enterEvent(QEnterEvent *e) override
virtual bool event(QEvent *event) override
virtual bool hitButton(const QPoint &pos) const override
virtual void leaveEvent(QEvent *e) override
virtual void mousePressEvent(QMouseEvent *e) override
virtual void mouseReleaseEvent(QMouseEvent *e) override
virtual void nextCheckState() override
virtual void paintEvent(QPaintEvent *event) override
virtual void timerEvent(QTimerEvent *e) override

상세 설명

도구 버튼은 특정 명령이나 옵션에 빠르게 접근할 수 있게 해주는 특수한 버튼입니다. 일반 명령 버튼과 달리, 도구 버튼은 대개 텍스트 레이블을 표시하지 않고 대신 아이콘을 표시합니다.

도구 버튼은 일반적으로 ` QToolBar::addAction()`를 사용하여 새로운 ` QAction ` 인스턴스를 생성하거나, ` QToolBar::addAction()`를 사용하여 기존 액션을 툴바에 추가할 때 생성됩니다. 또한 다른 위젯과 동일한 방식으로 도구 버튼을 생성하고, 레이아웃 내에서 다른 위젯들과 나란히 배치할 수도 있습니다.

도구 버튼의 대표적인 용도 중 하나는 도구를 선택하는 것입니다. 예를 들어, 드로잉 프로그램의 “펜” 도구가 있습니다. 이는 QToolButton을 토글 버튼으로 사용하여 구현할 수 있습니다( setCheckable() 참조).

QToolButton은 자동 돌출(auto-raise)을 지원합니다. 자동 돌출 모드에서는 마우스가 버튼을 가리킬 때만 3D 프레임이 그려집니다. 이 기능은 QToolBar 내부에서 버튼을 사용할 때 자동으로 활성화됩니다. setAutoRaise()를 사용하여 이 설정을 변경할 수 있습니다.

도구 버튼의 아이콘은 QIcon 로 설정됩니다. 이를 통해 비활성화 상태와 활성 상태에 서로 다른 픽스맵을 지정할 수 있습니다. 비활성화 픽스맵은 버튼의 기능을 사용할 수 없을 때 사용됩니다. 활성 픽스맵은 마우스 포인터가 버튼 위에 머물러 있어 버튼이 자동으로 돌출되었을 때 표시됩니다.

버튼의 모양과 크기는 ` setToolButtonStyle()` 및 ` setIconSize()`을 사용하여 조정할 수 있습니다. ` QMainWindow` 내의 ` QToolBar `에서 사용될 경우, 버튼은 ` QMainWindow`의 설정에 따라 자동으로 조정됩니다(` QMainWindow::setToolButtonStyle()` 및 ` QMainWindow::setIconSize()` 참조). 아이콘 대신, 도구 버튼은 ` arrowType`로 지정된 화살표 기호를 표시할 수도 있습니다.

도구 버튼은 팝업 메뉴를 통해 추가 선택 항목을 제공할 수 있습니다. 팝업 메뉴는 setMenu()를 사용하여 설정할 수 있습니다. setPopupMode()를 사용하면 메뉴가 설정된 도구 버튼에 사용할 수 있는 다양한 모드를 구성할 수 있습니다. 기본 모드는 DelayedPopupMode이며, 이는 웹 브라우저의 “뒤로” 버튼에서 때때로 사용됩니다. 버튼을 잠시 길게 누르면 이동 가능한 페이지 목록이 표시된 메뉴가 팝업으로 나타납니다. 타임아웃은 스타일에 따라 다르며, QStyle::SH_ToolButton_PopupDelay 를 참조하십시오.

도구 버튼이 있는 Qt Assistant의 도구 모음

Qt Assistant의 툴바에는 메인 창의 다른 부분에서 사용되는 동작과 연결된 도구 버튼들이 포함되어 있습니다.

QPushButton, QToolBar, QMainWindow 및 QAction도 참조하십시오 .

멤버 유형 문서

enum QToolButton::ToolButtonPopupMode

메뉴 세트가 설정되어 있거나 작업 목록이 포함된 도구 버튼에 대해 메뉴가 어떻게 팝업되어야 하는지 설명합니다.

상수값설명
QToolButton::DelayedPopup0도구 버튼을 일정 시간 동안 길게 누르면(타임아웃은 스타일에 따라 다르며, QStyle::SH_ToolButton_PopupDelay 참조), 메뉴가 표시됩니다. 전형적인 적용 예로는 일부 웹 브라우저의 도구 모음에 있는 “뒤로” 버튼이 있습니다. 사용자가 이 버튼을 클릭하면 브라우저는 단순히 이전 페이지로 돌아갑니다. 사용자가 버튼을 잠시 길게 누르면, 도구 버튼에 현재 기록 목록이 포함된 메뉴가 표시됩니다.
QToolButton::MenuButtonPopup1이 모드에서는 도구 버튼에 메뉴가 있음을 나타내는 특별한 화살표가 표시됩니다. 버튼의 화살표 부분을 누르면 메뉴가 표시됩니다.
QToolButton::InstantPopup2도구 버튼을 누르면 지연 없이 메뉴가 표시됩니다. 이 모드에서는 버튼 자체의 동작이 실행되지 않습니다.

속성 설명

arrowType : Qt::ArrowType

이 속성은 버튼에 일반 아이콘 대신 화살표가 표시되는지 여부를 결정합니다.

이 속성은 ' QToolButton'의 아이콘으로 화살표를 표시합니다.

기본적으로 이 속성은 ` Qt::NoArrow`로 설정되어 있습니다.

액세스 함수:

Qt::ArrowType arrowType() const
void setArrowType(Qt::ArrowType type)

autoRaise : bool

이 속성은 자동 증가 기능이 활성화되었는지 여부와 관계없이 적용됩니다.

기본값은 비활성화(즉, false)입니다.

현재 macOS에서 QMacStyle을 사용할 경우 이 속성은 무시됩니다.

액세스 함수:

bool autoRaise() const
void setAutoRaise(bool enable)

popupMode : ToolButtonPopupMode

도구 버튼과 함께 팝업 메뉴를 사용하는 방법을 설명합니다

기본적으로 이 속성은 ` DelayedPopup`로 설정되어 있습니다.

액세스 함수:

QToolButton::ToolButtonPopupMode popupMode() const
void setPopupMode(QToolButton::ToolButtonPopupMode mode)

toolButtonStyle : Qt::ToolButtonStyle

이 속성은 도구 버튼에 아이콘만 표시할지, 텍스트만 표시할지, 아니면 아이콘 옆이나 아래에 텍스트를 함께 표시할지를 결정합니다.

기본값은 ' Qt::ToolButtonIconOnly'입니다.

도구 버튼의 스타일이 시스템 설정을 따르도록 하려면 이 속성을 ` Qt::ToolButtonFollowStyle`로 설정하십시오. Unix에서는 데스크톱 환경의 사용자 설정이 사용됩니다. 다른 플랫폼에서 ` Qt::ToolButtonFollowStyle `는 아이콘만 표시함을 의미합니다.

QToolButton 이 슬롯을 해당 슬롯이 속한 ` QMainWindow `의 관련 신호에 자동으로 연결합니다.

액세스 함수:

Qt::ToolButtonStyle toolButtonStyle() const
void setToolButtonStyle(Qt::ToolButtonStyle style)

멤버 함수 문서

[explicit] QToolButton::QToolButton(QWidget *parent = nullptr)

parent 를 부모로 하는 빈 도구 버튼을 생성합니다.

[virtual noexcept] QToolButton::~QToolButton()

객체를 삭제하고 할당된 리소스를 모두 해제합니다.

[override virtual protected] void QToolButton::actionEvent(QActionEvent *event)

QWidget::actionEvent(QActionEvent *event)를 재구현합니다.

[override virtual protected] void QToolButton::changeEvent(QEvent *e)

QAbstractButton::changeEvent(QEvent *e)를 재구현합니다.

[override virtual protected] void QToolButton::checkStateSet()

QAbstractButton::checkStateSet()를 재구현합니다.

QAction *QToolButton::defaultAction() const

기본 동작을 반환합니다.

setDefaultAction()도 참조하십시오 .

[override virtual protected] void QToolButton::enterEvent(QEnterEvent *e)

QWidget::enterEvent(QEnterEvent *event)를 재구현합니다.

[override virtual protected] bool QToolButton::event(QEvent *event)

QAbstractButton::event(QEvent *e)를 재구현합니다.

[override virtual protected] bool QToolButton::hitButton(const QPoint &pos) const

QAbstractButton::hitButton(const QPoint &pos) const를 재구현합니다.

[virtual protected] void QToolButton::initStyleOption(QStyleOptionToolButton *option) const

option 를 QToolButton 에 있는 값들로 초기화합니다. 이 메서드는 하위 클래스에서 QStyleOptionToolButton 가 필요하지만, 모든 정보를 직접 입력하고 싶지 않을 때 유용합니다.

QStyleOption::initFrom()도 참조하십시오 .

[override virtual protected] void QToolButton::leaveEvent(QEvent *e)

QWidget::leaveEvent(QEvent *event)를 재구현합니다.

연관된 메뉴를 반환하거나, 정의된 메뉴가 없는 경우 nullptr 를 반환합니다.

setMenu()도 참조하십시오 .

[override virtual] QSize QToolButton::minimumSizeHint() const

QWidget::minimumSizeHint 속성에 대한 액세스 함수를 재구현합니다.

[override virtual protected] void QToolButton::mousePressEvent(QMouseEvent *e)

QAbstractButton::mousePressEvent(QMouseEvent *e)를 재구현합니다.

[override virtual protected] void QToolButton::mouseReleaseEvent(QMouseEvent *e)

QAbstractButton::mouseReleaseEvent(QMouseEvent *e)를 재구현합니다.

[override virtual protected] void QToolButton::nextCheckState()

QAbstractButton::nextCheckState()을 재구현합니다.

[override virtual protected] void QToolButton::paintEvent(QPaintEvent *event)

QAbstractButton::paintEvent(QPaintEvent *e)를 재구현합니다.

event 의 페인트 호출에 응답하여 버튼을 그립니다.

[slot] void QToolButton::setDefaultAction(QAction *action)

기본 동작을 ‘ action ’로 설정합니다.

도구 버튼에 기본 동작이 설정되어 있는 경우, 해당 동작은 버튼의 다음 속성을 정의합니다:

autoRepeat 과 같은 다른 속성은 동작의 영향을 받지 않습니다.

defaultAction()도 참조하십시오 .

void QToolButton::setMenu(QMenu *menu)

지정된 ‘ menu ’를 이 도구 버튼에 연결합니다.

버튼의 popupMode 에 따라 메뉴가 표시됩니다.

메뉴의 소유권은 도구 버튼으로 이전되지 않습니다.

menu()도 참조하십시오 .

[slot] void QToolButton::showMenu()

관련된 팝업 메뉴를 표시(팝업)합니다. 해당 메뉴가 없는 경우, 이 함수는 아무 작업도 수행하지 않습니다. 이 함수는 사용자가 팝업 메뉴를 닫을 때까지 반환되지 않습니다.

[override virtual] QSize QToolButton::sizeHint() const

QWidget::sizeHint 속성에 대한 액세스 함수를 재구현합니다.

[override virtual protected] void QToolButton::timerEvent(QTimerEvent *e)

QAbstractButton::timerEvent(QTimerEvent *e)를 재구현합니다.

[signal] void QToolButton::triggered(QAction *action)

이 신호는 지정된 action 가 트리거될 때 발생합니다.

이 동작은 메뉴 항목이나 키보드 단축키와 같은 사용자 인터페이스의 다른 요소와도 연결될 수 있습니다. 이러한 방식으로 동작을 공유하면 사용자 인터페이스의 일관성을 높일 수 있을 뿐만 아니라, 구현에 드는 노력도 줄이는 경우가 많습니다.

© 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.