Sur cette page

QToolButton Class

La classe QToolButton fournit un bouton d'accès rapide à des commandes ou à des options, généralement utilisé à l'intérieur d'une page QToolBar. Plus....

En-tête : #include <QToolButton>
CMake : find_package(Qt6 REQUIRED COMPONENTS Widgets)
target_link_libraries(mytarget PRIVATE Qt6::Widgets)
qmake : QT += widgets
Héritages : 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

Emplacements 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 normal, un bouton d'outil n'affiche généralement pas de texte, mais une icône.

Les boutons d'outils sont normalement créés lorsque de nouvelles instances QAction sont créées avec QToolBar::addAction() ou que des actions existantes sont ajoutées à une barre d'outils avec QToolBar::addAction(). Il est également possible de construire des boutons d'outils de la même manière que n'importe quel autre widget et de les placer à côté d'autres widgets dans les mises en page.

Une utilisation classique d'un bouton d'outil est la sélection d'outils, par exemple l'outil "stylo" dans un programme de dessin. Pour ce faire, on utilise un QToolButton comme bouton de basculement (voir setCheckable()).

QToolButton prend en charge la levée automatique. En mode "auto-raise", le bouton dessine un cadre 3D uniquement lorsque la souris le pointe. Cette fonction est automatiquement activée lorsqu'un bouton est utilisé à l'intérieur d'un site QToolBar. Modifiez-la à l'aide de setAutoRaise().

L'icône d'un bouton d'outil est définie comme QIcon. Cela permet de spécifier des pixmaps différents pour l'état désactivé et l'état actif. La pixmap désactivée est utilisée lorsque la fonctionnalité du bouton n'est pas disponible. La pixmap active est affichée lorsque le bouton est levé automatiquement parce que le pointeur de la souris le survole.

L'aspect et la dimension du bouton sont ajustables avec setToolButtonStyle() et setIconSize(). Lorsqu'il est utilisé à l'intérieur d'un QToolBar dans un 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 de flèche, spécifié par arrowType.

Un bouton d'outil peut offrir des choix supplémentaires dans un menu contextuel. Le menu contextuel peut être configuré à l'aide de setMenu(). Utilisez setPopupMode() pour configurer les différents modes disponibles pour les boutons d'outils avec un ensemble de menus. Le mode par défaut est DelayedPopupMode, qui est parfois utilisé avec le bouton "Précédent" d'un navigateur web. Après avoir appuyé sur le bouton et l'avoir maintenu enfoncé pendant un certain temps, un menu apparaît, affichant une liste de pages possibles à consulter. Le délai d'attente dépend du style, voir QStyle::SH_ToolButton_PopupDelay.

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

Qt AssistantLa barre d'outils du logiciel 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 apparaître pour les boutons d'outils qui ont un ensemble de menus ou qui contiennent une liste d'actions.

ConstanteValeurDescription
QToolButton::DelayedPopup0Après avoir appuyé sur le bouton d'outil et l'avoir maintenu 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 typique est le bouton "retour" 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'utilisateur appuie sur la flèche du bouton.
QToolButton::InstantPopup2Le menu s'affiche, sans délai, lorsque l'on appuie sur le bouton de l'outil. Dans ce mode, l'action propre du bouton n'est pas déclenchée.

Documentation sur les propriétés

arrowType : Qt::ArrowType

Cette propriété indique si le bouton affiche une flèche au lieu d'une icône normale

Cette propriété affiche une flèche comme icône pour le bouton 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é indique si le relèvement automatique est activé ou non.

La valeur par défaut est désactivée (c'est-à-dire fausse).

Cette propriété est actuellement ignorée sur 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 déroulants 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é indique si le bouton d'outil affiche une icône uniquement, du texte uniquement ou du texte à côté et en dessous de l'icône.

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

Pour que le style des boutons d'outils suive les paramètres du système, définissez cette propriété sur Qt::ToolButtonFollowStyle. Sous Unix, les paramètres utilisateur de l'environnement de bureau seront utilisés. Sur les autres plates-formes, Qt::ToolButtonFollowStyle signifie icône uniquement.

QToolButton connecte automatiquement cet emplacement au signal correspondant dans le site QMainWindow dans lequel 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)

Construit un bouton d'outil vide avec le parent parent.

[virtual noexcept] QToolButton::~QToolButton()

Détruit l'objet et libère 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

Initialiser option avec les valeurs de QToolButton. Cette méthode est utile pour les sous-classes qui ont besoin d'un QStyleOptionToolButton, mais qui ne veulent pas remplir toutes les informations elles-mêmes.

Voir aussi 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 à 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).

Peint le bouton en réponse à l'événement paint event.

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

Définit l'action par défaut à action.

Si un bouton d'outil a une action par défaut, l'action 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 le site menu à ce bouton d'outil.

Le menu sera affiché en fonction du bouton popupMode.

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

Voir aussi menu().

[slot] void QToolButton::showMenu()

Affiche (fait apparaître) le menu contextuel associé. Si ce menu n'existe pas, cette fonction ne fait rien. Cette fonction ne revient pas tant que le menu contextuel n'a pas été fermé par l'utilisateur.

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

Réimplémente une fonction d'accès à 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 action est déclenchée.

L'action peut également être associée à d'autres parties de l'interface utilisateur, telles que des éléments de menu et des raccourcis clavier. Le partage d'actions de cette manière permet de rendre l'interface utilisateur plus cohérente et est souvent plus facile à mettre 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.