QPushButton
is simply a button. QToolButton
is part of a group of widgets in the QtWidgets module that operate on QAction
s: QMenu
and QToolBar
are other examples. As a result, QToolButton
is much more complex under the hood than QPushButton
.
Some examples of how they are different in practice:
QToolButton
is tightly integrated withQAction
. Changing the icon, text, or other properties of a tool button’s default action is reflected on the button.- You can change the layout of the tool button contents (icon only, text only, text beside icon, text below icon). This is not possible for a
QPushButton
. QToolButton
supports a “split” button type: a sidebar hot zone opens a menu instead of triggering the default action.- Tool buttons can be created directly in a
QToolBar
by adding an action. Other widgets must be explicitly added to the toolbar. - A tool button is meant to be displayed in a grid, so it has smaller default internal margins than a push button.
QPushButton
is more for “Ok”/”Close” type buttons that contain text with an optional icon.- A
QToolButton
should generally have an icon. - A
QPushButton
should always have text.