QMenuBar Class
La classe QMenuBar fournit une barre de menu horizontale. Plus d'informations...
| En-tête : | #include <QMenuBar> |
| CMake : | find_package(Qt6 REQUIRED COMPONENTS Widgets)target_link_libraries(mytarget PRIVATE Qt6::Widgets) |
| qmake : | QT += widgets |
| Héritages : | QWidget |
Propriétés
- defaultUp : bool
- nativeMenuBar : bool
Fonctions publiques
| QMenuBar(QWidget *parent = nullptr) | |
| virtual | ~QMenuBar() |
| QAction * | actionAt(const QPoint &pt) const |
| QRect | actionGeometry(QAction *act) const |
| QAction * | activeAction() const |
| QAction * | addMenu(QMenu *menu) |
| QMenu * | addMenu(const QString &title) |
| QMenu * | addMenu(const QIcon &icon, const QString &title) |
| QAction * | addSeparator() |
| void | clear() |
| QWidget * | cornerWidget(Qt::Corner corner = Qt::TopRightCorner) const |
| QAction * | insertMenu(QAction *before, QMenu *menu) |
| QAction * | insertSeparator(QAction *before) |
| bool | isDefaultUp() const |
| bool | isNativeMenuBar() const |
| void | setActiveAction(QAction *act) |
| void | setCornerWidget(QWidget *widget, Qt::Corner corner = Qt::TopRightCorner) |
| void | setDefaultUp(bool) |
| void | setNativeMenuBar(bool nativeMenuBar) |
| NSMenu * | toNSMenu() |
Fonctions publiques réimplémentées
| virtual int | heightForWidth(int) const override |
| virtual QSize | minimumSizeHint() const override |
| virtual QSize | sizeHint() const override |
Emplacements publics
| virtual void | setVisible(bool visible) override |
Signaux
Fonctions protégées
| virtual void | initStyleOption(QStyleOptionMenuItem *option, const QAction *action) const |
Fonctions protégées réimplémentées
| virtual void | actionEvent(QActionEvent *e) override |
| virtual void | changeEvent(QEvent *e) override |
| virtual bool | event(QEvent *e) override |
| virtual bool | eventFilter(QObject *object, QEvent *event) override |
| virtual void | focusInEvent(QFocusEvent *) override |
| virtual void | focusOutEvent(QFocusEvent *) override |
| virtual void | keyPressEvent(QKeyEvent *e) override |
| virtual void | leaveEvent(QEvent *) override |
| virtual void | mouseMoveEvent(QMouseEvent *e) override |
| virtual void | mousePressEvent(QMouseEvent *e) override |
| virtual void | mouseReleaseEvent(QMouseEvent *e) override |
| virtual void | paintEvent(QPaintEvent *e) override |
| virtual void | resizeEvent(QResizeEvent *) override |
| virtual void | timerEvent(QTimerEvent *e) override |
Description détaillée
Une barre de menu consiste en une liste d'éléments de menu déroulants. Vous ajoutez des éléments de menu à l'aide de addMenu(). Par exemple, en supposant que menubar est un pointeur sur une QMenuBar et que fileMenu est un pointeur sur QMenu, l'instruction suivante insère le menu dans la barre de menus :
menubar->addMenu(fileMenu);
L'esperluette dans le texte de l'élément de menu définit Alt+F comme raccourci pour ce menu. (Vous pouvez utiliser "&&" pour obtenir une véritable esperluette dans la barre de menus).
Il n'est pas nécessaire de créer une barre de menus. Elle définit automatiquement sa propre géométrie en haut du widget parent et la modifie de manière appropriée lorsque le parent est redimensionné.
Utilisation
Dans la plupart des applications de type fenêtre principale, vous utiliserez la fonction menuBar() fournie dans QMainWindow, en ajoutant QMenus à la barre de menus et QActions aux menus contextuels.
Exemple (tiré de l'exemple des menus ) :
fileMenu = menuBar()->addMenu(tr("&File")); fileMenu->addAction(newAct);
Les éléments de menu peuvent être supprimés à l'aide de la fonction removeAction().
Des widgets peuvent être ajoutés aux menus en utilisant des instances de la classe QWidgetAction pour les contenir. Ces actions peuvent ensuite être insérées dans les menus de la manière habituelle ; voir la documentation QMenu pour plus de détails.
Apparence dépendante de la plate-forme
Les exigences relatives à l'apparence des barres de menus et à leur comportement lorsque l'utilisateur interagit avec elles varient d'une plate-forme à l'autre. Par exemple, les systèmes Windows sont souvent configurés de manière à ce que les caractères mnémoniques soulignés qui indiquent les raccourcis clavier pour les éléments de la barre de menu ne s'affichent que lorsque la touche Alt est enfoncée.
QMenuBar en tant que barre de menu globale
Sous macOS et dans certains environnements de bureau Linux tels qu'Ubuntu Unity, QMenuBar est une enveloppe permettant d'utiliser la barre de menu globale du système. Si vous avez plusieurs barres de menu dans un dialogue, la barre de menu la plus externe (normalement à l'intérieur d'un widget avec le drapeau de widget Qt::Window) sera utilisée pour la barre de menu globale.
Qt pour macOS fournit également une fonction de fusion des barres de menu pour rendre QMenuBar plus conforme à la disposition acceptée des barres de menu de macOS. Si une entrée est déplacée, ses slots seront toujours activés comme s'ils se trouvaient à l'emplacement d'origine.
La fonctionnalité de fusion est basée sur le QAction::menuRole() des entrées de menu. Si un élément a QAction::TextHeuristicRole, le rôle est déterminé par la correspondance de la chaîne de caractères du titre à l'aide de l'heuristique suivante :
| Correspondance de chaînes | Placement | Notes |
|---|---|---|
| about.* | Menu d'application | À propos de <nom de l'application> | Le nom de l'application est extrait du fichier Info.plist (voir note ci-dessous). Si cette entrée n'est pas trouvée, aucun élément About n'apparaîtra dans le menu d'application. |
| config, options, configuration, réglages ou préférences | Menu d'application | Préférences | Si cette entrée n'est pas trouvée, l'élément Paramètres sera désactivé. |
| quitter ou quitter | Menu d'application | Quitter <nom de l'application> | Si cette entrée n'est pas trouvée, un élément Quit par défaut sera créé pour appeler QCoreApplication::quit(). |
Vous pouvez ignorer ce comportement en définissant la propriété QAction::menuRole() sur QAction::NoRole.
Si vous souhaitez que toutes les fenêtres d'une application Mac partagent une même barre de menus, vous devez créer une barre de menus sans parent. Créez une barre de menu sans parent de cette manière :
Remarque : n ' appelez pas QMainWindow::menuBar() pour créer la barre de menu partagée, car cette barre de menu aura pour parent QMainWindow. Cette barre de menu ne serait affichée que pour le parent QMainWindow.
Note : Le texte utilisé pour le nom de l'application dans la barre de menu macOS est obtenu à partir de la valeur définie dans le fichier Info.plist dans le bundle de l'application. Voir Qt pour macOS - Déploiement pour plus d'informations.
Remarque : sous Linux, si le service com.canonical.AppMenu.Registrar est disponible sur le bus de session Qt-Bus, alors Qt communiquera avec lui pour installer les menus de l'application dans la barre de menu globale, comme décrit.
Exemples
L'exemple Menus montre comment utiliser QMenuBar et QMenu. Les autres exemples d'application de la fenêtre principale fournissent également des menus à l'aide de ces classes.
Voir également QMenu, QShortcut, QAction, Introduction aux directives d'interface humaine d'Apple et Exemple de menus.
Documentation sur les propriétés
defaultUp : bool
Cette propriété contient l'orientation de la fenêtre contextuelle
L'orientation par défaut de la fenêtre contextuelle. Par défaut, les menus s'affichent "vers le bas" de l'écran. En attribuant la valeur true à cette propriété, le menu s'affichera "vers le haut". Cette propriété peut être utilisée pour les menus qui se trouvent en dessous du document auquel ils se réfèrent.
Si le menu ne tient pas à l'écran, l'autre sens est utilisé automatiquement.
Fonctions d'accès :
| bool | isDefaultUp() const |
| void | setDefaultUp(bool) |
nativeMenuBar : bool
Cette propriété indique si une barre d'outils doit être utilisée comme barre d'outils native sur les plates-formes qui la prennent en charge.
Cette propriété indique si la barre de menus doit être utilisée comme barre de menus native sur les plates-formes qui la prennent en charge. Les plateformes actuellement prises en charge sont macOS et les ordinateurs de bureau Linux qui utilisent l'interface D-Bus com.canonical.dbusmenu (comme Ubuntu Unity). Si cette propriété vaut true, la barre de menus est utilisée dans la barre de menus native et ne se trouve pas dans la fenêtre de son parent ; si elle vaut false, la barre de menus reste dans la fenêtre. Sur les autres plateformes, la définition de cet attribut n'a aucun effet, et la lecture de cet attribut renvoie toujours false.
Par défaut, l'application suit si l'attribut Qt::AA_DontUseNativeMenuBar est défini pour l'application. Le fait de définir explicitement cette propriété annule la présence (ou l'absence) de l'attribut.
Fonctions d'accès :
| bool | isNativeMenuBar() const |
| void | setNativeMenuBar(bool nativeMenuBar) |
Documentation des fonctions membres
[explicit] QMenuBar::QMenuBar(QWidget *parent = nullptr)
Construit une barre de menu avec le parent parent.
[virtual noexcept] QMenuBar::~QMenuBar()
Détruit la barre de menu.
QAction *QMenuBar::actionAt(const QPoint &pt) const
Renvoie l'adresse QAction à pt. Renvoie nullptr s'il n'y a pas d'action à pt ou si l'emplacement a un séparateur.
Voir aussi QWidget::addAction() et addSeparator().
[override virtual protected] void QMenuBar::actionEvent(QActionEvent *e)
Réimplémente : QWidget::actionEvent(QActionEvent *event).
QRect QMenuBar::actionGeometry(QAction *act) const
Renvoie la géométrie de l'action act sous forme de QRect.
Voir aussi actionAt().
QAction *QMenuBar::activeAction() const
Retourne le QAction qui est actuellement mis en évidence, s'il y en a un, sinon nullptr.
Voir aussi setActiveAction().
QAction *QMenuBar::addMenu(QMenu *menu)
Ajoute menu à la barre de menu. Retourne la fonction menuAction() du menu. La barre de menu n'est pas propriétaire du menu.
Remarque : l'objet QAction renvoyé peut être utilisé pour masquer le menu correspondant.
Voir également QWidget::addAction() et QMenu::menuAction().
QMenu *QMenuBar::addMenu(const QString &title)
Ajoute un nouveau QMenu avec title à la barre de menu. La barre de menu devient propriétaire du menu. Renvoie le nouveau menu.
Voir aussi QWidget::addAction() et QMenu::menuAction().
QMenu *QMenuBar::addMenu(const QIcon &icon, const QString &title)
Ajoute un nouveau QMenu avec icon et title à la barre de menu. La barre de menu devient propriétaire du menu. Renvoie le nouveau menu.
Voir aussi QWidget::addAction() et QMenu::menuAction().
QAction *QMenuBar::addSeparator()
Ajoute un séparateur au menu.
[override virtual protected] void QMenuBar::changeEvent(QEvent *e)
Réimplémente : QWidget::changeEvent(QEvent *event).
void QMenuBar::clear()
Supprime toutes les actions de la barre de menu.
Remarque : sur macOS, les éléments de menu qui ont été fusionnés avec la barre de menu système ne sont pas supprimés par cette fonction. L'une des solutions consiste à supprimer vous-même les actions supplémentaires. Vous pouvez définir l'adresse menu role pour les différents menus, afin de savoir à l'avance quels éléments de menu sont fusionnés et lesquels ne le sont pas. Vous déciderez ensuite vous-même de ce qu'il convient de recréer ou de supprimer.
Voir également removeAction().
QWidget *QMenuBar::cornerWidget(Qt::Corner corner = Qt::TopRightCorner) const
Renvoie le widget situé à gauche du premier ou à droite du dernier élément du menu, en fonction de corner.
Remarque : l'utilisation d'un coin autre que Qt::TopRightCorner ou Qt::TopLeftCorner entraînera un avertissement.
Voir également setCornerWidget().
[override virtual protected] bool QMenuBar::event(QEvent *e)
Réimplémente : QWidget::event(QEvent *event).
[override virtual protected] bool QMenuBar::eventFilter(QObject *object, QEvent *event)
Réimplémente : QObject::eventFilter(QObject *watched, QEvent *event).
[override virtual protected] void QMenuBar::focusInEvent(QFocusEvent *)
Réimplémente : QWidget::focusInEvent(QFocusEvent *event).
[override virtual protected] void QMenuBar::focusOutEvent(QFocusEvent *)
Réimplémente : QWidget::focusOutEvent(QFocusEvent *event).
[override virtual] int QMenuBar::heightForWidth(int) const
Réimplémente : QWidget::heightForWidth(int w) const.
[signal] void QMenuBar::hovered(QAction *action)
Ce signal est émis lorsqu'une action de menu est mise en évidence ; action est l'action qui a provoqué l'envoi de l'événement.
Ce signal est souvent utilisé pour mettre à jour les informations d'état.
Voir également triggered() et QAction::hovered().
[virtual protected] void QMenuBar::initStyleOption(QStyleOptionMenuItem *option, const QAction *action) const
Initialiser option avec les valeurs de la barre de menu et les informations de action. Cette méthode est utile pour les sous-classes lorsqu'elles ont besoin d'un QStyleOptionMenuItem, mais ne veulent pas remplir toutes les informations elles-mêmes.
Voir aussi QStyleOption::initFrom() et QMenu::initStyleOption().
QAction *QMenuBar::insertMenu(QAction *before, QMenu *menu)
Cette fonction de commodité insère menu avant l'action before et renvoie les menus menuAction().
Voir aussi QWidget::insertAction() et addMenu().
QAction *QMenuBar::insertSeparator(QAction *before)
Cette fonction de commodité crée une nouvelle action de séparation, c'est-à-dire une action pour laquelle QAction::isSeparator() renvoie true. La fonction insère l'action nouvellement créée dans la liste des actions de cette barre de menu avant l'action before et la renvoie.
Voir aussi QWidget::insertAction() et addSeparator().
[override virtual protected] void QMenuBar::keyPressEvent(QKeyEvent *e)
Réimplémente : QWidget::keyPressEvent(QKeyEvent *event).
[override virtual protected] void QMenuBar::leaveEvent(QEvent *)
Réimplémente : QWidget::leaveEvent(QEvent *event).
[override virtual] QSize QMenuBar::minimumSizeHint() const
Réimplémente une fonction d'accès à la propriété : QWidget::minimumSizeHint.
[override virtual protected] void QMenuBar::mouseMoveEvent(QMouseEvent *e)
Réimplémente : QWidget::mouseMoveEvent(QMouseEvent *event).
[override virtual protected] void QMenuBar::mousePressEvent(QMouseEvent *e)
Réimplémente : QWidget::mousePressEvent(QMouseEvent *event).
[override virtual protected] void QMenuBar::mouseReleaseEvent(QMouseEvent *e)
Réimplémente : QWidget::mouseReleaseEvent(QMouseEvent *event).
[override virtual protected] void QMenuBar::paintEvent(QPaintEvent *e)
Réimplémente : QWidget::paintEvent(QPaintEvent *event).
[override virtual protected] void QMenuBar::resizeEvent(QResizeEvent *)
Réimplémente : QWidget::resizeEvent(QResizeEvent *event).
void QMenuBar::setActiveAction(QAction *act)
Définit l'action actuellement en surbrillance à act.
Voir aussi activeAction().
void QMenuBar::setCornerWidget(QWidget *widget, Qt::Corner corner = Qt::TopRightCorner)
Cela permet d'afficher le site widget directement à gauche du premier élément du menu ou à droite du dernier élément du menu, en fonction de corner.
La barre de menu prend possession de widget, le répartissant dans la barre de menu. Toutefois, si le site corner contient déjà un widget, ce widget précédent ne sera plus géré et restera un enfant visible de la barre de menus.
Remarque : l'utilisation d'un coin autre que Qt::TopRightCorner ou Qt::TopLeftCorner entraînera un avertissement.
Voir aussi cornerWidget().
[override virtual slot] void QMenuBar::setVisible(bool visible)
Réimplémente une fonction d'accès à la propriété : QWidget::visible.
[override virtual] QSize QMenuBar::sizeHint() const
Réimplémente une fonction d'accès à la propriété : QWidget::sizeHint.
[override virtual protected] void QMenuBar::timerEvent(QTimerEvent *e)
Réimplémente : QObject::timerEvent(QTimerEvent *event).
NSMenu *QMenuBar::toNSMenu()
Renvoie le NSMenu natif de cette barre de menu. Disponible sur macOS uniquement.
Note : Qt peut définir le délégué de la barre de menu native. Si vous devez définir votre propre délégué, assurez-vous de sauvegarder l'original et de transférer tous les appels vers lui.
[signal] void QMenuBar::triggered(QAction *action)
Ce signal est émis lorsqu'une action dans un menu appartenant à ce ménubar est déclenchée à la suite d'un clic de souris ; action est l'action qui a provoqué l'émission du signal.
Normalement, vous reliez chaque action du menu à un seul emplacement en utilisant QAction::triggered(), mais il arrive que vous souhaitiez relier plusieurs éléments à un seul emplacement (le plus souvent si l'utilisateur choisit dans un tableau). Ce signal est utile dans ce cas.
Voir aussi hovered() et QAction::triggered().
© 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.
