CamerNet - Visual Basic - Tutoriels

Une fois le fichier d'aide créé, vous devez insérer dans votre application Visual Basic des commandes pour ouvrir ce-dernier et le manipuler.

Généralement dans la feuille principale d'une application, figure un menu Help ou un menu ? permettant à l'utilisateur d'accéder à l'aide en ligne de diverses façons.

Et très souvent aussi, les contrôles de feuilles permettent d'accéder à l'aide du contrôle lorsqu'on presse sur F1.

Tout ceci se fait grâce à l'utilisation de la fonction API WINHELP. Grâce à cette fonction API, vous envoyez des messages à votre fichier d'aide en lui demandant d'executer diverses tâches comme montrer le sommaire, montrer l'index ou encore montrer une rubrique à partir de son identificateur.

Lorsque vous appellez la fonction API WinHelp, cette dernière démarre (si elle ne l'est pas encore) l'Application Windows Help qui est chargée de recevoir vos messages et commandes afin de manipuler le fichier d'aide de votre application.

Public Declare Function WinHelp Lib "user32" Alias "WinHelpA" (ByVal hwnd As Long, ByVal lpHelpFile As String, ByVal wCommand As Long, ByVal dwData As Long) As Long

Ce paramètre désigne le handle de la fenêtre qui appelle la fonction. Pour obtenir le handle d'une fenêtre utilisez un code similaire à ceci: Form1.hwnd.

Ce paramètre désigne le chemin d'accès complet suivi du nom du fichier d'aide à manipuler. Si par exemple votre fichier d'aide est situé dans le même répertoire que celui de votre application, utilisez ceci: App.Path & "\MonFichier.HLP" comme paramètre.
Vous pouvez, à la suite du nom de fichier, ajouter un ">" suivi du nom de la fenêtre secondaire dans laquelle doit être chargée la rubrique (si vous ne voulez pas que cette dernière soit chargée dans la fenêtre par défaut). Ce nom de fenêtre secondaire doit être sécifié dans la section [WINDOWS] du Fichier Projet de l'aide (.HPJ).

Spécifie le type d'aide demandé. Pour une liste des valeurs possibles ainsi que leurs effets sur la valeur du paramètre dwData regardez plus loin dans cette page.

Spécifie des données additionnelles. La valeur utilisée dépend de la valeur du paramètre wCommand. Pour une liste des valeurs possibles, regardez plus loin dans cette page.

Si la fonction réussit, la valeur renvoyée est tout nombre différent de 0.
Si la fonction échoue, la valeur renvoyée est 0.

Voici la déclaration de toutes les constanstes qui vont être utilisées dans cette section:

Public Const HELP_CONTENTS = &H3&
Public Const HELP_CONTEXT = &H1
Public Const HELP_CONTEXTPOPUP = &H8&
Public Const HELP_HELPONHELP = &H4
Public Const HELP_INDEX = &H3
Public Const HELP_QUIT = &H2
Public Const HELP_SETCONTENTS = &H5&
Public Const HELP_FORCEFILE = &H9&

Lorsque vous appelerez la fonction API WinHelp, vous devrez passer une de ces constantes comme paramètre wCommand. La valeur de dwData dépendra ensuite de la constante que vous avez adopté.

Affiche la rubrique par défaut spécifiée dans l'option Contents de la section [OPTIONS] du fichier .HPJ. La paramètre dwData est dans ce cas ignoré, mettez y le nombre 0.
Exemple:

Dim LResult As Long
LResult = WinHelp (hwnd, App.Path & "\Help.hlp", HELP_CONTENTS, 0)

Affiche la rubrique dont l'identificateur contextuel est la valeur spécifiée dans dwData. L'identificateur contextuel d'une rubrique est un nombre associé à la rubrique et défini dans la section [MAP] du fichier .HPJ.

Affiche, dans une fenêtre Pop-Up, la rubrique dont l'identificateur contextuel est la valeur spécifiée dans dwData.

S'assure que WinHelp affiche le fichier d'aide correcte. Si un fichier d'aide incorrecte est en train d'être affiché, WinHelp ouvre celui qui est correcte, sinon aucune action n'est executée. Le paramètre dwData est dans ce cas ignoré, mettez y le nombre 0.

Affiche l'aide "Comment utiliser Windows Help", si le fichier WINHELP.HLP est disponible. Le paramètre dwData est dans ce cas ignoré, mettez y le nombre 0.

Affiche l'Index du fichier d'aide. L'Index c'est la partie du fichier d'aide qui affiche la liste des mots clés de l'aide. Le paramètre dwData est dans ce cas ignoré, mettez y le nombre 0.

Définit la rubrique qui constitue le sommaire de l'aide. Dans cette rubrique, vous pourrez classer et ranger les liens vers les autres rubriques selon vos préférences. Le paramètre dwData contient dans ce cas l'identificateur contextuel de cette rubrique. Cette constante est généralement utilisée lorsque votre fichier d'aide ne contient pas de Fichier Sommaire. NOTE: vous devez d'abord charger votre fichier d'aide en mémoire à l'aide de la constante HELP_CONTENTS.

Informe le fichier d'aide qu'on n'a plus besoin de lui. Le fichier d'aide se ferme donc. Le paramètre dwData est dans ce cas ignoré, mettez y le nombre 0. Cette constante est généralement utilisée quand l'utilisateur quitte le programme.

Parfois l'utilisateur a besoin d'aide sur l'utilisation d'un contrôle spécifique et c'est parfois pénible d'aller dans le menu "Aide", de cliquer sur "Sommaire de l'aide" et ensuite de rechercher la rubrique qui correspond à une description du contrôle. Vous pouvez éviter tout ce parcours à l'utilisateur en utilisant la propriété HelpContextID de vos contrôles pour un accès rapide à l'aide de ceux-ci.

La valeur que vous donnez à la propriété HelpContextID d'un contrôle est l'Identificateur Contextuel de la rubrique qui correspond à ce contrôle. L'identificateur contextuel d'une rubrique est un nombre associé à la rubrique et défini dans la section [MAP] du fichier .HPJ.

A l'exécution, lorsque c'est votre contrôle qui aura le focus et que l'utilisateur pressera sur F1, le fichier d'aide se chargera et affichera la rubrique correspondante.

NOTEZ aussi que vous devez d'abord définir une référence au fichier d'aide de l'application dans votre projet avant d'utiliser cette technique ! Pour définir une référence au fichier d'aide:

A défaut de définir la propriété HelpContextID de chaque contrôle, vous pouvez aussi utiliser leur propriété WhatsThisHelpID. Lorsque vous définissez cette propriété, l'utilisateur peut avoir accès à l'aide du contrôle en cliquant sur le bouton WhatsThis (?) de la fenêtre et en cliquant ensuite sur le contrôle.

La seule différence entre la propriété HelpContextID et la propriété WhatsThisHelpID est que WhatsThisHelpID ouvre la rubrique associée au contrôle dans une fenêtre style Pop-Up alors que HelpContextID ouvre la rubrique dans une fenêtre normale.

Pour insérer le bouton WhatsThis dans la barre de titre d'une fenêtre, mettez la propriété WhatsThisButton de la feuille à True. Assurez vous aussi que la propriété BorderStyle de la feuille soit Fixed Single ou Fixed Dialog, autrement le bouton ne s'affiche pas !

Et si vous ne l'avez pas encore déviné depuis, la valeur que vous donnez à la propriété WhatsThisHelpID d'un contrôle est l'Identificateur Contextuel de la rubrique qui correspond à ce contrôle. Remarquez aussi que même les menus possèdent cette propriété...

Notez toujours que vous devez d'abord définir une référence au fichier d'aide de l'application dans votre projet avant d'utiliser cette technique !

Notez aussi que si vous définissez en même temps la propriété HelpContextID et WhatsThisHelp d'un contrôle, c'est la rubrique spécifiée dans WhatsThisHelp qui s'affichera en Pop-up lorsque vous presserez sur F1.

Afin ne pas laisser cette section vide, remarquons qu'en même que la fonction API WinHelp est la seule fonction API que vous trouverez pour gérer éfficacement l'aide sous Windows.

Pour vous accompagner dans la lecture, voici l'ensemble des programmes et listings présentés dans cet article.