Sur cette page

QToolButton Class

La classe `QToolButton` permet de créer un bouton d'accès rapide à des commandes ou à des options, généralement utilisé dans une interface utilisateur graphique ( QToolBar). En savoir plus...

En-tête : #include <QToolButton>
CMake : find_package(Qt6 REQUIRED COMPONENTS Widgets)
target_link_libraries(mytarget PRIVATE Qt6::Widgets)
qmake : QT += widgets
Hérite de : QAbstractButton

Types publics

enum ToolButtonPopupMode { DelayedPopup, MenuButtonPopup, InstantPopup }

Propriétés

Fonctions publiques

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

Fonctions publiques réimplémentées

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

Slots publics

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

Signaux

void triggered(QAction *action)

Fonctions protégées

virtual void initStyleOption(QStyleOptionToolButton *option) const

Fonctions protégées réimplémentées

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

Description détaillée

Un bouton d'outil est un bouton spécial qui permet d'accéder rapidement à des commandes ou options spécifiques. Contrairement à un bouton de commande classique, un bouton d'outil n'affiche généralement pas de libellé, mais une icône à la place.

Les boutons d'outil sont généralement créés lors de la création de nouvelles instances d'QAction s à l'aide de ` QToolBar::addAction()` ou lors de l'ajout d'actions existantes à une barre d'outils à l'aide de ` QToolBar::addAction()`. Il est également possible de créer des boutons d'outil de la même manière que n'importe quel autre widget et de les disposer aux côtés d'autres widgets dans des mises en page.

Une utilisation classique d’un bouton d’outil consiste à sélectionner des outils ; par exemple, l’outil « crayon » dans un programme de dessin. Cela s’implémenterait en utilisant un QToolButton comme bouton bascule (voir setCheckable()).

QToolButton prend en charge l’affichage automatique. En mode d’affichage automatique, le bouton affiche un cadre 3D uniquement lorsque la souris le survole. Cette fonctionnalité est automatiquement activée lorsqu’un bouton est utilisé à l’intérieur d’un QToolBar. Vous pouvez la modifier à l’aide de setAutoRaise().

L’icône d’un bouton d’outil est définie via ` QIcon`. Cela permet de spécifier des images différentes pour les états désactivé et actif. L’image de l’état désactivé est utilisée lorsque la fonctionnalité du bouton n’est pas disponible. L’image de l’état actif s’affiche lorsque le bouton est en mode « auto-raise » parce que le pointeur de la souris survole le bouton.

L’apparence et les dimensions du bouton sont réglables à l’aide de ` setToolButtonStyle()` et ` setIconSize()`. Lorsqu’il est utilisé à l’intérieur d’une ` QToolBar ` dans une ` QMainWindow`, le bouton s’adapte automatiquement aux paramètres de ` QMainWindow` (voir ` QMainWindow::setToolButtonStyle()` et ` QMainWindow::setIconSize()`). Au lieu d’une icône, un bouton d’outil peut également afficher un symbole en forme de flèche, spécifié à l’aide de ` arrowType`.

Un bouton d’outil peut proposer des choix supplémentaires dans un menu contextuel. Ce menu contextuel peut être défini à l’aide de ` setMenu()`. Utilisez ` setPopupMode()` pour configurer les différents modes disponibles pour les boutons d’outil dotés d’un menu. Le mode par défaut est DelayedPopupMode, qui est parfois utilisé avec le bouton « Retour » d’un navigateur Web. Après avoir maintenu le bouton enfoncé pendant un certain temps, un menu s’affiche, présentant une liste des pages vers lesquelles il est possible d’accéder. Le délai d’attente dépend du style ; voir QStyle::SH_ToolButton_PopupDelay.

Barre d'outils de <span translate=Qt Assistant avec ses boutons d'outils" src="images/assistant-toolbar.png" title="Barre d'outils de Qt Assistant avec ses boutons d'outils"/>

Qt AssistantLa barre d’outils contient des boutons d’outils associés à des actions utilisées dans d’autres parties de la fenêtre principale.

Voir également QPushButton, QToolBar, QMainWindow et QAction.

Documentation sur les types de membres

enum QToolButton::ToolButtonPopupMode

Décrit comment un menu doit s'afficher pour les boutons d'outils qui disposent d'un ensemble de menus ou qui contiennent une liste d'actions.

ConstanteValeurDescription
QToolButton::DelayedPopup0Après avoir maintenu le bouton d’outil enfoncé pendant un certain temps (le délai dépend du style, voir QStyle::SH_ToolButton_PopupDelay), le menu s’affiche. Un exemple d'application courant est le bouton « Retour » présent dans les barres d'outils de certains navigateurs Web. Si l'utilisateur clique dessus, le navigateur revient simplement à la page précédente. Si l'utilisateur appuie sur le bouton et le maintient enfoncé pendant un certain temps, le bouton d'outil affiche un menu contenant la liste de l'historique actuel
QToolButton::MenuButtonPopup1Dans ce mode, le bouton d’outil affiche une flèche spéciale pour indiquer la présence d’un menu. Le menu s’affiche lorsque l’on appuie sur la partie en forme de flèche du bouton.
QToolButton::InstantPopup2Le menu s'affiche, sans délai, lorsque l'on appuie sur le bouton d'outil. Dans ce mode, l'action propre au bouton n'est pas déclenchée.

Documentation sur les propriétés

arrowType : Qt::ArrowType

Cette propriété détermine si le bouton affiche une flèche à la place d'une icône normale

Cette propriété affiche une flèche comme icône pour l'QToolButton.

Par défaut, cette propriété est définie sur « Qt::NoArrow ».

Fonctions d'accès :

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

autoRaise : bool

Cette propriété s'applique, que l'augmentation automatique soit activée ou non.

Par défaut, elle est désactivée (c'est-à-dire « false »).

Cette propriété est actuellement ignorée sous macOS lors de l'utilisation de QMacStyle.

Fonctions d'accès :

bool autoRaise() const
void setAutoRaise(bool enable)

popupMode : ToolButtonPopupMode

décrit la manière dont les menus contextuels sont utilisés avec les boutons d'outils

Par défaut, cette propriété est définie sur « DelayedPopup ».

Fonctions d'accès :

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

toolButtonStyle : Qt::ToolButtonStyle

Cette propriété détermine si le bouton d'outil affiche uniquement une icône, uniquement du texte, ou du texte à côté ou en dessous de l'icône.

La valeur par défaut est « Qt::ToolButtonIconOnly ».

Pour que le style des boutons d’outils respecte les paramètres système, définissez cette propriété sur « Qt::ToolButtonFollowStyle ». Sous Unix, ce sont les paramètres utilisateur de l’environnement de bureau qui seront utilisés. Sur les autres plateformes, « Qt::ToolButtonFollowStyle » signifie « icône uniquement ».

QToolButton relie automatiquement ce slot au signal correspondant dans l’ QMainWindow dans laquelle il se trouve.

Fonctions d’accès :

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

Documentation des fonctions membres

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

Crée un bouton d'outil vide dont le parent est parent.

[virtual noexcept] QToolButton::~QToolButton()

Détruit l'objet et libère toutes les ressources allouées.

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

Réimplémente : QWidget::actionEvent(QActionEvent *event).

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

Réimplémente : QAbstractButton::changeEvent(QEvent *e).

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

Réimplémente : QAbstractButton::checkStateSet().

QAction *QToolButton::defaultAction() const

Renvoie l'action par défaut.

Voir aussi setDefaultAction().

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

Réimplémente : QWidget::enterEvent(QEnterEvent *event).

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

Réimplémente : QAbstractButton::event(QEvent *e).

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

Réimplémente : QAbstractButton::hitButton(const QPoint &pos) const.

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

Initialisez ` option ` avec les valeurs fournies à l'adresse suivante : QToolButton. Cette méthode est utile pour les sous-classes qui ont besoin d'un ` QStyleOptionToolButton`, mais ne souhaitent pas renseigner elles-mêmes toutes les informations.

Voir également QStyleOption::initFrom().

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

Réimplémente : QWidget::leaveEvent(QEvent *event).

Renvoie le menu associé, ou « nullptr » si aucun menu n'a été défini.

Voir aussi setMenu().

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

Réimplémente une fonction d'accès pour la propriété : QWidget::minimumSizeHint.

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

Réimplémente : QAbstractButton::mousePressEvent(QMouseEvent *e).

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

Réimplémente : QAbstractButton::mouseReleaseEvent(QMouseEvent *e).

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

Réimplémente : QAbstractButton::nextCheckState().

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

Réimplémente : QAbstractButton::paintEvent(QPaintEvent *e).

Dessine le bouton en réponse à l'event de dessin.

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

Définit l'action par défaut sur « action ».

Si un bouton d'outil possède une action par défaut, celle-ci définit les propriétés suivantes du bouton :

Les autres propriétés, telles que autoRepeat, ne sont pas affectées par les actions.

Voir également defaultAction().

void QToolButton::setMenu(QMenu *menu)

Associe l'menu on indiquée à ce bouton d'outil.

Le menu s'affichera en fonction de l'popupMode ation du bouton.

La propriété du menu n’est pas transférée au bouton d’outil.

Voir aussi menu().

[slot] void QToolButton::showMenu()

Affiche (en fenêtre contextuelle) le menu contextuel associé. Si ce menu n'existe pas, cette fonction ne fait rien. Cette fonction ne retourne pas avant que le menu contextuel ait été fermé par l'utilisateur.

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

Réimplémente une fonction d'accès pour la propriété : QWidget::sizeHint.

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

Réimplémente : QAbstractButton::timerEvent(QTimerEvent *e).

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

Ce signal est émis lorsque l'action on indiquée est déclenchée.

L'action peut également être associée à d'autres éléments de l'interface utilisateur, tels que des éléments de menu et des raccourcis clavier. Le partage des actions de cette manière contribue à rendre l'interface utilisateur plus cohérente et nécessite souvent moins d'efforts de mise en œuvre.

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