QMenuBar

La classe QMenuBar fournit une barre de menu horizontale. Plus d'informations...

 #include <QMenuBar>

Héritage

Hérite de QWidget.

Description détaillée

La classe QMenuBar fournit une barre de menu horizontale.

Une barre de menu se compose d?une liste d?éléments de type menu déroulant. On ajoute des menus avec la fonction addMenu(). Par exemple, en supposant que menubar soit un pointeur vers une QMenuBar et fileMenu un pointeur vers un QMenu, le code suivant insère le menu dans la barre de menu :

 menubar->addMenu(fileMenu);

L?esperluette (&) dans le texte de l?élément de menu définit le raccourci pour ce menu à Alt+F (on peut utiliser  »&& » pour afficher l?esperluette dans la barre de menu).

Il n?est pas nécessaire de gérer le positionnement d'une barre de menu. Elle définit sa propre géométrie au-dessus du widget parent et la modifie de manière appropriée lorsque le parent est redimensionné.

Utilisation

Dans la plupart des applications avec fenêtre principale, on utilise la fonction menuBar() fournie par QMainWindow, en ajoutant des QMenu à la barre de menu et en ajoutant des QActions aux menus contextuels.

Voici un exemple (extrait de l?exemple Menus) :

     fileMenu = menuBar()->addMenu(tr("&File"));
     fileMenu->addAction(newAct);

Les éléments menu peuvent être enlevés avec la fonction removeAction().

Des widgets peuvent être ajoutés aux menus en utilisant des conteneurs de type QWidgetAction. Ces actions peuvent être insérées dans les menus de la manière habituelle ; voir la documentation QMenu pour plus d?informations.

Apparence dépendante de la plateforme

Des plateformes différentes ont des exigences différentes pour l?aspect de leurs barres de menus et leur comportement d?interaction avec l?utilisateur. Par exemple, les systèmes Windows sont souvent configurés de sorte que les caractères mnémoniques soulignés indiquant les raccourcis clavier pour les éléments de menu ne soient montrés que lorsque la touche Alt est pressée.

Le style de widget Plastique.	Le style de widget Plastique, comme la plupart des autres styles, gère le menu Aide de la même manière que les autres menus.
Le style de widget Motif.	Le style de widget Motif traite le menu Aide de façon particulière, en le plaçant à l'extrémité droite de la barre de menu.

QMenuBar sous Mac OS X

QMenuBar sous Mac OS X est un adaptateur (wrapper) pour l'utilisation de la barre de menu globale au système. Si on a plusieurs barres de menu dans la même fenêtre de dialogue, la barre de menu la plus proche de l'extérieur (normalement à l?intérieur d'un widget dont le drapeau Qt::Window est actif) sera utilisée comme barre de menu globale.

Qt pour Mac OS X fournit également une fonctionnalité de fusion de barres de menu pour rendre QMenuBar plus apte à accepter la disposition des barres de menu de Mac OS X. La fonctionnalité de fusion est basée sur une chaîne de caractères correspondant au titre d?une entrée QMenu. Ces chaînes de caractères sont traduites (en utilisant QObject::tr()) dans le contexte de la « QMenuBar ». Si une entrée est déplacée, ses slots seront toujours activés comme si elle était à son emplacement d?origine. Le tableau ci-dessous résume les chaînes de caractères recherchées et l?endroit où l?entrée sera placée si une correspondance est trouvée :

On peut redéfinir ce comportement en utilisant la propriété QAction::menuRole().

Pour que toutes les fenêtres d?une application Mac partagent la même barre de menu, il faut créer une barre de menu sans parent. On peut créer une barre de menu sans parent de cette manière :

 QMenuBar *menuBar = new QMenuBar(0);

À noter : on ne doit pas appeler QMainWindow::menuBar() pour créer une barre de menu partagée, car cette barre de menu aurait le QMainWindow comme parent, et ne serait affichée que pour ce parent QMainWindow.

À noter : le texte utilisé pour le nom de l?application dans la barre de menu est obtenu à partir de la valeur définie dans le fichier Info.plist dans le bundle de l?application. Voir Déploiement d?une application sous Mac OS X pour plus d?informations.

QMenuBar sous Windows CE

QMenuBar sous Windows CE est un adaptateur (wrapper) pour utiliser la barre de menu globale, de la même manière que sous Mac. Cette fonctionnalité est activée pour Windows Mobile et intègre QMenuBar avec les touches programmables natives. La touche programmable gauche peut être contrôlée avec QMenuBar::setDefaultAction() et la touche programmable droite peut être utilisée pour accéder à la barre de menu.

Le signal hovered() n?est pas pris en charge par l?intégration du menu natif. Il n?est pas non plus possible d?afficher une icône dans un menu natif sous Windows Mobile.

Exemples

L'exemple Menus montre comment utiliser QMenuBar et QMenu. Les autres exemples d'applications avec fenêtre principale contiennent aussi des menus utilisant ces classes.

Voir aussi QMenu, QShortcut, QAction, Introduction to Apple Human Interface Guidelines, GUI Design Handbook: Menu Bar et Exemple de menus.

Propriétés

defaultUp : bool

Cette propriété contient l'orientation de déroulement.

Par défaut, les menus vont se dérouler vers le bas de l'écran. En définissant cette propriété à true, les menus vont se dérouler vers le haut. Cette orientation alternative peut être intéressante pour les menus situés en bas du document auquel ils se réfèrent.

Si le menu ne peut pas être entièrement affiché dans l'écran, l'autre direction est utilisée automatiquement.

Fonction d'accès

bool isDefaultUp () const

void setDefaultUp ( bool )

nativeMenuBar : bool

Cette propriété définit si une barre de menu sera utilisée en tant que barre de menu native sur les plateformes qui la prennent en charge.

Les plateformes qui la prennent actuellement en charge sont Mac OS X et Windows CE. Sur ces plateformes, si cette propriété est à true, la barre de menu sera utilisée dans la barre de menu native et n?apparaîtra pas dans la fenêtre de son parent ; si elle est à false, la barre de menu reste dans la fenêtre. Sur les autres plateformes la valeur de cet attribut n?a aucun effet.

La valeur par défaut est déterminée en fonction de la valeur de l?attribut Qt::AA_DontUseNativeMenuBar. La définition explicite de cette propriété est prioritaire sur la présence (ou l?absence) de l?attribut.

Cette classe a été introduite dans Qt 4.6.

Fonction d'accès

bool isNativeMenuBar () const

void setNativeMenuBar ( bool nativeMenuBar )

Fonctions membres

QMenuBar::QMenuBar ( QWidget * parent = 0 )

Construit une barre de menu avec le parent parent.

QMenuBar::~QMenuBar ()

Détruit la barre de menu.

QAction * QMenuBar::actionAt ( const QPoint & pt ) const

Retourne la QAction au point pt. Retourne 0 s'il n'y a pas d'action au point pt ou si la position est celle d'un séparateur.

Voir aussi addAction() et addSeparator().

void QMenuBar::actionEvent ( QActionEvent * e ) [virtual protected]

Réimplémentation de QWidget::actionEvent().

QRect QMenuBar::actionGeometry ( QAction * act ) const

Retourne la géométrie de l'action act sous forme d'un QRect.

Voir aussi actionAt().

QAction * QMenuBar::activeAction () const

Retourne l'action actuellement sélectionnée (affichée en surbrillance). Un pointeur nul sera retourné si aucune action n'est actuellement sélectionnée.

Voir aussi setActiveAction().

QAction * QMenuBar::addAction ( const QString & text )

Il s'agit d'une fonction surchargée.

Cette fonction de commodité crée une nouvelle action avec le texte text. La fonction ajoute l'action nouvellement créée à la liste d'actions du menu et la retourne.

Voir aussi QWidget::addAction() et QWidget::actions().

QAction * QMenuBar::addAction ( const QString & text, const QObject * receiver, const char * member )

Il s'agit d'une fonction surchargée.

Cette fonction de commodité crée une nouvelle action avec le texte text. Le signal triggered() de l'action est connecté au slot membre member du receveur receiver. La fonction ajoute l'action nouvellement créée à la liste d'actions du menu et la retourne.

Voir aussi QWidget::addAction() et QWidget::actions().

void QMenuBar::addAction ( QAction * action )

Il s'agit d'une fonction surchargée.

Ajoute l'action action à la fin de la liste d'actions du menu.

Voir aussi QMenu::addAction(), QWidget::addAction() et QWidget::actions().

QAction * QMenuBar::addMenu ( QMenu * menu )

Ajoute le menu à la barre de menu. Retourne l'action menuAction() du menu.

À noter : l'objet QAction retourné peut être utilisé pour masquer le menu correspondant.

Voir aussi QWidget::addAction() et QMenu::menuAction().

QMenu * QMenuBar::addMenu ( const QString & title )

Ajoute un nouveau QMenu avec le titre title à la barre de menu. La barre de menu devient propriétaire du menu. Retourne le nouveau menu.

Voir aussi QWidget::addAction() et QMenu::menuAction().

QMenu * QMenuBar::addMenu ( const QIcon & icon, const QString & title )

Ajoute un nouveau QMenu avec l'icône icon et le titre title à la barre de menu. La barre de menu devient propriétaire du menu. Retourne le nouveau menu.

Voir aussi QWidget::addAction() et QMenu::menuAction().

QAction * QMenuBar::addSeparator ()

Ajoute un séparateur au menu.

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

Réimplémentation de QWidget::changeEvent().

void QMenuBar::clear ()

Supprime toutes les actions de la barre de menu.

À noter : sous Mac OS X, 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. Une manière de le faire est de supprimer les actions supplémentaires soi-même. On peut définir le rôle de menu pour les différents menus, de façon à savoir par avance quels éléments de menu ont été fusionnés, puis de décider lesquels doivent être recréés ou supprimés.

Voir aussi removeAction().

QWidget * QMenuBar::cornerWidget ( Qt::Corner corner = Qt::TopRightCorner ) const

Retourne le widget à gauche du premier élément de menu, ou à droite du dernier élément de menu, en fonction du coin corner.

À noter : utiliser un coin autre que Qt::TopRightCorner ou Qt::TopLeftCorner entrainera un avertissement.

Voir aussi setCornerWidget().

QAction * QMenuBar::defaultAction () const

Retourne l'action par défaut courante.

Cette fonction a été introduite dans Qt 4.4.

Voir aussi setDefaultAction().

bool QMenuBar::event ( QEvent * e ) [virtual protected]

Réimplémentation de QObject::event().

bool QMenuBar::eventFilter ( QObject * object, QEvent * event ) [virtual protected]

Réimplémentation de QObject::eventFilter().

void QMenuBar::focusInEvent ( QFocusEvent * ) [virtual protected]

Réimplémentation de QWidget::focusInEvent().

void QMenuBar::focusOutEvent ( QFocusEvent * ) [virtual protected]

Réimplémentation de QWidget::focusOutEvent().

int QMenuBar::heightForWidth ( int ) const [virtual]

Réimplémentation de QWidget::heightForWidth().

void QMenuBar::hovered ( QAction * action ) [signal]

Ce signal est émis lorsqu'une action de menu passe en surbrillance ; action est l'action qui a provoqué cet événement.

Ce signal est souvent utilisé pour mettre à jour l'information de la barre d'état.

Voir aussi triggered() et QAction::hovered().

void QMenuBar::initStyleOption ( QStyleOptionMenuItem * option, const QAction * action ) const [protected]

Initialise l'option option avec les valeurs de la barre de menu et les informations de l'action action. Cette méthode est utile pour les sous-classes qui ont besoin d'un QStyleOptionMenuItem mais qui ne veulent pas renseigner toutes les informations par elles-mêmes.

Voir aussi QStyleOption::initFrom() et QMenu::initStyleOption().

QAction * QMenuBar::insertMenu ( QAction * before, QMenu * menu )

Cette fonction de commodité insère le menu avant l'action before et retourne l'action menuAction() du menu.

Voir aussi QWidget::insertAction() et addMenu().

QAction * QMenuBar::insertSeparator ( QAction * before )

Cette fonction de commodité crée une nouvelle action séparateur, c'est-à-dire une action avec QAction::isSeparator() fixé à true. La fonction insère l'action nouvellement créée dans la liste des actions de la barre de menu avant l'action before et la retourne.

Voir aussi QWidget::insertAction() et addSeparator().

void QMenuBar::keyPressEvent ( QKeyEvent * e ) [virtual protected]

Réimplémentation de QWidget::keyPressEvent().

void QMenuBar::leaveEvent ( QEvent * ) [virtual protected]

Réimplémentation de QWidget::leaveEvent().

QSize QMenuBar::minimumSizeHint () const [virtual]

Réimplémentation de QWidget::minimumSizeHint().

void QMenuBar::mouseMoveEvent ( QMouseEvent * e ) [virtual protected]

Réimplémentation de QWidget::mouseMoveEvent().

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

Réimplémentation de QWidget::mousePressEvent().

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

Réimplémentation de QWidget::mouseReleaseEvent().

void QMenuBar::paintEvent ( QPaintEvent * e ) [virtual protected]

Réimplémentation de QWidget::paintEvent().

void QMenuBar::resizeEvent ( QResizeEvent * ) [virtual protected]

Réimplémentation de QWidget::resizeEvent().

void QMenuBar::setActiveAction ( QAction * act )

Définit l'action act comme étant l'action en surbrillance courante.

Cette fonction a été introduite dans Qt 4.1.

Voir aussi activeAction().

void QMenuBar::setCornerWidget ( QWidget * widget, Qt::Corner corner = Qt::TopRightCorner )

Cette fonction rend le widget donné directement visible à la gauche du premier élément de menu, ou à la droite du dernier élément de menu, en fonction du coin corner.

La barre de menu devient propriétaire du widget, en modifiant son parent. Toutefois, si le coin corner possède déjà un widget, ce précédent widget ne sera plus géré et sera toujours un enfant visible de la barre de menu.

À noter : utiliser un coin autre que Qt::TopRightCorner ou Qt::TopLeftCorner entrainera un avertissement.

Voir aussi cornerWidget().

void QMenuBar::setDefaultAction ( QAction * act )

Définit act comme étant l'action par défaut.

L'action par défaut est affectée à la touche programmable gauche. Le menu est affecté à la touche programmable droite.

Actuellement l'action par défaut n'est prise en charge que sous Windows Mobile. Sur toutes les autres plateformes cette méthode n'est pas disponible.

Cette fonction a été introduite dans Qt 4.4.

Voir aussi defaultAction().

void QMenuBar::setVisible ( bool visible ) [virtual slot]

Réimplémentation de QWidget::setVisible().

QSize QMenuBar::sizeHint () const [virtual]

Réimplémentation de QWidget::sizeHint().

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

Réimplémentation de QObject::timerEvent().

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

Ce signal est émis lorsqu'une action d'un menu appartenant à cette barre de menu est déclenchée à la suite d'un clic souris ; action est l'action qui a provoqué l'émission du signal.

Normalement, on connecte chaque action de menu à un slot unique en utilisant QAction::triggered(), mais on souhaite parfois se connecter plusieurs fois au même signal (notamment lorsque l'utilisateur fait une sélection dans un tableau). Ce signal est utile dans de tels cas.

Voir aussi hovered() et QAction::triggered().

Remerciements

Merci à Lo?c Leguay pour la traduction, ainsi qu'à Ilya Diallo, David Taralla et Claude Leloup pour la relecture !