QAction

La classe QAction fournit une action d'interface utilisateur abstraite pouvant être insérée dans les widgets. Plus d'informations...

 #include <QAction>

Héritage

Hérite de QObject.

Héritage

Hérité par QMenuItem et QWidgetAction.

Description détaillée

La classe QAction fournit une action d'interface utilisateur abstraite pouvant être insérée dans les widgets.

Dans les applications, de nombreuses commandes courantes peuvent être appelées à partir de menus, de barres d'outils et de raccourcis clavier. Comme l'utilisateur s'attend à ce que chaque commande soit effectuée de la même façon, indépendamment de l'interface utilisateur utilisée, il est utile de représenter chaque commande par une action.

Les actions peuvent être ajoutées aux menus et barres d'outils et seront automatiquement synchronisées. Par exemple, dans un éditeur de texte, si l'utilisateur appuie sur le bouton de Gras, l'élément du menu Gras sera automatiquement coché.

Les actions peuvent être créées comme objets indépendants mais elles peuvent aussi être créées pendant la construction des menus ; la classe QMenu contient des fonctions de commodité pour la création d'actions utilisables comme des éléments du menu.

Une QAction peut aussi contenir une icône, un texte de menu, un raccourci, un texte d'état, un texte « Qu'est ce que c'est ? » et une bulle d'information. La plupart de ces contenus peuvent être définis à partir du constructeur. Ils peuvent aussi être définis indépendamment avec les fonctions setIcon(), setText(), setIconText(), setShortcut(), setStatusTip(), setWhatsThis() et setToolTip(). Pour les éléments de menu, il est possible de définir une police de caractères avec setFont().

Les actions sont ajoutées aux widgets avec les fonctions QWidget::addAction() ou QGraphicsWidget::addAction(). Notez qu'une action doit d'abord être ajoutée à un widget avant de pouvoir être utilisée ; ceci reste vrai lorsque le raccourci est global (c'est-à-dire Qt::ApplicationShortcut valant Qt::ShortcutContext).

Une fois qu'une QAction a été créée, elle doit être ajoutée au menu ou à la boite d'outils appropriée, puis connectée au slot qui effectuera l'action. Par exemple :

     openAct = new QAction(QIcon(":/images/open.png"), tr("&Open..."), this);
     openAct->setShortcuts(QKeySequence::Open);
     openAct->setStatusTip(tr("Open an existing file"));
     connect(openAct, SIGNAL(triggered()), this, SLOT(open()));
 
     fileMenu->addAction(openAct);
     fileToolBar->addAction(openAct);

Nous recommandons de créer les actions comme enfants de la fenêtre où elles seront utilisées. Dans la plupart des cas, les actions sont des enfants de la fenêtre principale de l'application.

Voir aussi QMenu, QToolBar et Application Example.

Type

enum QAction::ActionEvent

Cette énumération est utilisée lors de l'appel à la fonction QAction::activate().

enum QAction::MenuRole

Cette énumération décrit la façon dont l'action doit être placée dans le menu de l'application sur Mac OS X.

La définition de cette valeur n'a d'effet que sur les éléments dans les menus immédiats de la barre de menu, et non sur les sous-menus de ces menus. Par exemple, si vous avez un menu « Fichier » dans votre barre de menus et que ce menu a un sous-menu, la définition du rôle pour les actions du sous-menu n'aura pas d'effet. Elles ne seront jamais déplacées.

enum QAction::Priority

Cette énumération définit la priorité des actions dans l'interface utilisateur.

Cette énumération a été introduite ou modifiée dans Qt 4.6.

Voir aussi priority.

enum QAction::SoftKeyRole

Cette énumération décrit la façon dont les actions doivent être placées dans la barre de touches programmables. Actuellement, cette énumération n'affecte que la plate-forme Symbian.

Les actions ayant un rôle de touche programmable défini ne sont visibles dans la barre des touches programmables que lorsque le widget contenant l'action possède le focus. Si aucun widget n'a le focus, le framework de touches programmables remontera la hiérarchie des widgets parents pour trouver un widget contenant des actions de touches programmables.

Cette énumération a été introduite ou modifiée dans Qt 4.6.

Propriétés

autoRepeat : bool

Cette propriété spécifie si l'action peut s'autorépéter.

Si true, l'action s'autorépétera lorsque le raccourci clavier est maintenu appuyé et si la répétition du clavier est activée sur le système. Par défaut, la propriété est à true.

Cette classe a été introduite dans Qt 4.2.

Fonction d'accès

bool autoRepeat () const

void setAutoRepeat ( bool )

Signal de notification :

void changed ()

checkable : bool

Cette propriété indique si l'action est cochable.

Une action cochable (ou bascule) est une action ayant un état oui/non. Par exemple, dans un éditeur de texte, un bouton de « Gras » peut être enclenché ou non. Une action qui n'est pas cochable est une action de commande ; une action de commande est simplement exécutée, par exemple : « Sauvegarder le fichier ». Par défaut cette propriété est false.

Dans certaines situations, l'état de l'action cochable dépend de l?état d'autres actions. Par exemple, les bascules « Aligner à gauche », « Centrer » et « Aligner à droite » sont mutuellement exclusives. Pour créer des bascules exclusives, ajouter les actions concernées dans un QActionGroup avec la propriété QActionGroup::exclusive définie à true.

Fonction d'accès

bool isCheckable () const

void setCheckable ( bool )

Signal de notification :

void changed ()

Voir aussi QAction::setChecked().

checked : bool

Cette propriété spécifie si l'action est cochée.

Seules les actions cochables peuvent être cochées. Par défaut, cette propriété est false (l'action n'est pas cochée).

Fonction d'accès

bool isChecked () const

void setChecked ( bool )

Signal de notification :

void toggled ( bool checked )

Voir aussi checkable.

enabled : bool

Cette propriété spécifie si l'action est activée.

Les actions désactivées ne peuvent pas être choisies par l'utilisateur. Elles ne disparaissent pas des menus mais sont affichées d'une façon qui indique qu'elles ne sont pas disponibles. Par exemple, elles peuvent être affichées en gris.

L'aide « Qu'est ce que c'est ? » reste disponible sur les actions désactivées, si la propriété QAction::whatsThis est définie.

Une action sera désactivée lorsque tous les widgets auxquels l'action a été ajoutée (à l'aide de la fonction QWidget::addAction()) sont désactivés ou invisibles. Lorsque l'action est désactivée, il n'est pas possible de la déclencher par son raccourci.

Par défaut, cette propriété est définie à true (l'action est activée).

Fonction d'accès

bool isEnabled () const

void setEnabled ( bool )

Signal de notification :

void changed ()

Voir aussi text.

font : QFont

Cette propriété contient la fonte de l'action.

La fonte est utilisée lors de l'affichage du texte défini pour la QAction. La fonte sera considérée comme une préférence car elle ne sera pas toujours utilisée selon l'application et les styles.

Par défaut, cette propriété contient la fonte par défaut de l'application.

Fonction d'accès

QFont font () const

void setFont ( const QFont & font )

Signal de notification :

void changed ()

Voir aussi QAction::setText() et QStyle.

icon : QIcon

Cette propriété contient l?icône de l'action.

Dans les barres d'outils, l?icône est utilisée comme icône du bouton ; dans les menus, l?icône est affichée à gauche du texte du menu. Il n'y a pas d?icône par défaut.

Sur Symbian, les icônes qui sont passées aux touches programmables, c'est-à-dire aux actions avec un rôle de touche programmable, ont besoin d'une définition correcte du canal alpha de la pixmap, sinon des artefacts apparaîtront lors du dessin lorsque la touche programmable est appuyée.

Si une icône nulle (QIcon::isNull() est passée dans cette fonction, l?icône de la fonction est effacée.

Fonction d'accès

QIcon icon () const

void setIcon ( const QIcon & icon )

Signal de notification :

void changed ()

iconText : QString

Cette propriété contient la description textuelle de l?icône de l'action.

Si QToolBar::toolButtonStyle est défini à une valeur qui permet au texte d'être affiché, le texte défini dans cette propriété apparaît comme libellé dans le bouton de la barre d'outils correspondant.

La propriété est aussi utilisée comme texte par défaut dans les menus et bulles d'information si l'action n'a pas été définie avec setText() ou setToolTip() et sera aussi utilisée dans la barre d'outils si aucune icône n'a été définie par le biais de la fonction setIcon().

Si le texte n'est pas défini explicitement, le texte de l'action sera utilisé comme texte d?icône.

Par défaut, la propriété contient une chaîne de caractères vide.

Fonction d'accès

QString iconText () const

void setIconText ( const QString & text )

Signal de notification :

void changed ()

Voir aussi setToolTip() et setStatusTip().

iconVisibleInMenu : bool

Cette propriété spécifie si l'action doit afficher une icône dans un menu.

Dans certaines applications, il peut être logique d'avoir des actions avec des icônes dans la barre d'outils mais pas dans le menu. Si la propriété est true, l?icône (si elle est valide) est affichée dans le menu, si la propriété est false alors elle n'est pas affichée.

Le comportement par défaut dépend de l'attribut Qt::AA_DontShowIconsInMenus. La définition explicite de cette propriété est prioritaire sur la présence (ou l'absence) de l'attribut.

Par exemple :

 QApplication app(argc, argv);
 app.setAttribute(Qt::AA_DontShowIconsInMenus);  // Les icônes *ne sont pas affichées* dans les menus
 // ...
 QAction *myAction = new QAction();
 // ...
 myAction->setIcon(SomeIcon);
 myAction->setIconVisibleInMenu(true);   // l?icône *sera* affichée dans les menus pour *cette* action.

Cette classe a été introduite dans Qt 4.4.

Fonction d'accès

bool isIconVisibleInMenu () const

void setIconVisibleInMenu ( bool visible )

Signal de notification :

void changed ()

Voir aussi QAction::icon et QApplication::setAttribute().

menuRole : MenuRole

Cette propriété contient le rôle de menu de l'action.

La propriété indique quel rôle est attribué à l'action dans le menu d'application sur Mac OS X. Par défaut toutes actions ont le rôle TextHeuristicRole, qui signifie que l'action est ajoutée selon son texte (voir QMenuBar pour plus d'informations).

Le rôle de menu peut être changé uniquement avant que les actions soient placées dans la barre de menus de Mac OS X (normalement, juste avant que la première fenêtre de l'application soit affichée).

Cette classe a été introduite dans Qt 4.2.

Fonction d'accès

MenuRole menuRole () const

void setMenuRole ( MenuRole menuRole )

Signal de notification :

void changed ()

priority : Priority

Cette propriété contient la priorité de l'action dans l'interface utilisateur.

Cette propriété peut être définie pour indiquer la façon dont l'action sera priorisée dans l'interface utilisateur.

Par exemple, lorsque les barres d'outils ont le mode Qt::ToolButtonTextBesideIcon défini, alors pour les actions de priorité basse le libellé ne sera pas affiché.

Cette classe a été introduite dans Qt 4.6.

Fonction d'accès

Priority priority () const

void setPriority ( Priority priority )

shortcut : QKeySequence

Cette propriété contient le raccourci clavier principal.

Les codes de touches valides pour cette propriété se trouvent dans Qt::Key et Qt::Modifier. Il n'y a pas de raccourci clavier par défaut.

Fonction d'accès

QKeySequence shortcut () const

void setShortcut ( const QKeySequence & shortcut )

Signal de notification :

void changed ()

shortcutContext : Qt::ShortcutContext

Cette propriété contient le contexte pour le raccourci clavier de l'action.

Les valeurs valides pour cette propriété se trouvent dans Qt::ShortcutContext. La valeur par défaut est Qt::WindowShortcut.

Fonction d'accès

Qt::ShortcutContext shortcutContext () const

void setShortcutContext ( Qt::ShortcutContext context )

Signal de notification :

void changed ()

softKeyRole : SoftKeyRole

Cette propriété contient le rôle de touche programmable de l'action.

Cette propriété indique quel type de rôle cette action décrit dans le framework de touches programmables, pour les plates-formes gérant ce framework. Actuellement, il n'est géré que par les plates-formes Symbian.

Le rôle de touche programmable peut être modifié à tout moment.

Cette classe a été introduite dans Qt 4.6.

Fonction d'accès

SoftKeyRole softKeyRole () const

void setSoftKeyRole ( SoftKeyRole softKeyRole )

Signal de notification :

void changed ()

statusTip : QString

Cette propriété contient l'indicateur d'état de l'action.

L?indicateur d'état est affiché dans toutes les barres d'état fournies par le widget parent de premier niveau à l'action.

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

Fonction d'accès

QString statusTip () const

void setStatusTip ( const QString & statusTip )

Signal de notification :

void changed ()

Voir aussi setToolTip() et showStatusText().

text : QString

Cette propriété contient le texte descriptif de l'action.

Si l'action est ajoutée à un menu, l'élément consistera en l?icône (si présente), le texte et le raccourci (s'il y en a un). Si le texte n'est pas défini explicitement dans le constructeur ou en utilisant la fonction setText(), la description de l?icône de l'action sera utilisée comme texte. Il n'y a pas de texte par défaut.

Fonction d'accès

QString text () const

void setText ( const QString & text )

Signal de notification :

void changed ()

Voir aussi iconText.

toolTip : QString

Cette propriété contient le texte de l'infobulle (tooltip).

Ce texte est utilisé pour l'infobulle. Si rien n'est spécifié, c'est le texte de l'action qui sera utilisé.

Par défaut, cette propriété contient le texte de l'action.

Fonction d'accès

QString toolTip () const

void setToolTip ( const QString & tip )

Signal de notification :

void changed ()

Voir aussi setStatusTip() et setShortcut().

visible : bool

Cette propriété indique si l'action peut être vue (par exemple, dans les menus et les barres d'outils).

Si visible est true, l'action peut être vue (par exemple, dans les menus et les barres d'outils) et choisie par l'utilisateur ; si visible est false l'action ne peut pas être vue ni choisie par l'utilisateur.

Les actions qui ne sont pas visibles ne sont pas grisées ; elles n'apparaissent pas du tout.

Par défaut, la propriété est true (les actions sont visibles).

Fonction d'accès

bool isVisible () const

void setVisible ( bool )

Signal de notification :

void changed ()

whatsThis : QString

Cette propriété contient le texte d'aide « Qu'est-ce que c'est ? » de l'action.

Le texte « Qu'est-ce que c'est ? » est utilisé pour fournir une brève description de l'action. Le texte peut contenir du texte riche. Il n'y a pas de texte « Qu'est-ce que c'est ? » par défaut.

Fonction d'accès

QString whatsThis () const

void setWhatsThis ( const QString & what )

Signal de notification :

void changed ()

Voir aussi QWhatsThis et Q3StyleSheet.

Fonctions membres

QAction::QAction ( QObject * parent )

Construit une action avec pour parent parent. Si parent est un groupe d'actions, l'action sera automatiquement ajoutée au groupe.

QAction::QAction ( const QString & text, QObject * parent )

Construit une action ayant pour texte text et pour parent parent. Si parent est un groupe d'actions, l'action sera automatiquement ajoutée au groupe.

L'action utilise une version dépouillée du texte text (par exemple,  »&Option de menu... » devient « Option de menu ») comme texte descriptif pour les boutons d'outils. Vous pouvez le remplacer par une description spécifique avec la fonction setText(). Le même texte sera utilisé pour l'infobulle tant que vous ne spécifiez pas un texte différent avec la fonction setToolTip().

QAction::QAction ( const QIcon & icon, const QString & text, QObject * parent )

Construit une action avec une icône icon, un texte text et un parent parent. Si parent est un groupe d'actions, l'action sera automatiquement ajoutée au groupe.

L'action utilise une version dépouillée du texte text (par exemple,  »&Option de menu... » devient « Option de menu ») comme texte descriptif pour les boutons d'outils. Vous pouvez le remplacer par une description spécifique avec la fonction setText(). Le même texte sera utilisé pour l'infobulle tant que vous ne spécifiez pas un texte différent avec la fonction setToolTip().

QAction::~QAction ()

Détruit l'objet et libère les ressources allouées.

QActionGroup * QAction::actionGroup () const

Retourne le groupe d'actions pour cette action. Si aucun groupe d'actions ne contient cette action la fonction retourne 0.

Voir aussi QActionGroup et QAction::setActionGroup().

void QAction::activate ( ActionEvent event )

Envoie les signaux appropriés pour l?événement ActionEvent event.

Les widgets basés sur les actions utilisent cette fonction pour forcer la QAction à envoyer des signaux tout en émettant les leurs.

QList<QGraphicsWidget *> QAction::associatedGraphicsWidgets () const

Retourne une liste des widgets contenant cette action.

Cette fonction a été introduite dans Qt 4.5.

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

QList<QWidget *> QAction::associatedWidgets () const

Retourne une liste de widgets contenant cette action.

Cette fonction a été introduite dans Qt 4.2.

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

void QAction::changed () [signal]

Ce signal est envoyé lorsque l'action a changé. Si vous ne vous intéressez qu'aux actions d'un widget spécifique, vous pouvez regarder si QWidget::actionEvent() est appelé avec QEvent::ActionChanged.

Voir aussi QWidget::actionEvent().

QVariant QAction::data () const

Retourne les données utilisateurs définies dans QAction::setData.

Voir aussi setData().

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

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

void QAction::hover () [slot]

Ce slot est un slot de commodité qui appelle activate(Hover).

void QAction::hovered () [signal]

Ce signal est émis lorsque l'action est sélectionnée par l'utilisateur ; par exemple, lorsque l'utilisateur arrête le pointeur de la souris sur un élément de menu, un bouton de barre d'outils ou appuie sur le raccourci clavier de l'action.

Voir aussi QAction::activate().

bool QAction::isSeparator () const

Retourne true si cette action est une action de séparation ; sinon, retourne false.

Voir aussi QAction::setSeparator().

QMenu * QAction::menu () const

Retourne le menu contenu dans cette action. Les actions contenant des menus peuvent être utilisées pour créer des éléments de menu ayant des sous-menus, ou insérées dans les barres d'outils pour créer des boutons ayant des menus contextuels.

Voir aussi setMenu() et QMenu::addAction().

QWidget * QAction::parentWidget () const

Retourne le widget parent.

void QAction::setActionGroup ( QActionGroup * group )

Définit le groupe d'actions à group. L'action sera automatiquement ajoutée à la liste des actions du groupe.

Les actions du groupe seront mutuellement exclusives.

Voir aussi QActionGroup et QAction::actionGroup().

void QAction::setData ( const QVariant & userData )

Définit userData comme données internes de l'action.

Voir aussi data().

void QAction::setDisabled ( bool b ) [slot]

Cette fonction est une fonction de commodité pour la propriété enabled, utile pour les connexions signaux-slots. Si b est true alors l'action est désactivée ; sinon elle est activée.

void QAction::setMenu ( QMenu * menu )

Définit menu comme menu contenu dans cette action.

Voir aussi menu().

void QAction::setSeparator ( bool b )

Si b est true alors l'action sera considérée comme un séparateur.

La façon dont un séparateur est représenté dépend du widget dans lequel il est inséré. Dans la plupart des cas, le texte, le sous-menu et les icônes sont ignorés pour les actions séparateur.

Voir aussi QAction::isSeparator().

void QAction::setShortcuts ( const QList<QKeySequence> & shortcuts )

Définit les raccourcis shortcuts comme liste de raccourcis qui déclenchent l'action. Le premier élément de la liste est le raccourci principal.

Cette fonction a été introduite dans Qt 4.2.

Voir aussi shortcuts() et shortcut.

void QAction::setShortcuts ( QKeySequence::StandardKey key )

Définit une liste de raccourcis dépendante de la plate-forme basée sur la clé key. Le résultat de l'appel de cette fonction dépendra de la plate-forme courante. Notez que plus d'un raccourci peut être affecté par cette action. Si seul le raccourci principal est requis, utilisez la fonction setShortcut() à la place.

Cette fonction a été introduite dans Qt 4.2.

Voir aussi QKeySequence::keyBindings().

QList<QKeySequence> QAction::shortcuts () const

Retourne la liste de raccourcis, avec le raccourci principal comme premier élément de la liste.

Cette fonction a été introduite dans Qt 4.2.

Voir aussi setShortcuts().

bool QAction::showStatusText ( QWidget * widget = 0 )

Met à jour la barre d'état appropriée pour le widget spécifié en envoyant un QStatusTipEvent à ce widget. Retourne true si l?événement a été envoyé ; sinon retourne false.

Si un widget nul est spécifié, l?événement est envoyé au parent de l'action.

Voir aussi statusTip.

void QAction::toggle () [slot]

Cette fonction est une fonction de commodité pour la propriété checked. Connectez-vous à ce slot pour basculer l'état coché à sa valeur opposée.

void QAction::toggled ( bool checked ) [signal]

Ce signal est émis à chaque fois qu'une action cochable modifie son état isChecked(). Cela peut être causé par une interaction avec l'utilisateur ou par un appel à la fonction setChecked().

checked est true si l'action est cochée ou false si l'action ne l'est pas.

Voir aussi QAction::activate(), QAction::triggered() et checked.

void QAction::trigger () [slot]

Ce slot est un slot de commodité qui appelle activate(Trigger).

void QAction::triggered ( bool checked = false ) [signal]

Ce signal est émis à chaque fois qu'une action est activée par l'utilisateur; par exemple, lors d'un clic de souris sur le menu, la barre d'outils ou de l'activation du raccourci clavier, ou encore lorsque trigger() a été appelé. Attention, le signal n'est pas émis après un appel aux fonctions setChecked() ou toggle().

Si l'action est cochable, checked est true si l'action est cochée, ou false si l'action est décochée.

Voir aussi QAction::activate(), QAction::toggled() et checked.

Remerciements

Merci à Alexandre Laurent pour la traduction, ainsi qu'à Ilya Diallo et Claude Leloup pour la relecture !