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 !