QWhatsThis Class

Description détaillée

L'aide « Qu'est-ce que c'est ? » fait partie du système d'aide en ligne d'une application et fournit aux utilisateurs des informations sur les fonctionnalités et l'utilisation d'un widget particulier. Les textes d'aide « Qu'est-ce que c'est ? » sont généralement plus longs et plus détaillés que ceux de l'aide « tooltips », mais fournissent généralement moins d'informations que celles fournies par des fenêtres d'aide distinctes.

QWhatsThis propose une fenêtre unique contenant un texte explicatif qui s'affiche lorsque l'utilisateur demande « Qu'est-ce que c'est ? ». Par défaut, pour poser cette question, l’utilisateur doit placer le curseur sur le widget concerné et appuyer sur Maj+F1. Le texte d’aide s’affiche immédiatement ; il disparaît dès que l’utilisateur effectue une autre action. (Notez que si un raccourci clavier est déjà attribué à la combinaison Maj+F1, ce mécanisme ne fonctionnera pas.) Certaines boîtes de dialogue proposent un bouton « ? » sur lequel les utilisateurs peuvent cliquer pour passer en mode « Qu'est-ce que c'est ? » ; ils cliquent ensuite sur le widget concerné pour faire apparaître la fenêtre « Qu'est-ce que c'est ? ». Il est également possible de proposer une option de menu ou un bouton de la barre d'outils pour passer en mode « Qu'est-ce que c'est ? ».

Pour ajouter un texte « Qu'est-ce que c'est ? » à un widget ou à une action, il suffit d'appeler QWidget::setWhatsThis() ou QAction::setWhatsThis().

Le texte peut être soit du texte enrichi, soit du texte brut. Si vous spécifiez une chaîne formatée en texte enrichi, elle sera affichée à l’aide de la feuille de style par défaut, ce qui permet d’intégrer des images dans le texte affiché. Pour ê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 affiché en texte brut. Voir Qt::mightBeRichText() pour plus de détails.

newAct = new QAction(tr("&New"), this);
newAct->setShortcut(tr("Ctrl+N"));
newAct->setStatusTip(tr("Create a new file"));
newAct->setWhatsThis(tr("Click this option to create a new file."));

Une autre façon d’accéder au mode « Qu’est-ce que c’est ? » consiste à appeler createAction(), puis à ajouter l’ QAction renvoyée à un menu ou à une barre d’outils. En invoquant cette action d’aide contextuelle (sur l’image ci-dessous, le bouton avec l’icône représentant une flèche et un point d’interrogation), l’utilisateur passe en mode « Qu’est-ce que c’est ? ». S’il clique alors sur un widget, le texte d’aide correspondant s’affiche. Le mode prend fin lorsque l’aide est fournie ou lorsque l’utilisateur appuie sur la touche Échap.

Vous pouvez passer en mode « Qu'est-ce que c'est ? » par programmation avec enterWhatsThisMode(), vérifier le mode avec inWhatsThisMode(), et revenir au mode normal avec leaveWhatsThisMode().

Si vous souhaitez contrôler manuellement le comportement « Qu'est-ce que c'est ? » d'un widget, consultez Qt::WA_CustomWhatsThis.

Il est également possible d’afficher différents textes d’aide pour différentes zones d’un widget, en utilisant un QHelpEvent de type QEvent::WhatsThis. Interceptez l’événement d’aide dans la fonction QWidget::event() de votre widget et appelez QWhatsThis::showText() avec le texte que vous souhaitez afficher à la position spécifiée dans QHelpEvent::pos(). Si le texte est au format RTF et que l’utilisateur clique sur un lien, le widget reçoit également un événement « QWhatsThisClickedEvent » avec la référence du lien sous la forme QWhatsThisClickedEvent::href(). Si un événement « QWhatsThisClickedEvent » est géré (c’est-à-dire si QWidget::event() renvoie true), la fenêtre d’aide reste visible. Appelez QWhatsThis::hideText() pour la masquer explicitement.