QMenu

La classe QMenu fournit un widget menu utilisable dans les barres de menu, les menus contextuels et autres menus popup. Plus d'informations...

#include <QMenu>

Voir la position dans l'arbre des classes.

H�ritage

H�rite de QWidget.

H�ritage

H�rit� par Q3PopupMenu.

Description d�taill�e

La classe QMenu fournit un widget menu utilisable dans les barres de menu, les menus contextuels et autres menus popup.

Un widget menu est un menu de s�lection. Il peut �tre soit un menu d�roulant dans une barre de menu, soit un menu contextuel ind�pendant. Les menus d�roulants sont affich�s par la barre de menu lorsque l?utilisateur clique sur l?�l�ment correspondant, ou appuie sur le raccourci clavier sp�cifi�. On utilise QMenuBar::addMenu() pour ins�rer un menu dans une barre de menu. Les menus contextuels sont g�n�ralement appel�s par certaines touches claviers ou par un clic droit. Ils peuvent �tre ex�cut�s soit de mani�re asynchrone avec popup(), soit synchrone avec exec(). Les menus peuvent �galement �tre appel�s en r�ponse � des appuis sur des boutons ; ils sont alors similaires � des menus contextuels � l?exception de la fa�on dont ils sont appel�s.

Un menu avec le style de widget Plastique	Un menu avec le style de widget Windows XP	Un menu avec le style de widget Macintosh.

Actions

Un menu est constitu� d?une liste d?�l�ments de type action. Les actions sont ajout�es avec les fonctions addAction(), addActions() et insertAction(). Une action est repr�sent�e verticalement, et est rendue par un QStyle. De plus, les actions peuvent avoir un libell� textuel, une ic�ne facultative dessin�e dans sa partie gauche, et une combinaison de touches de raccourcis, par exemple « Ctrl+X ».

Les actions existantes contenues dans un menu peuvent �tre retrouv�es avec la fonction actions().

Il existe quatre types d?�l�ments action : les s�parateurs, les actions qui affichent un sous-menu, les widgets, et les actions qui accomplissent une action. Les s�parateurs sont ins�r�s avec addSeparator(), les sous-menus avec addMenu(), et tous les autres �l�ments sont consid�r�s comme des �l�ments action.

Lors de l?insertion d?un �l�ment action, on sp�cifie g�n�ralement un r�cepteur et un slot. Le r�cepteur sera notifi� � chaque fois que l?�l�ment sera d�clench� (triggered()). De plus, QMenu fournit deux signaux, activated() et highlighted(), qui indiquent quel objet QAction a �t� d�clench� depuis le menu.

On vide un menu avec clear() et on enl�ve les �l�ments action avec removeAction().

Un QMenu fournit �galement un menu d�tachable. Un menu d�tachable est une fen�tre de haut niveau qui contient une copie du menu. Cela permet � l?utilisateur de « d�tacher » les menus fr�quemment utilis�s et de les positionner dans un endroit pratique sur l?�cran. Si on souhaite appliquer cette fonctionnalit� � un menu particulier, on ins�re un gestionnaire de d�tachement avec setTearOffEnabled(). Lorsqu?on utilise les menus d�tachables, il faut garder � l?esprit que le concept n?est pas r�pandu sous Microsoft Windows, et que certains utilisateurs peuvent ne pas y �tre habitu�s. On peut envisager d?utiliser une barre d?outils QToolBar � la place.

Les widgets peuvent �tre ins�r�s dans les menus � l?aide de la classe QWidgetAction. Les instances de cette classe sont utilis�es pour contenir les widgets et sont ins�r�es dans les menus avec la fonction surcharg�e addAction() prenant en param�tre un QAction.

Inversement, les actions peuvent �tre ajout�es aux widgets avec les fonctions addAction(), addActions() et insertAction().

Attention : pour rendre un QMenu visible � l?�cran, il faut utiliser exec() ou popup() � la place de show().

QMenu sous Qt pour Windows CE

Si un menu est int�gr� dans la barre de menu native de Windows Mobile, les signaux suivants ne sont pas pris en charge : aboutToHide(), aboutToShow() et hovered(). Il n'est pas possible d'afficher une ic�ne dans un menu natif de Windows Mobile.

QMenu sous Mac OS X avec Qt construit sous Cocoa

Un QMenu ne peut �tre ins�r� qu'une seule fois dans un menu ou une barre de menu. Les insertions suivantes n'auront pas d'effet, ou aboutiront � un �l�ment de menu d�sactiv�.

Voir l'exemple Menus pour un exemple d?utilisation de QMenuBar et QMenu dans une application.

Fonctions h�rit�es importantes : addAction(), removeAction(), clear(), addSeparator() et addMenu().

Voir aussi QMenuBar, Manuel de conception d'IHM : Menu d�roulant et popup, Exemple d'application, Exemple de menus et Exemple de fichiers r�cents.

Propri�t�s

icon : QIcon

Cette propri�t� contient l?ic�ne du menu.

Elle est �quivalente � la propri�t� QAction::icon de menuAction().

Par d�faut, si aucune ic�ne n'est explicitement d�finie, cette propri�t� contient une ic�ne nulle.

Fonction d'acc�s

QIcon icon () const

void setIcon ( const QIcon & icon )

separatorsCollapsible : bool

Cette propri�t� indique si les s�parateurs cons�cutifs du menu doivent �tre visuellement fusionn�s en un seul. Les s�parateurs au d�but et � la fin du menu sont aussi cach�s.

Par d�faut, cette propri�t� est � true.

Cette classe a �t� introduite dans Qt 4.2.

Fonction d'acc�s

bool separatorsCollapsible () const

void setSeparatorsCollapsible ( bool collapse )

tearOffEnabled : bool

Cette propri�t� indique si le menu peut �tre d�tach�.

Si cette propri�t� est � true, le menu contient un �l�ment sp�cial de d�tachement (souvent affich� sous la forme d'une ligne pointill�e en haut du menu) qui cr�e une copie du menu lorsqu'il est d�clench�.

Cette copie de « d�tachement » existe dans une fen�tre s�par�e. Elle contient les m�mes �l�ments menu que le menu original, � l'exception du gestionnaire de d�tachement.

Par d�faut, cette propri�t� est � false.

Fonction d'acc�s

bool isTearOffEnabled () const

void setTearOffEnabled ( bool )

title : QString

Cette propri�t� contient le titre du menu.

Elle est �quivalente � la propri�t� QAction::text de menuAction().

Par d�faut, cette propri�t� contient une cha�ne de caract�res vide.

Fonction d'acc�s

QString title () const

void setTitle ( const QString & title )

Fonctions membres

QMenu::QMenu ( QWidget * parent = 0 )

Construit un menu avec le parent parent.

Bien qu'un menu popup soit toujours un widget de premier niveau, si un parent est fourni en argument, le menu popup sera supprim� lorsque le parent sera d�truit (de la m�me fa�on que tous les autres QObject).

QMenu::QMenu ( const QString & title, QWidget * parent = 0 )

Construit un menu avec le titre title et le parent parent.

Bien qu?un menu popup soit toujours un widget de premier niveau, si un parent est fourni en argument, le menu popup sera supprim� lorsque le parent sera d�truit (de la m�me fa�on que tous les autres QObject).

Voir aussi title.

QMenu::~QMenu ()

D�truit le menu.

void QMenu::aboutToHide () [signal]

Ce signal est �mis juste avant que le menu ne soit cach� � l'utilisateur.

Cette fonction a �t� introduite dans Qt 4.2.

Voir aussi aboutToShow() et hide().

void QMenu::aboutToShow () [signal]

Ce signal est �mis juste avant que le menu ne soit affich� � l'utilisateur.

Voir aussi aboutToHide() et show().

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

Retourne l'�l�ment au point pt ; retourne 0 si il n'y a pas d'�l�ment � cet endroit.

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

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

QRect QMenu::actionGeometry ( QAction * act ) const

Retourne la g�om�trie de l'action act.

QAction * QMenu::activeAction () const

Retourne l'action actuellement active (en surbrillance), ou 0 si aucune action n'est actuellement active.

Voir aussi setActiveAction().

QAction * QMenu::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. Cette fonction ajoute l'action nouvellement cr��e � la liste des actions du menu, et la retourne.

Voir aussi QWidget::addAction().

QAction * QMenu::addAction ( const QIcon & icon, const QString & text )

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

Cette fonction de commodit� cr�e une nouvelle action avec l'ic�ne icon et le texte text. Cette fonction ajoute l?action nouvellement cr��e � la liste des actions du menu, et la retourne.

Voir aussi QWidget::addAction().

QAction * QMenu::addAction ( const QString & text, const QObject * receiver, const char * member, const QKeySequence & shortcut = 0 )

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

Cette fonction de commodit� cr�e une nouvelle action avec le texte text et un raccourci clavier facultatif shortcut. Le signal triggered() de l'action est connect� au slot membre member du r�cepteur receiver. Cette fonction ajoute l?action nouvellement cr��e � la liste des actions du menu, et la retourne.

Voir aussi QWidget::addAction().

QAction * QMenu::addAction ( const QIcon & icon, const QString & text, const QObject * receiver, const char * member, const QKeySequence & shortcut = 0 )

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

Cette fonction de commodit� cr�e une nouvelle action avec l'ic�ne icon, le texte text et un raccourci facultatif shortcut. Le signal triggered() de l?action est connect� au slot membre member du r�cepteur receiver. Cette fonction ajoute l?action nouvellement cr��e � la liste des actions du menu, et la retourne.

Voir aussi QWidget::addAction().

void QMenu::addAction ( QAction * action )

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

Ajoute l'action action � la fin de la liste des actions du menu.

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

QAction * QMenu::addMenu ( QMenu * menu )

Cette fonction de commodit� ajoute le menu en tant que sous-menu de ce menu. Elle retourne l'action menuAction() du menu. Ce menu ne devient pas propri�taire de menu.

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

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

Ajoute un nouveau QMenu avec le titre title au menu. Le menu devient propri�taire du menu. Retourne le nouveau menu.

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

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

Ajoute un nouveau QMenu avec l'ic�ne icon et le titre title au menu. Le menu devient propri�taire du menu. Retourne le nouveau menu.

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

QAction * QMenu::addSeparator ()

Cette fonction de commodit� cr�e une nouvelle action de type s�parateur, c'est-�-dire une action dont la fonction QAction::isSeparator() retourne true, et ajoute cette nouvelle action � la liste des actions du menu. L'action nouvellement cr��e est retourn�e.

Voir aussi QWidget::addAction().

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

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

void QMenu::clear ()

Supprime toutes les actions du menu. Les actions dont le menu est propri�taire et qui ne sont affich�es par aucun autre widget sont d�truites.

Voir aussi removeAction().

int QMenu::columnCount () const [protected]

Si un menu d�borde de l'�cran dans sa disposition par d�faut (sur une colonne), il modifie sa disposition afin de rester dans les limites de l'�cran. La disposition est d�pendante du style (par exemple, sous Windows, le menu va s'�taler sur plusieurs colonnes).

Cette fonction retourne le nombre de colonnes n�cessaires.

QAction * QMenu::defaultAction () const

Retourne l'action par d�faut actuelle.

Voir aussi setDefaultAction().

void QMenu::enterEvent ( QEvent * ) [virtual protected]

R�impl�mentation de QWidget::enterEvent().

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

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

QAction * QMenu::exec ()

Ex�cute ce menu de mani�re synchrone.

Cette fonction est �quivalente � exec(pos()).

Elle retourne la QAction d�clench�e dans le menu popup ou un des ses sous-menus, ou 0 si aucun �l�ment n?a �t� d�clench� (g�n�ralement lorsque l?utilisateur appuie sur la touche Echap).

Dans la plupart des situations, on souhaite sp�cifier soi-m�me la position, par exemple la position actuelle de la souris :

 exec(QCursor::pos());

ou align�e avec un widget :

 exec(somewidget.mapToGlobal(QPoint(0,0)));

ou en r�action � un �v�nement QMouseEvent *e :

 exec(e->globalPos());

QAction * QMenu::exec ( const QPoint & p, QAction * action = 0 )

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

Ex�cute ce menu de mani�re synchrone.

Cr�e un menu popup de telle sorte que l?action action soit situ�e � la position absolue p. La fonction QWidget::mapToGlobal() permet de convertir les coordonn�es locales d'un widget en coordonn�es absolues.

Elle retourne la QAction d�clench�e dans le menu popup ou un des ses sous-menus, ou 0 si aucun �l�ment n?a �t� d�clench� (g�n�ralement lorsque l?utilisateur appuie sur la touche Echap).

� noter que tous les signaux sont �mis normalement. Si on connecte une QAction � un slot et qu?on appelle la fonction exec() du menu, on obtiendra le r�sultat � la fois via la connexion signal-slot et via la valeur retourn�e par exec().

En g�n�ral, on positionne le menu � la position actuelle de la souris :

 exec(QCursor::pos());

ou align� avec un widget :

 exec(somewidget.mapToGlobal(QPoint(0, 0)));

ou en r�action � un �v�nement QMouseEvent *e :

 exec(e->globalPos());

Lorsqu?on positionne un menu avec exec() ou popup(), il faut garder en t�te que la taille size() du menu actuel peut �tre amen�e � changer. Pour des raisons de performances, le menu adapte sa taille uniquement lorsque c?est n�cessaire. Ainsi, dans la plupart des cas, la taille avant et apr�s l?affichage sont diff�rentes. Il faut mieux utiliser la fonction sizeHint() qui calcule la taille adapt�e en fonction du contenu du menu.

Voir aussi popup() et QWidget::mapToGlobal().

QAction * QMenu::exec ( QList<QAction *> actions, const QPoint & pos, QAction * at, QWidget * parent ) [static]

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

Ex�cute le menu de mani�re synchrone.

Les actions du menu sont sp�cifi�es par la liste des actions. Le menu popup va appara�tre de telle sorte que l?action sp�cifi�e at, apparaisse � la position absolue pos. Si l'action at n?est pas sp�cifi�e alors le menu appara�tra � la position pos. parent est le widget parent du menu ; sp�cifier le parent permet de fournir un contexte suppl�mentaire lorsque pos n?est pas suffisante pour d�terminer la position du menu (par exemple lorsqu?il y a plusieurs bureaux ou lorsque le parent est int�gr� dans une vue QGraphicsView).

Elle retourne la QAction d�clench�e dans le menu popup ou un des ses sous-menus, ou 0 si aucun �l�ment n?a �t� d�clench� (g�n�ralement lorsque l?utilisateur appuie sur la touche Echap ).

Elle est �quivalente � :

 QMenu menu;
 QAction *at = actions[0]; // Suppose que l?action n?est pas vide
 foreach (QAction *a, actions)
     menu.addAction(a);
 menu.exec(pos, at);

Voir aussi popup() et QWidget::mapToGlobal().

QAction * QMenu::exec ( QList<QAction *> actions, const QPoint & pos, QAction * at = 0 ) [static]

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

Ex�cute le menu de mani�re synchrone.

Les actions du menu sont sp�cifi�es par la liste des actions. Le menu popup va appara�tre de telle sorte que l?action sp�cifi�e at apparaisse � la position absolue pos. Si l'action at n?est pas sp�cifi�e alors le menu appara�tra � la position pos.

Elle retourne la QAction d�clench�e dans le menu popup ou un des ses sous-menus, ou 0 si aucun �l�ment n?a �t� d�clench� (g�n�ralement lorsque l?utilisateur appuie sur la touche Echap).

Elle est �quivalente � :

 QMenu menu;
 QAction *at = actions[0]; // Suppose que l?action n?est pas vide
 foreach (QAction *a, actions)
     menu.addAction(a);
 menu.exec(pos, at);

Voir aussi popup() et QWidget::mapToGlobal().

bool QMenu::focusNextPrevChild ( bool next ) [virtual protected]

R�impl�mentation de QWidget::focusNextPrevChild().

void QMenu::hideEvent ( QHideEvent * ) [virtual protected]

R�impl�mentation de QWidget::hideEvent().

void QMenu::hideTearOffMenu ()

Cette fonction force le masquage du menu d�tachable, le faisant disparaitre du bureau de l'utilisateur.

Voir aussi isTearOffMenuVisible() et isTearOffEnabled().

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

Ce signal est �mis lorsqu'une action de menu passe en surbrillance ; action est l'action qui a provoqu� l'�mission du signal.

Il est souvent utilis� pour mettre � jour l'information de la barre d'�tat.

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

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

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

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

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

Cette fonction de commodit� ins�re le menu avant l'action before, et retourne les actions menuAction() du menu.

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

QAction * QMenu::insertSeparator ( QAction * before )

Cette fonction de commodit� cr�e une nouvelle action de type s�parateur, c?est-�-dire une action dont la fonction QAction::isSeparator() retourne true. L'action nouvellement cr��e est ins�r�e dans la liste des actions du menu avant l'action before, puis est retourn�e.

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

bool QMenu::isEmpty () const

Retourne true si le menu ne poss�de aucune action visible, sinon retourne false.

Cette fonction a �t� introduite dans Qt 4.2.

Voir aussi QWidget::actions().

bool QMenu::isTearOffMenuVisible () const

Lorsqu'un menu est d�tach�, un deuxi�me menu appara�t pour afficher le contenu du menu dans une nouvelle fen�tre. Cette fonction retourne true lorsque le menu est dans ce mode et qu'il est visible ; sinon elle retourne false.

Voir aussi hideTearOffMenu() et isTearOffEnabled().

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

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

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

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

QAction * QMenu::menuAction () const

Retourne l'action associ�e � ce menu.

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

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

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

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

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

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

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

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

void QMenu::popup ( const QPoint & p, QAction * atAction = 0 )

Affiche le menu de telle sorte que l?action atAction soit situ�e � la position absolue p. La fonction QWidget::mapToGlobal() permet de convertir les coordonn�es locales d'un widget en coordonn�es absolues.

Lorsqu?on positionne un menu avec exec() ou popup(), il faut garder en t�te que la valeur courante de size() de ce menu peut ne pas �tre correcte. Pour des raisons de performances, le menu adapte sa taille uniquement lorsque c?est n�cessaire. Ainsi, dans la plupart des cas, la taille avant et apr�s l?affichage sont diff�rentes. Il vaut mieux utiliser la fonction sizeHint() qui calcule la taille adapt�e en fonction du contenu du menu.

Voir aussi QWidget::mapToGlobal() et exec().

void QMenu::setActiveAction ( QAction * act )

D�finit l'action act comme �tant l'action actuellement en surbrillance.

Voir aussi activeAction().

void QMenu::setDefaultAction ( QAction * act )

D�finit l'action act comme �tant l'action par d�faut. L'action par d�faut peut avoir un indice visuel, en fonction du style QStyle courant. Une action par d�faut indique g�n�ralement ce qu'il se produira par d�faut lorsqu'une d�pose sera effectu�e.

Voir aussi defaultAction().

QSize QMenu::sizeHint () const [virtual]

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

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

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

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

Ce signal est �mis lorsqu?une action de menu est d�clench�e.

action est l?action qui a provoqu� l?�mission du signal.

En g�n�ral, on connecte chaque signal triggered() d?action du menu � son propre slot personnalis�, mais il est parfois utile de connecter plusieurs actions � un m�me signal, par exemple dans le cas d?un groupe d?actions �troitement li�es, telles que « justifi� � gauche », « centr� », « justifi� � droite »

� noter : ce signal est �mis pour le parent principal de la hi�rarchie. Ainsi, seul le menu du parent a besoin d?�tre connect� � un slot ; les sous-menus n?ont pas besoin d?�tre connect�s.

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

void QMenu::wheelEvent ( QWheelEvent * e ) [virtual protected]

R�impl�mentation de QWidget::wheelEvent().

Remerciements

Merci � Lo?c Leguay pour la traduction, ainsi qu'� Ilya Diallo, Dimitry Ernot et Claude Leloup pour la relecture !