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 } |
属性
- arrowType : Qt::ArrowType
- autoRaise : bool
- popupMode : ToolButtonPopupMode
- toolButtonStyle : Qt::ToolButtonStyle
公共函数
| 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 支持自动提升。在自动提升模式下，按钮只有在鼠标指向它时才会绘制三维框架。在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::DelayedPopup | 0 | 按住工具按钮一定时间后（超时时间与样式有关，请参见QStyle::SH_ToolButton_PopupDelay ），菜单将显示出来。一个典型的应用例子是某些网页浏览器工具栏中的 "后退 "按钮。如果用户点击它，浏览器就会返回到上一页面。如果用户按住按钮不放一会儿，工具按钮就会显示一个包含当前历史列表的菜单。 |
QToolButton::MenuButtonPopup | 1 | 在这种模式下，工具按钮会显示一个特殊的箭头，表示有一个菜单。按下按钮的箭头部分时，菜单就会显示出来。 |
QToolButton::InstantPopup | 2 | 按下工具按钮时，菜单会立即显示。在此模式下，按钮本身的操作不会被触发。 |
属性文档
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
使用此QToolButton 中的值初始化option 。当子类需要QStyleOptionToolButton ，但又不想自己填写所有信息时，该方法非常有用。
另请参阅 QStyleOption::initFrom()。
[override virtual protected] void QToolButton::leaveEvent(QEvent *e)
重实现：QWidget::leaveEvent(QEvent *event).
QMenu *QToolButton::menu() const
返回相关菜单，如果未定义菜单，则返回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)。
响应 paintevent ，为按钮上色。
[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 时，就会发出该信号。
该操作也可能与用户界面的其他部分相关联，如菜单项和键盘快捷键。以这种方式共享操作有助于使用户界面更加一致，而且通常实施起来也比较省事。
© 2025 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.
