Comment : spécifier un fichier d'aide pour votre composant
Mise à jour : novembre 2007
Dans la plupart des cas, il est conseillé de laisser les développeurs qui utilisent votre composant activer l'aide à l'exécution. Toutefois, dans certains cas, il peut être judicieux de permettre au composant d'afficher de l'aide HTML au moment où il est appelé. Il est possible de fournir de l'aide HTML pour des composants au moyen de l'objet System.Windows.Forms.Help. Cet objet est une classe statique qui encapsule le moteur HTML Help 1.x. Cette classe ne peut pas être instanciée, et ses méthodes doivent être appelées directement. Pour afficher l'aide, appelez la méthode Help.ShowHelp. Cette méthode surchargée exige au moins deux arguments : le contrôle faisant office de contrôle parent de la boîte de dialogue Aide et l'URL du fichier d'aide. Le fichier d'aide peut être un fichier HTML Help 1.x compilé (.chm) ou un fichier HTML au format HTML Help.
Si vous projetez d'incorporer la prise en charge d'un fichier d'aide directement dans votre composant, vous disposez de deux options pour choisir le moment et la manière dont cette aide s'affichera :
L'option préconisée consiste à implémenter une méthode Help pouvant être appelée par l'application cliente. L'application cliente peut passer des paramètres à la méthode Help pour garantir que les rubriques adéquates seront affichées ; d'autre part, le développeur écrivant du code avec votre composant a le choix de ne pas utiliser l'aide.
La seconde option consiste à appeler la méthode ShowHelp en réponse aux conditions successives se produisant dans le code. Cette solution vous offre un plus grand contrôle sur le contenu de l'aide et sur le moment auquel elle s'affiche, mais elle limite considérablement la marge de manœuvre des futurs développeurs qui utiliseront votre composant.
Pour spécifier et afficher un fichier d'aide pour votre composant
Créez et compilez le fichier d'aide .chm.
S'il n'existe pas encore de référence à l'espace de noms System.Windows.Forms dans votre composant, ajoutez-en une.
Créez une méthode publique pour afficher l'aide. Cette méthode doit offrir aux développeurs un moyen facile de spécifier l'aide qu'ils doivent afficher.
' This method takes parameters from the client application that allow ' the developer to specify when Help is displayed. Public Sub DisplayHelp (ByVal parent as System.Windows.Forms.Control, _ ByVal topic as MyHelpEnum) ' The file to display is chosen by the value of the topic ' parameter. Select Case topic Case MyHelpEnum.enumWidgets Windows.Forms.Help.ShowHelp(parent, "C:\Help\Widgets.chm") Case MyHelpEnum.enumMechanisms ' Insert code to implement additional functionality. End Select End Sub// This method takes parameters from the client application that allow // the developer to specify when Help is to be shown. public void MyHelp(System.Windows.Forms.Control parent, myHelpEnum topic) { // The file to display is chosen by the value of the topic. switch (topic) { case myHelpEnum.enumWidgets: System.Windows.Forms.Help.ShowHelp(parent, " C:\\help\\widgets.chm "); break; case myHelpEnum.enumMechanism: // Insert code to implement additional functionality. break; } }