QPushButton Class
QPushButton widget 提供了一个命令按钮。更多
| Header： | #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 |
详细说明
按钮或命令按钮可能是图形用户界面中最常用的部件。按下（点击）按钮可命令计算机执行某些操作或回答问题。典型的按钮有确定、应用、取消、关闭、是、否和帮助。
命令按钮是矩形的，通常会显示一个说明其操作的文本标签。快捷键可以通过在首选字符前加上 "ampersand "来指定。例如
QPushButton *button = new QPushButton("&Download", this);
本例中的快捷键是Alt+D。有关详情，请参阅QShortcut 文档（要显示真正的分号，请使用"&&"）。
按钮会显示文字标签，也可选择显示小图标。这些都可以通过构造函数进行设置，并在以后使用setText() 和setIcon() 进行更改。如果按钮被禁用，文本和图标的外观将根据 GUI 风格进行调整，使按钮看起来 "禁用"。
通过鼠标、空格键或键盘快捷键激活按钮时，按钮会发出clicked() 信号。连接到该信号可执行按钮的操作。按钮还提供一些不常用的信号，例如pressed() 和released()。
默认情况下，对话框中的命令按钮是自动默认按钮，也就是说，当它们接收到键盘输入焦点时，就会自动成为默认按钮。默认按钮是用户在对话框中按下 Enter 或 Return 键时激活的按钮。您可以使用setAutoDefault() 进行更改。请注意，自动默认按钮保留了一点额外空间，这是绘制默认按钮指示器所必需的。如果您不希望按钮周围有这些空间，请调用setAutoDefault(false)。
由于按钮部件非常重要，在过去的十年中，它已经发展出了许多不同的样式。现在，微软风格指南显示了大约十种不同的 Windows 按钮状态，文中还暗示，如果考虑到所有功能的组合，还会有几十种。
最重要的模式或状态有
- 可用或不可用（灰色显示，禁用）。
- 标准按钮、切换按钮或菜单按钮。
- 开或关（仅适用于切换按钮）。
- 默认或正常。对话框中的默认按钮通常可以用回车键或回车键 "点击"。
- 是否自动重复。
- 按下与否。
一般来说，当应用程序或对话窗口在用户点击时执行操作（如应用、取消、关闭和帮助），以及当部件应该是宽长方形并带有文本标签时，应使用按压式按钮。改变窗口状态而非执行操作的小型、典型的正方形按钮（如QFileDialog 右上角的按钮）不是命令按钮，而是工具按钮。Qt XML 为这些按钮提供了一个特殊的类 (QToolButton)。
如果您需要切换行为（请参阅setCheckable()) 或像滚动条中的箭头一样按下时自动重复激活信号的按钮（请参阅setAutoRepeat()) ，那么命令按钮可能不是您想要的。如有疑问，请使用工具按钮。
注意： 在 macOS 上，当推动按钮的宽度小于 50 或高度小于 30 时，按钮的边角会从圆形变为方形。请使用setMinimumSize() 函数防止出现这种情况。
菜单按钮是命令按钮的一种变体。这些按钮提供的不只是一个命令，而是多个命令，因为点击后会弹出一个选项菜单。使用setMenu() 方法可将弹出菜单与按钮关联起来。
按钮的其他类别还有选项按钮（参见QRadioButton ）和复选框（参见QCheckBox ）。
在 Qt 中，QAbstractButton 基类提供了大部分模式和其他 API，QPushButton 则提供了图形用户界面逻辑。有关 API 的更多信息，请参见QAbstractButton 。
另请参见 QToolButton,QRadioButton, 和QCheckBox 。
属性文档
autoDefault : bool
此属性表示按钮是否为自动默认按钮
如果该属性设置为 true，则该按钮为自动默认按钮。
在某些图形用户界面样式中，默认按钮周围会有一个额外的边框，最大可达 3 像素或更多。Qt 会自动在自动默认按钮周围保留空闲空间，也就是说，自动默认按钮可能有一个稍大的尺寸提示。
对于拥有QDialog 父对象的按钮，该属性默认为 true；否则默认为 false。
有关default 和自动默认如何交互的详细信息，请参阅default 属性。
访问功能：
| bool | autoDefault() const |
| void | setAutoDefault(bool) |
default : bool
此属性表示按下的按钮是否为默认按钮
默认按钮和自动默认按钮决定用户在对话框中按下回车键时会发生什么。
此属性设置为 true 的按钮（即对话框的默认按钮）将在用户按下回车键时自动按下，但有一个例外：如果autoDefault 按钮当前具有焦点，则会按下autoDefault 按钮。当对话框有autoDefault 按钮但没有默认按钮时，按回车键将按下当前有焦点的autoDefault 按钮，如果没有按钮有焦点，则按下焦点链中的下一个autoDefault 按钮。
在对话框中，一次只能有一个按钮作为默认按钮。该按钮会以附加框架显示（取决于 GUI 风格）。
默认按钮行为仅在对话框中提供。当按钮有焦点时，始终可以通过按空格键从键盘点击按钮。
如果在对话框可见时将当前默认按钮上的默认属性设置为 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 构建一个按钮。
请注意，您也可以传递QPixmap 对象作为图标（这要归功于 C++ 提供的隐式类型转换）。
[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
使用此QPushButton 中的值初始化option 。当子类需要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 widget 风格显示的带弹出菜单的按钮。
另请参见 menu()。
[slot] void QPushButton::showMenu()
显示（弹出）相关的弹出菜单。如果没有弹出菜单，则该函数不会执行任何操作。在用户关闭弹出菜单之前，该函数不会返回。
[override virtual] QSize QPushButton::sizeHint() const
重构属性访问函数：QWidget::sizeHint 。
© 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.
