QShortcut

La classe QShortcut est utilisée pour créer des raccourcis clavier. Plus d'informations...

#include <QShortcut>

Héritage

Hérite de QObject.

Description détaillée

La classe QShortcut est utilisée pour créer des raccourcis clavier. Elle fournit un moyen de connecter des raccourcis clavier au mécanisme de signaux et slots de Qt, de sorte que les objets peuvent être informés quand une combinaison de touches d'un raccourci est enfoncée. Le raccourci peut être mis en place pour contenir toutes les touches nécessaires à la description d'un raccourci clavier, y compris les états des touches de modification telles que Shift, Ctrl et Alt.

Sur certains widgets, utiliser & devant un caractère crée automatiquement un raccourci pour celui-ci. Par exemple  »&Quitter » crée un raccourci Alt+Q (utiliser && pour afficher une esperluette). Le widget peut consommer et effectuer une action sur un raccourci. Sur X11, l'esperluette ne sera pas affichée, et le caractère sera souligné. Sur Windows, les raccourcis ne sont normalement pas affichés jusqu'à ce que l'utilisateur presse la touche Alt, mais ceci est un paramètre que l'utilisateur peut changer. Sur Mac, les raccourcis sont désactivés par défaut. Appelez qt_set_sequence_auto_mnemonic() pour les activer. Cependant, étant donné que les raccourcis mnémotechniques ne rentrent pas dans les lignes directrices d'Aqua, Qt ne soulignera pas le caractère du raccourci.

Pour les applications qui utilisent des menus, il peut être plus pratique d'utiliser les fonctions prévues dans la classe QMenu pour assigner des raccourcis clavier à des éléments du menu lors de leur création. Par ailleurs, les raccourcis peuvent être associés à d'autres types d'actions dans la classe QAction.

Le plus simple pour créer un raccourci pour un widget particulier est de le construire avec une séquence de touches. Par exemple :

raccourci = new QShortcut(QKeySequence(tr(Ctrl+O, Ouvrir un fichier)),
                          parent);

Quand l'utilisateur tape la série de touches pour un raccourci, le signal activated() de la classe est émis (en le cas d'ambiguïté, le signal activatedAmbiguously() est émis). Un raccourci est perçu par la boucle événementielle de Qt au moment où le raccourci du widget parent reçoit les événements.

Une séquence de touches de raccourci peut être définie avec setKey() et récupérée avec key(). Un raccourci peut être activé ou désactivé avec setEnabled() et peut avoir un texte d'aide « What's This? » défini par setWathsThis().

Voir aussi QShortcutEvent, QKeySequence et QAction.

Propriétés

autoRepeat : bool

Cette propriété indique si le raccourci peut se répéter automatiquement.

Si true, le raccourci est automatiquement répété quand la combinaison du raccourci clavier est effectuée, à condition que l'auto-répétition du clavier soit activée sur le système. La valeur par défaut est true.

Cette propriété a été introduite à partir de Qt 4.2.

Fonctions d'accès

bool autoRepeat () const
void setAutoRepeat ( bool on )

context : Qt::ShortcutContext

Cette propriété indique le contexte dans lequel le raccourci est valide.

Un contexte de raccourci décide dans quelle circonstance un raccourci est autorisé à être déclenché. Le contexte par défaut est Qt::WindowShortcut, qui permet au raccourci d'être déclenché si le parent (le widget qui contient le raccourci) est un sous-widget de la fenêtre active au premier plan.

Par défaut, cette propriété est égale à Qt::WindowShortcut.

Fonctions d'accès

Qt::ShortcutContext context ()
void setContext ( Qt::ShortcutContext context )

enabled : bool

Cette propriété indique si le raccourci est activé.

L'activation d'un raccourci émet les signaux activated() ou activatedAmbiguously() quand un QShortcutEvent qui correspond à la séquence key() du raccourci est pressé.

Si l'application est en mode WhatsThis, le raccourci n'émettra pas les signaux, mais affichera le texte de la propriété « What's This? » à la place.

Par défaut, cette propriété vaut true.

Fonctions d'accès

bool isEnabled () const
void setEnabled ( bool enable )

Voir aussi whatsThis.

key : QKeySequence

Cette propriété contient la séquence de touches du raccourci.

Il s'agit d'une séquence de touches avec une combinaison optionnelle de Shift, Ctrl et Alt. La séquence de touches peut être fournie de différentes façons :

setKey(0);                       // aucun signal émis
setKey(QKeySequence());          // aucun signal émis
setKey(0x3b1);                   // la lettre grecque Alpha 
setKey(Qt::Key_D);               // 'd', pour par exemple supprimer 
setKey('q');                     // 'q', pour par exemple quitter
setKey(Qt::CTRL + Qt::Key_P);    // Ctrl+P, pour par exemple imprimer le document 
setKey("Ctrl+P");                // Ctrl+P, pour par exemple imprimer le document

Par défaut, cette propriété contient une séquence de touches vide.

Fonctions d'accès

QKeySequence key () const
void setKey ( const QKeySequence & key )

whatsThis : QString

Cette propriété contient le texte d'aide « What's This? » du raccourci.

Le texte sera affiché quand l'application est en mode « What's This? » et que l'utilisateur tape la série de touches key() du raccourci.

Pour définir l'aide « What's This? » sur un élément d'un menu (avec ou sans touche de raccourci), définissez l'aide sur l'action de l'élément.

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

Fonctions d'accès

QString whatsThis () const
void setWhatsThis ( const QString & text )

Voir aussi QWhatsThis::inWhatsThisMode() et QAction::setWhatsThis().

Fonctions membres

QShortcut::QShortcut ( QWidget * parent )

Construit un objet QShortcut pour le widget parent. Tant qu'aucun raccourci clavier n'est spécifié, le raccourci n'émettra aucun signal.

Voir aussi setKey().

QShortcut::QShortcut ( const QKeySequence & key, QWidget * parent, const char * member = 0, const char * ambiguousMember = 0, Qt::ShortcutContext context = Qt::WindowShortcut )

Construit un objet QShortcut pour le widget parent. Le raccourci fonctionne sur son parent, écoutant les QShortcutEvent qui correspondent à la séquence de touches. En fonction de l'ambiguïté de l'événement, le raccourci appellera la fonction member ou la fonction ambiguousMember, si la touche pressée était dans le context du raccourci.

QShortcut::~QShortcut ()

Détruit le raccourci.

void QShortcut::activated () [signal]

Ce signal est émis quand l'utilisateur tape la séquence de touches du raccourci.

Voir aussi activatedAmbiguously().

void QShortcut::activatedAmbiguously () [signal]

Quand une séquence de touches est bien tapée sur le clavier, on dit qu'elle est ambiguë dans la mesure où elle correspond à l'ouverture de plus d'un raccourci.

Quand la séquence de touches du raccourci est complète, activatedAmbiguously() est émis si la séquence de touches est toujours ambiguë (c'est-à-dire s'il s'agit du début d'un ou de plusieurs autres raccourcis). Le signal activated() n'est pas émis dans ce cas.

Voir aussi activated().

int QShortcut::id () const

Retourne l'identifiant du raccourci.

Voir aussi QShortcutEvent::shortcutId().

QWidget * QShortcut::parentWidget () const

Retourne le widget parent du raccourci.

Remerciements

Merci à Adrien Dadouchi pour la traduction et à Jonathan Courtois, Thibaut Cuvelier et à Jacques Thery pour leur relecture !