création de fichiers d'aide

Accueil > Iza > Aide HLP > Microsoft HelpWorkshop 4, leçon 2
Ou Page précédente

Rattacher l'aide à votre projet VB

Introduction

Rattacher l'aide à votre projet VB se fait littéralement en quelques clics. C'est pourquoi j'ai choisi de vous montrer aussi dans cette rubrique comment intégrer l'aide contextuelle du bouton Qu'est-ce que c'est? (ou What's this help). J'y ai aussi ajouté la programmation de l'objet CommonDialog qui permet un meilleur contrôle de l'affichage de l'aide. Attention, cette leçon est principalement une leçon de VB. Désolé ! Les amateurs d'autres langages de programmation devront s'en remettre à l'aide de leur environnement de développement ou à un autre site Web. Si c'est votre cas, essayez le site Développez.com, vous y trouverez des tutoriels, des forums et une section FAQ qui répondront peut-être à vos besoins. J'y ai trouvé quelques tutoriels de création de fichiers d'aide pour Delphi et C++.

---

Lier le fichier d'aide HLP à votre projet VB

C'est par la fenêtre Propriétés du projet (Project properties) de Visual Basic que vous lierez votre fichier d'aide.

1. D'abord, ouvrez votre fichier de projet VB, pour l'exemple présent, le fichier Bonjour.vbp que vous avez téléchargé.
2. Ouvrez la fenêtre de propriétés du projet Projet > Propriétés de Bonjour (Project > Bonjour Properties).
3. Dans l'onglet Général, cliquez sur le bouton […] de la zone Nom du fichier d'aide (Help File Name) pour ouvrir la boîte de dialogue Fichier d'aide (Help File).
4. Localisez le dossier où se trouvent vos fichier et sélectionnez le fichier Aidehlp.hlp. Cliquez sur Ouvrir.
5. Cliquez sur OK pour valider et fermer la fenêtre Propriétés du projet.

Voilà ! C'est fait ! Maintenant, pour tester si ça fonctionne, dans VB, appuyez sur la touche F5 pour démarrer l'exécution du programme. Puis, appuyez sur F1 pour afficher votre fichier d'aide.

|   Haut de la page   |   Sommaire   |

---

Ajoutez un bouton pour afficher l'aide

Bon ! Évidemment, ce n'est pas tout le monde qui connaissent les raccourcis de clavier ou les utilisent même s'ils les connaissent. Vous voudrez ajouter un bouton ou une option de menu pour accéder à vos rubriques d'aide.

1. Dans la fenêtre de dessin de VB ajoutez un bouton de commande cmdAide (propriété name) avec le texte &Aide (propriété caption).
2. Double-cliquez dessus pour afficher la fenêtre de code.
3. Dans la procédure cmdAide_Click(), ajoutez ceci :
      Sendkeys "{F1}"
   sans oublier les gillemets.
4. Enregistrez votre projet et appuyez sur F5 pour démarrer l'exécution du programme.
5. Cliquez sur votre bouton d'aide pour vérifier que tout fonctionne bien.

Vous verrez apparaître l'Assistant à la création de recherche. Cliquez sur Annuler puisque nous n'avons pas encore configuré l'onglet Rechercher. Votre rubrique principale devrait apparaître à l'écran.

L'instruction Sendkeys

L'instruction Sendkeys de VB sert à simuler par programmation l'action de l'utilisateur sur le clavier. L'argument de l'instruction Sendkeys est toujours une valeur de chaîne. Par exemple, Sendkeys "Bonjour" agit comme si l'utilisateur avait tapé le mot Bonjour. Le terme entre les accolades est le nom d'une touche de fonction ou d'une touche autre qu'un chiffre ou une lettre. L'aide de VB donne une liste de toutes ces constantes. Par l'instruction Sendkeys "{F1}", nous avons « dit » au programme : « fais comme si l'utilisateur avait appuyé sur la touche F1 ». Par défaut, la touche F1 ouvre l'application winhelp (fenêtre d'aide) avec votre fichier d'aide (spécifié dans les propriétés de votre programme).

L'autre méthode, nécessitant un peu plus de code, consiste à utiliser les boîtes de dialogues communes (contrôle CommonDialog). Nous y reviendront un peu plus loin.

|   Haut de la page   |   Sommaire   |

---

Ajouter l'aide Qu'est-ce que c'est ?

L'aide « Qu'est-ce que c'est? » est souvent utilisée dans les boîtes de dialogues pour donner de brèves descriptions de leurs différents éléments. Tel qu'il est présentement, notre projet VB ne peut afficher à la fois l'aide et l'aide « Qu'est-ce que c'est? ». Peut-être l'utilisation et la programmation avancée d'un contrôle CommonDialog permettrait de le faire, mais comme je suis encore incapable de le faire (c'est difficile à avouer)... Allez savoir ! Ha ! Un jour, j'aurai fait le tour de la question et je vous le dirai... peut-être sous la forme d'un tutoriel...

Quoi qu'il en soit, lorsqu'une feuille a pour la propriété BorderStyle les valeurs 1 - Fixed Single ou 3 - Fixed Dialog, il est possible d'y ajouter l'aide contextuelle. Mais pas avec les autres valeurs. En tous cas,j'ai essayé et ça n'a pas marché.

Pour ajouter l'aide « Qu'est-ce que c'est? » à notre application, nous allons d'abord ajouter une procédure DblClick sur la feuille de notre projet qui ouvrira la feuille Dialog.frm (inclue dans le projet VB du fichier zip). Puis nous allons lier des rubriques d'aide à différents objets de la feuille Dialog.frm. La feuille Dialog.frm a, vous vous en doutez, à proriété BorderStyle, la valeur
3 - Fixed Dialog.

Ajouter la procédure d'ouverture de la boîte de dialogue

1. Dans la fenêtre de dessin de VB, double-cliquez sur la feuille (mais pas sur un de ses contrôles) Bonjour.frm.
2. La fenêtre de code s'ouvre sur une procédure Load. N'y écrivez rien. Déroulez la liste des procédure (en haut, à droite) et choisissez DblClick.
3. Dans la nouvelle procédure ainsi créée, tapez le code suivant :
      Dialog.Show vbModal, Me

Vous venez de créer la procédure qui ouvrira une boîte de dialogue modale. Pour en savoir plus sur les fenêtres modales ou non modales, dans la fenêtre de code de VB sélectionnez le mot Show et appuyez sur F1. Je ne m'étendrez pas trop ici sur le sujet des fenêtres modales quisque l'aide de VB forurnit suffisamment d'explications. Ha ! Vous avez la version anglaise et « vous n'y entravez que dale ! » Bon !
Cliquez ici pour une explication sur les fenêtres modales et non modales.
Cliquez ici pour une description de la méthode Show.

Lier les contrôles à leurs descriptions

1. Double-cliquez sur Dialog(Dialog.frm) dans l'explorateur de projet pour afficher la fenêtre de design de cette feuille.
2. Ajoutez ces valeurs de propriétés pour les contrôles suivants :
    

   Contrôle(s)	Propriété	Valeur
   Dialog (Form)	WhatsThisButton	True
   Dialog (Form)	WhatsThisHelp	True
   Option1 (les deux)	WhatsThisHelpID	801
   OKButton et CancelButton	WhatsThisHelpID	501

Vous venez de lier vos rubriques pour l'aide Qu'est-ce que c'est? à votre boîte de dialogue. Pour en voir le résultat, exécutez l'application et double cliquez sur la feuille à côté du mot Bonjour. La boîte de dialogue apparaît avec son bouton [ ? ]. Cliquez sur ce bouton puis sur un des contrôles de la feuille.

|   Haut de la page   |   Sommaire   |

---

L'utilisation du contrôle CommonDialog pour afficher l'aide

Vous aurez remarqué que le fait d'appuyer sur la touche F1 ouvre automatiquement l'aide, mais avec un inconvénient. WinHelp essaiera de trouver ce que vous n'avez pas encore programmé dans votre fichier d'aide : les mots clés pour l'onglet Rechercher. Ce qui provoque l'affichage de l'Assistant création de recherche chaque fois que l'utilisateur appuiera sur F1 ou cliquera sur votre bouton Aide (puisque nous y avons programmé la simulation d'un appui sur F1). Un peu agaçant, n'est-ce pas? C'est pourquoi il est recommandé d'ajouter un contrôle CommonDialog à votre projet VB. L'ajout de ce contrôle et la programmation de ses propriétés permet un meilleur contrôle de ce que voulez afficher lorsque l'utilisateur appelle l'aide de votre application.

Nous allons ajouter un contrôle CommonDialog à la feuille frmBonjour et ajouter le code nécessaire à l'affichage de l'aide au bouton cmdAide. Pour ajouter un contrôle CommonDialog à la feuille, vous devez d'abord ajouter une composante à votre projet.

1. Ouvrez le menu Projet et choisissez l'option Composantes (Project > Components).
2. Dans la boîte de dialogue Compasants (Components), dans l'onglet Contrôles (Controls), trouvez dans la liste des contrôles Microsoft Common Dialog Controls 6.0 (SP3) et cochez la case pour le sélectionner.
3. Cliquez sur Appliquer et OK.

Vous pouvez maintenant ajouter un objet CommonDialog à la feuille frmBonjour.

1. Double-cliquez sur l'outil CommonDialog que vous avez ajouté à la palette d'outils de VB. l'endroit où « atterrit » votre contrôle importe peu puisqu'il sera invisible pendant l'exécution du programme.
2. Si ce n'est déjà fait, sélectionnez l'objet CommonDialog sur la feuille et à la propriété Name, tapez dlgAide.

Il ne vous reste plus qu'à programmer l'affichage de votre boîte de dialogue. Nous allons pour ce faire utiliser les propriétés HelpFile et HelpCommand ainsi que la méthode ShowHelp. Voici une brève explication des deux propriétés et de la méthode ShowHlep.

HelpFile, propriété

Valeur de chaîne (String). On y place le chemin complet du fichier d'aide à afficher.

HelpCommand, propriété

Valeur de donnée entière (Integer). Selon le paramètre indiqué, l'aide s'affichera sous la forme correspondantes. Voyez plus bas la liste des différentes valeurs de HelpCommand et des constantes que l'on peut utiliser.

ShowHelp, méthode

Une des méthode du contrôle CommonDialog. ShowHelp, comme son nom l'indique, affiche la fenêtre d'aide. Voici la liste des autres méthodes disponibles :

• ShowColor : Affiche la boîte de dialogue Couleur
• ShowFont : Affiche la boîte de dialogue Police
• ShowOpen : Affiche la boîte de dialogue Ouvrir
• ShowPrinter : Affiche la boîte de dialogue Imprimer
• ShowSave : Affiche la boîte de dialogue Enregistrer sous

Cliquez ici pour une liste des valeurs de la propiété HelpCommand.

Programmer l'affichage de la fenêtre d'aide

Maintenant que vous en savez plus sur le contrôle CommonDialog et les propriétés et méthodes qui affichent l'aide, voici le code que vous devrez taper dans la procédure cmdAide_Clic() à la place de l'instruction Sendkeys.

   Private Sub cmdAide_Click()
      Dim fichierAide As String
         fichierAide = App.Path
      If Right(fichierAide, 1) = "\" Then
         fichierAide = fichierAide & "AideHLP.hlp"
      Else
         fichierAide = fichierAide & "\AideHLP.hlp"
      End If
      With dlgAide
         .HelpFile = fichierAide
         .HelpCommand = cdlHelpContents
         .ShowHelp
      End With
   End Sub

La variable fichierAide sert à construire le chemin d'accès (path) du fichier d'aide. La commande App.Path sert à trouver le chemin d'accès de l'application courante. Gardez en mémoire que votre application, une fois installé sur un autre ordinateur, ne se retrouvera pas nécessairement sur le même chemin d'accès que sur le votre ordinateur. Les fichiers d'aides seront dans le sous-répertoire que vous aurez défini par rapport à l'application. Mais l'application sera installé sur l'ordinateur de l'utilisateur, sur un lecteur et dans un répertoire choisi par lui.

La structure If... Then... Else... End If sert à vérifier si l'application se trouve dans le répertoire racine (exemple : C:\), ce qui est assez rare mais pas impossible, et à compléter le chemin d'accès en ajoutant ou non une barre oblique inversée (back slash) et le nom du fichier.

La constante cdlHelpContents (valeur de la propriété HelpCommand) indique au programme Winhelp que c'est le contenu tel que défini à l'option Contents de la section [OPTION] de votre fichier .hpj (help project ou fichier de projet d'aide) qui sera affiché comme fenêtre de départ.

|   Haut de la page   |   Sommaire   |

---

En résumé

Lier l'aide à votre projet VB relève d'avantage de la programmation VB que de l'aide elle-même. Cette leçon fut donc en grande partie un retour à Visual Basic. Vous y avez appris ou redécouvert :

• Comment lier, via la fenêtre de propriétés de VB, le fichier d'aide à votre projet.
• Comment programmer un bouton qui fait afficher l'aide en utilisant l'instruction Sendkeys "{F1}", une astuce qui contourne la programmation des boîtes de dialogues communes (contrôle CommonDialog).
• Un rappel sur les boîtes de dialogue modales et la méthode Show de VB.
• Comment rendre l'aide « Qu'est-ce que c'est? » disponible dans une fenêtre fixe ou une boîte de dialogue (propriétés WhatsThisButton et WhatsThisHelp).
• Comment lier les contrôles aux rubriques (propriété WhatsThisHelpID).
• Et enfin, comment utiliser le contrôle CommonDialog pour afficher l'aide.

Dans la leçon suivante, nous verront comment créer un fichier de contenu qui permettra d'afficher la fenêtre Sommaire (et l'onglet rechercher, par la force des choses). Les dernières leçons présenteront comment ajouter un index de mots clés et comment paramétrer l'onglet Rechercher. Mais toutes ces leçons ne sont encore qu'à l'état de projet. Alors, à bientôt !

|   Leçon précédente   |   Leçon suivante   |

---

|   Haut de la page   |   Sommaire   |