QMenuBar Class
La classe QMenuBar permet de créer une barre de menus horizontale. En savoir plus...
| En-tête : | #include <QMenuBar> |
| CMake : | find_package(Qt6 REQUIRED COMPONENTS Widgets) target_link_libraries(mytarget PRIVATE Qt6::Widgets) |
| qmake : | QT += widgets |
| Hérite de : | 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 |
Slots 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 menus se compose d'une liste d'éléments de menu déroulants. Vous ajoutez des éléments de menu à l'aide de la fonction ` addMenu()`. Par exemple, en supposant que ` menubar ` soit un pointeur vers un `QMenuBar` et que ` fileMenu ` soit un pointeur vers un ` QMenu`, l'instruction suivante insère le menu dans la barre de menus :
menubar->addMenu(fileMenu);Le signe « & » dans le texte de l’élément de menu définit Alt+F comme raccourci clavier pour ce menu. (Vous pouvez utiliser « && » pour afficher un véritable signe « & » dans la barre de menus.)
Il n’est pas nécessaire de définir la disposition d’une barre de menus. Elle définit automatiquement sa propre géométrie en haut du widget parent et la modifie en conséquence chaque fois que celui-ci est redimensionné.
Utilisation
Dans la plupart des applications de type « fenêtre principale », vous utiliserez la fonction ` menuBar()` fournie dans ` QMainWindow`, en ajoutant des éléments ` QMenu` à la barre de menus et des éléments ` QAction` aux menus contextuels.
Exemple (tiré de l’exemple « 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 à l’aide d’instances de la classe ` QWidgetAction ` destinées à les contenir. Ces actions peuvent ensuite être insérées dans les menus de la manière habituelle ; consultez la documentation de QMenu pour plus de détails.
Aspect et comportement spécifiques à chaque plateforme
Les différentes plateformes ont des exigences différentes concernant l’apparence des barres de menus et leur comportement lorsque l’utilisateur interagit avec elles. Par exemple, les systèmes Windows sont souvent configurés de telle sorte que les mnémoniques soulignées indiquant les raccourcis clavier des éléments de la barre de menus ne s’affichent que lorsque la touche Alt est enfoncée.
QMenuBar en tant que barre de menus globale
Sous macOS et dans certains environnements de bureau Linux tels qu’Ubuntu Unity, QMenuBar sert d’enveloppe permettant d’utiliser la barre de menus système. Si une boîte de dialogue contient plusieurs barres de menus, la barre de menus la plus externe (généralement située à l’intérieur d’un widget portant le drapeau Qt::Window) sera utilisée comme barre de menus système.
Qt pour macOS propose également une fonctionnalité de fusion des barres de menus afin que QMenuBar s'adapte davantage à la disposition standard des barres de menus macOS. Si une entrée est déplacée, ses slots se déclencheront toujours comme si elle se trouvait à son emplacement d'origine.
La fonctionnalité de fusion repose sur la méthode ` QAction::menuRole()` des entrées de menu. Si un élément dispose d’un paramètre ` QAction::TextHeuristicRole`, son rôle est déterminé par la correspondance d’une chaîne de caractères avec le titre, selon les heuristiques suivantes :
| Correspondances de chaînes | Emplacement | Remarques |
|---|---|---|
| about.* | Menu de l'application | À propos de <nom de l'application> | Le nom de l'application est extrait du fichier Info.plist (voir la remarque ci-dessous). Si cette entrée n'est pas trouvée, aucun élément « À propos » n'apparaîtra dans le menu de l'application. |
| config, options, configuration, paramètres ou préférences | Menu de l'application | Préférences | Si cette entrée est introuvable, l'élément « Paramètres » sera désactivé |
| Quitter ou Sortir | Menu de l'application | Quitter <nom de l'application> | Si cette entrée n'est pas trouvée, un élément « Quitter » par défaut sera créé pour appeler la méthode QCoreApplication::quit() |
Vous pouvez remplacer 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 seule barre de menus, vous devez créer une barre de menus sans parent. Créez une barre de menus sans parent de la manière suivante :
Remarque : n’ appelez pas la fonction ` QMainWindow::menuBar()` pour créer la barre de menus partagée, car celle-ci aurait alors pour parent ` QMainWindow `. Cette barre de menus ne s’afficherait alors que pour l’ QMainWindow parent.
Remarque : le texte utilisé pour le nom de l'application dans la barre de menus macOS est extrait de la valeur définie dans le fichier ` Info.plist ` du 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 D-Bus, Qt communiquera alors avec celui-ci pour installer les menus de l'application dans la barre de menus globale, comme décrit.
Exemples
L'exemple Menus montre comment utiliser QMenuBar et QMenu. Les autres exemples d’applications à fenêtre principale proposent également des menus utilisant ces classes.
Voir également QMenu, QShortcut, QAction, Introduction aux directives d’interface utilisateur d’Apple et l’exemple « Menus ».
Documentation sur les propriétés
defaultUp : bool
Cette propriété définit l'orientation de la fenêtre contextuelle
Orientation par défaut de la fenêtre contextuelle. Par défaut, les menus s'affichent « vers le bas » de l'écran. En définissant cette propriété sur « true », le menu s'affichera « vers le haut ». Vous pouvez utiliser cette option pour les menus situés en dessous du document auquel ils se réfèrent.
Si le menu ne tient pas sur l’écran, l’autre sens est utilisé automatiquement.
Fonctions d'accès :
| bool | isDefaultUp() const |
| void | setDefaultUp(bool) |
nativeMenuBar : bool
Cette propriété détermine si la barre de menus doit être utilisée en tant que barre de menus native sur les plateformes qui la prennent en charge
Cette propriété spécifie si la barre de menus doit ou non être utilisée en tant que barre de menus native sur les plateformes 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é est définie sur « true », la barre de menus s’affiche dans la barre de menus native et n’apparaît pas dans la fenêtre de son parent ; si elle est définie sur « 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 sa lecture renvoie toujours la valeur « false ».
Par défaut, le comportement dépend de la présence ou non de l'attribut ` Qt::AA_DontUseNativeMenuBar ` pour l'application. La définition explicite de cette propriété remplace 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)
Crée une barre de menu dont le parent est parent.
[virtual noexcept] QMenuBar::~QMenuBar()
Supprime la barre de menus.
QAction *QMenuBar::actionAt(const QPoint &pt) const
Renvoie la balise QAction à l'adresse pt. Renvoie nullptr s'il n'y a pas d'action à l'adresse pt ou si l'emplacement comporte un séparateur.
Voir également 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 la forme d'un objet de type ` QRect`.
Voir également actionAt().
QAction *QMenuBar::activeAction() const
Renvoie l'QAction actuellement sélectionnée, le cas échéant, sinon nullptr.
Voir aussi setActiveAction().
QAction *QMenuBar::addMenu(QMenu *menu)
Ajoute « menu » à la barre de menus. Renvoie la méthode `menuAction()` du menu. La barre de menus ne prend pas possession 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 menu « QMenu » avec l'élément « title » à la barre de menus. La barre de menus prend en charge ce menu. Renvoie le nouveau menu.
Voir également QWidget::addAction() et QMenu::menuAction().
QMenu *QMenuBar::addMenu(const QIcon &icon, const QString &title)
Ajoute un nouveau menu « QMenu » comprenant les éléments « icon » et « title » à la barre de menus. La barre de menus prend en charge ce menu. Renvoie le nouveau menu.
Voir également 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 menus.
Remarque : sous macOS, les éléments de menu qui ont été fusionnés dans la barre de menus système ne sont pas supprimés par cette fonction. Une solution consiste à supprimer vous-même les actions superflues. Vous pouvez définir les options d'menu role s sur les différents menus, afin de savoir à l'avance quels éléments de menu seront fusionnés et lesquels ne le seront pas. Vous pourrez alors décider vous-même 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 élément de menu ou à droite du dernier, selon la valeur de corner.
Remarque : l'utilisation d'un coin autre que Qt::TopRightCorner ou Qt::TopLeftCorner entraînera l'affichage d'un avertissement.
Voir aussi 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émentation de : QWidget::heightForWidth(int w) const.
[signal] void QMenuBar::hovered(QAction *action)
Ce signal est émis lorsqu'une action de menu est mise en surbrillance ; ` action ` correspond à l'action qui a déclenché l'envoi de l'événement.
Cette fonction est souvent utilisée pour mettre à jour des informations d'état.
Voir également triggered() et QAction::hovered().
[virtual protected] void QMenuBar::initStyleOption(QStyleOptionMenuItem *option, const QAction *action) const
Initialisez ` option ` avec les valeurs de la barre de menu et les informations provenant de action. Cette méthode est utile pour les sous-classes qui ont besoin d’un ` QStyleOptionMenuItem`, mais ne souhaitent pas renseigner elles-mêmes toutes les informations.
Voir également QStyleOption::initFrom() et QMenu::initStyleOption().
QAction *QMenuBar::insertMenu(QAction *before, QMenu *menu)
Cette fonction pratique insère menu avant l'action before et renvoie les menus via menuAction().
Voir également QWidget::insertAction() et addMenu().
QAction *QMenuBar::insertSeparator(QAction *before)
Cette fonction pratique crée une nouvelle action de séparation, c'est-à-dire une action pour laquelle la méthode QAction::isSeparator() renvoie « true ». La fonction insère l'action nouvellement créée dans la liste des actions de cette barre de menus, avant l'action before, puis la renvoie.
Voir également 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 pour 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 sélectionnée sur « act ».
Voir également activeAction().
void QMenuBar::setCornerWidget(QWidget *widget, Qt::Corner corner = Qt::TopRightCorner)
Cela permet d'afficher l'widget on donnée directement à gauche du premier élément du menu, ou à droite du dernier élément du menu, selon la valeur de ` corner`.
La barre de menu prend possession de widget et le rattache à la barre de menu. Cependant, si corner contient déjà un widget, ce widget ne sera plus géré et restera un enfant visible de la barre de menu.
Remarque : l’utilisation d’un coin autre que Qt::TopRightCorner ou Qt::TopLeftCorner entraînera l’affichage d’un avertissement.
Voir aussi cornerWidget().
[override virtual slot] void QMenuBar::setVisible(bool visible)
Réimplémente une fonction d'accès pour la propriété : QWidget::visible.
[override virtual] QSize QMenuBar::sizeHint() const
Réimplémente une fonction d'accès pour 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 associé à cette barre de menus. Disponible uniquement sous macOS.
Remarque : Qt peut définir le délégué sur la barre de menus native. Si vous devez définir votre propre délégué, veillez à enregistrer l'original et à lui transférer tous les appels qui lui sont destinés.
[signal] void QMenuBar::triggered(QAction *action)
Ce signal est émis lorsqu’une action d’un menu appartenant à cette barre de menus est déclenchée à la suite d’un clic de souris ; action correspond à l’action qui a provoqué l’émission du signal.
Normalement, on associe chaque action de menu à un seul slot à l’aide de ` QAction::triggered()` (), mais il arrive parfois que l’on souhaite associer plusieurs éléments à un seul slot (le plus souvent lorsque l’utilisateur effectue une sélection dans un tableau). Ce signal est utile dans de tels cas.
Voir également 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.
