Conception d'un fichier d'aide HTML et intégration dans une application Delphi

Delphi 6 n'intégrant pas de bibliothèques de manipulation de fichiers CHM, un groupe de développeurs intéressé par les systèmes d'aide, The Helpware Group a conçu les unités suivantes :

• hh.pas >> Unité contenant toutes les déclarations nécessaires aux appels à l'aide CHM ;
• hh_funcs.pas >> Unité contenant toutes les fonctions d'appels à l'aide CHM.

Ces deux unités sont à intégrer dans la clause uses de votre projet ou de votre unité :

unit fMain;
interface
uses
Windows, ......, hh, hh_funcs;

De plus, Delphi 6 engendrant quelques erreurs de gestion de l'évènement OnHelp, Robert Chandler, membre de The Helpware Group, a développé un correctif (D6OnHelpFix.pas) qu'il faut aussi intégrer à la clause uses de votre projet ou de votre unité :

unit fMain;
interface
uses
Windows, ......, D6OnHelpFix;

Comme indiqué précédemment, pour ouvrir une aide CHM (32 bits), il est nécessaire d'implémenter un gestionnaire d'évènement pour l'évènement OnHelp qui permettra de rediriger les appels à l'aide 16 bits vers les appels à l'aide 32 bits.

La première étape consiste à créer un gestionnaire d'évènement pour l'évènement OnHelp.

Déclarez la fonction HelpHook dans la clause private de votre unité. Cette fonction doit avoir les mêmes paramètres que la fonction de gestion des appels à l'aide 16 bits :

unit fMain;
interface
...
type
...
private
  {Déclarations privées }
  function HelpHook(Command: Word; Data: LongInt; var CallHelp: Boolean): Boolean;
public
  {Déclarations publiques }
  mHelpFile: string; //Variable servant à stocker le chemin du fichier CHM
end;

Implémentez la fonction HelpHook de la manière suivante :

function TfrmMain.HelpHook(Command: Word; Data: Integer; var CallHelp: Boolean): Boolean;
begin
  CallHelp := False; //Désactivation des appels à l'aide 16 bits
  //Test sur le paramètre Command qui permet de savoir le type d'aide à ouvrir
  if (Command in [Help_Context]) then
    HtmlHelp(0, PChar(mHelpFile), HH_HELP_CONTEXT, Data) //Ouverture de l'aide
  else
    CallHelp := true; //En cas d'erreur, réactivation des appels à l'aide 16 bits
  result := true;
end;

Votre fonction créée, il faut maintenant rediriger tous les appels à l'aide 16 bits vers l'aide 32 bits. Pour cela, placez-vous sur la form principale (frmMain) et implémenter la procédure FormCreate :

procedure TfrmMain.FormCreate(Sender: TObject);
begin
  //Redirection des appels à l'aide 16 bits vers notre gestionnaire d'évènement
  Application.OnHelp := HelpHook;
  //Recherche du chemin du fichier d'aide
  mHelpFile := ExtractFilePath(ParamStr(0)) + 'sample.chm';
  mHelpFile := ExpandFileName(mHelpFile);
  if not FileExists(mHelpFile) then //Déclenché si le fichier d'aide est introuvable
    ShowMessage('Le fichier d''aide est introuvable !');
  //Vérification de la version de HTML Help installé dans le système
  if (hh.HHCtrlHandle = 0) 
     or (hh_funcs._hhMajVer < 4)
     or ((hh_funcs._hhMajVer = 4) and (hh_funcs._hhMinVer < 73)) then
    ShowMessage('Vous devez installer la version 1.2 ou supérieure de Microsoft HTML Help !');
end;

Désormais, tous vos appels seront traités par le gestionnaire d'évènement HelpHook.

Du point de vue de l'utilisateur final, cela signifie que, dès qu'il appuiera sur la touche 'F1', c'est votre fichier d'aide CHM qui s'affichera.

Cependant, l'appui sur la touche 'F1' doit pouvoir ouvrir la rubrique d'aide liée au composant dans lequel est situé le curseur de l'utilisateur. En l'occurrence, si l'utilisateur a placé son curseur dans la zone de saisie du nom (edNom) et appuie sur la touche 'F1', il peut s'attendre à voir la rubrique traitant de la saisie du nom.

Pour cela, vous allez utiliser trois propriétés classiques des composants standards, il s'agit des propriétés :

• HelpContext
• HelpKeyword
• HelpType

Revenons un peu en arrière… Lors de la création du fichier d'aide CHM, vous avez créé un fichier nommé sample.h, dans lequel étaient définis des alias et des helpcontext :

Ce sont ces informations que nous allons utiliser dans ces propriétés.

Il existe deux manières d'appeler une rubrique précise en fonction du contexte : on peut appeler l'aide par un identifiant (HelpContext) ou par un mot-clé (HelpKeyword).

Pour appeler la rubrique traitant de la saisie du nom par un identifiant, paramétrez la propriété HelpContext du composant edNom à '1002' qui correspond au numéro attribué dans le fichier sample.h.
Ensuite, vérifiez que la propriété HelpType est bien paramétrée à htContext.

Pour appeler la même rubrique par son mot-clé, paramétrez la propriété HelpKeyword du composant edNom à 'NOM' qui correspond à l'alias attribué dans le fichier sample.h.
Pensez à vérifier que la propriété HelpType est paramétrée à htKeyword.

Mettez à jour ces propriétés pour tous les composants pour lesquels vous avez créé une rubrique d'aide et testez votre application.

L'appui sur la touche 'F1' n'est pas la seule façon d'appeler l'aide… Il est possible de l'appeler à partir d'éléments de menus, c'est l'objet de la rubrique suivante… :-)

Dans votre application, vous avez placé un composant de type TMainMenu nommé mmSample pour les besoins du tutoriel. Observez les différents éléments du menu mmSample :

Ces trois éléments du menu '?' sont des éléments que l'on trouve dans la plupart des applications.

Vous allez tout d'abord gérer l'appel au sommaire de l'aide. Pour cela, double-cliquez sur l'élément 'Sommaire de l'aide' et implémentez la procédure de la façon suivante :

procedure TfrmMain.idxSommaireClick(Sender: TObject);
begin
  HtmlHelp(0, PChar(mHelpFile), HH_DISPLAY_TOC, 0); //HH_DISPLAY_TOC est l'appel au sommaire
end;

En cliquant sur cet élément, l'onglet 'Sommaire' et la page d'accueil de l'aide apparaissent….

Double-cliquez ensuite sur l'élément 'Index de l'aide' et implémentez la procédure de la manière suivante :

procedure TfrmMain.idxIndexClick(Sender: TObject);
begin
  HtmlHelp(0, PChar(mHelpFile), HH_DISPLAY_INDEX, 0); //HH_DISPLAY_INDEX est l'appel à l'index
end;

En cliquant sur cet élément, l'onglet 'Index' et la page d'accueil de l'aide apparaissent…

Enfin, il ne vous reste plus qu'à implémenter la procédure liée à l'élément 'Recherche dans l'aide' du menu.
Attention, pour afficher l'onglet 'Rechercher' de l'aide, il est nécessaire de définir une requête…

procedure TfrmMain.idxRechercheClick(Sender: TObject);
var
  q: THHFtsQuery; //Type interne à l'unité hh.pas 
begin
  //Définition de la requête
  with q do
  begin
    cbStruct := sizeof(q); //Taille de la requête
    fUniCodeStrings := false; //mettre à true si toute la chaîne recherchée est de type Unicode 
    pszSearchQuery := nil; //chaîne recherchée
    iProximity := HH_FTS_DEFAULT_PROXIMITY; //Recherche en respectant les mots similaires
    fStemmedSearch := false; //mettre à true pour rechercher dans les résultats précédents 
    fTitleOnly := false; //mettre à true si la recherche se fait uniquement sur les titres de rubriques
    fExecute := true; //mettre à true pour exécuter la requête
    pszWindow := nil; //type de fenêtre à afficher, ici c'est celle par défaut
  end;
  HtmlHelp(0, PChar(mHelpFile), HH_DISPLAY_SEARCH, DWORD(@q)); //HH_DISPLAY_SEARCH est l'appel à la recherche
end;

En cliquant sur cet élément, l'onglet 'Rechercher' et la page d'accueil de l'aide apparaissent…

Ce tutoriel est terminé…

Ces quelques éléments devraient vous aider à concevoir des aides au format CHM et d'apporter un côté professionnel à vos applications.

Regardez tout de même la dernière page, elle contient les sources complètes de ce tutoriel et différentes manières d'obtenir des informations complémentaires sur le même sujet…