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 !