QWhatsThis

La classe QWhatsThis fournit une description simple de tout widget, c'est à dire en répondant à la question : « What's This? » (Qu'est-ce que c'est ?). Plus d'informations...

#include <QWhatsThis>

Description détaillée

La classe QWhatsThis fournit une description simple de tout widget, c'est à dire en répondant à la question : « What's This? » (Qu'est-ce que c'est ?).

L'aide « What's This? » fait partie du système d'aide en ligne de l'application, et fournit aux utilisateurs des informations concernant les fonctionnalités et l'utilisation d'un widget particulier. Le texte de l'aide « What's This? » est typiquement plus long et plus détaillé que les infobulles, mais fournit généralement moins d'informations que ceux qui sont procurés par des fenêtres d'aide séparées.

QWhatsThis fournit une fenêtre unique contenant un texte explicatif s'affichant quand l'utilisateur pose la question « What's This? ». La méthode par défaut, permettant aux utilisateurs de poser la question, est de déplacer le focus vers le widget approprié et d'appuyer sur Shift+F1. Le texte d'aide apparaît immédiatement et s'en va dès que l'utilisateur effectue une autre action (notez que, s'il existe un raccourci pour Shift+F1, ce mécanisme ne fonctionnera pas). Quelques boîtes de dialogue fournissent un bouton  »? » sur lequel les utilisateurs peuvent cliquer pour entrer dans le mode « What's This? » ; ils cliquent ensuite sur le widget approprié pour afficher la fenêtre « What's This? ». Il est aussi possible de fournir un menu ou une barre d'outils pour passer au mode « What's This? ».

Pour ajouter le texte « What's This? » à un widget ou une action, appelez tout simplement whatsThisQWidget::setWhatsThis() ou QAction::setWhatsThis().

Le texte peut être soit du texte enrichi, soit du texte simple. Si vous spécifiez une chaîne de caractères formée de texte enrichi, elle sera rendue en utilisant la feuille de style par défaut, ce qui permet d'inclure des images dans le texte affiché. Afin d'être aussi rapide que possible, la feuille de style par défaut utilise une méthode simple pour déterminer si le texte peut être rendu comme un texte simple. Regardez Qt::mightBeRichText() pour plus de détails.

newAct = new QAction(tr("&Nouveau"), this);
newAct->setShortcut(tr("Ctrl+N"));
newAct->setStatusTip(tr("Crée un nouveau fichier"));
newAct->setWhatsThis(tr("Cliquez sur cette option pour créer un nouveau fichier."));

Une alternative pour entrer dans le mode « What's This? » est d'appeler la fonction createAction() et d'ajouter la QAction retournée soit dans un menu, soit dans une barre d'outils. Par l'invocation de cette action d'aide contextuelle (dans l'image ci-dessous, le bouton avec une icône contenant une flèche et un point d'interrogation), l'utilisateur bascule en mode « What's This? ». S'il clique sur un widget, le texte d'aide approprié est affiché. Le mode est quitté quand l'aide est donnée ou quand l'utilisateur appuie sur Echap.

Vous pouvez entrer dans le mode « What's This? » avec enterWhatsThisMode(), vérifier le mode avec inWhatsThisMode() et retourner au mode normal avec leaveWhatsThisMode().

Si vous désirez contrôler manuellement le comportement « What's This? » d'un widget, regardez Qt::WA_CustomWhatsThis.

Il est aussi possible d'afficher différents textes d'aide dans différentes zones d'un widget par l'utilisation de l'objet QHelpEvent de type QEvent::WhatsThis. Il intercepte l'évènement d'aide dans la fonction QWidget::event() de votre widget et appelle QWhatsThis::showText() avec le texte que vous voulez afficher à la position spécifiée dans QHelpEvent::pos(). Si le texte est enrichi et que l'utilisateur clique sur un lien, le widget reçoit également un QWhatsThisClickedEvent avec la référence du lien en tant que QWhatsThisClickedEvent::href(). Si un QWhatsThisClickedEvent est traité (c'est-à-dire que QWidget::event() retourne true), la fenêtre d'aide reste visible. Appelez QWhatsThis::hideText() pour la cacher explicitement.

Voir aussi QToolTip.

Fonctions membres

QAction * QWhatsThis::createAction ( QObject * parent = 0 ) [static]

Renvoie une QAction toute faite, utilisée pour invoquer une aide contextuelle « What's This? », avec le parent donné.

La QAction retournée fournit un moyen pratique de permettre aux utilisateurs d'entrer dans le mode « What's This? ».

void QWhatsThis::enterWhatsThisMode () [static]

Cette fonction fait basculer l'interface utilisateur dans le mode « What's This? ». L'interface utilisateur peut revenir au mode normal par action de l'utilisateur (par exemple quand il clique ou quand il appuie sur Echap), ou par programmation en appelant leaveWhatsThisMode().

Lors de l'entrée dans le mode « What's This? », un QEvent de type Qt::EnterWhatsThisMode est envoyé à tous les widgets de haut niveau.

Voir aussi inWhatsThisMode() et leaveWhatsThisMode().

void QWhatsThis::hideText () [static]

Si une fenêtre « What's This? » est affichée, elle est détruite.

Voir aussi showText().

bool QWhatsThis::inWhatsThisMode () [static]

Retourne true si l'interface utilisateur est en mode « What's This? », sinon retourne false.

Voir aussi enterWhatsThisMode().

void QWhatsThis::leaveWhatsThisMode () [static]

Si l'interface utilisateur est en mode « What's This? », cette fonction la fait retourner en mode normal, sinon elle ne fait rien.

Lors de la sortie du mode « What's This? », un QEvent de type Qt::LeaveWhatsThisMode est envoyé aux widgets de haut niveau.

Voir aussi enterWhatsThisMode() et inWhatsThisMode().

void QWhatsThis::showText ( const QPoint & pos, const QString & text, QWidget * w = 0 ) [static]

Affiche text comme une fenêtre « What's This? », à la position globale pos. L'argument optionnel w, désignant un widget, est utilisé pour déterminer l'écran approprié sur les systèmes multi-têtes (multi-head).

Voir aussi hideText().

Remerciements

Merci à Louis du Verdier pour la traduction et à Jonathan Courtois, Thibaut Cuvelier ainsi qu'à Jacques Thery pour leur relecture !