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 !