Difference between QPushButton and QToolButton

I'm new to Qt and the difference between QPushButton and QToolButton is not so clear to me.

I know that a QToolButton is usually used in a QToolBar and it usually shows only an icon, without text, but I don't quite understand the main difference between both.

Does it have any bigger difference? When should I use QPushButton and when should I use QToolButton?

I would like to know this to use the most appropriate button, and I need to perform some GUI tests and maybe it can be relevant.

Solution

QPushButton is simply a button. QToolButton is part of a group of widgets in the QtWidgets module that operate on QActions: 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 with QAction. 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.