IdentifiantMot de passe
Loading...
Mot de passe oublié ?Je m'inscris ! (gratuit)

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


précédentsommairesuivant

III. Intégration du fichier d'aide CHM conçu dans une application Delphi

III-A. Principes généraux de l'utilisation de l'aide avec Delphi 6

Par défaut, Delphi ne gère pas les appels à l'aide 32 bits, seuls les appels 16 bits sont pris en compte. Sans modification des procédures d'appel, vous ne pourrez donc ouvrir que des fichiers HLP.

Lors d'un appui sur la touche F1, touche par défaut pour ouvrir l'aide, Delphi est informé par Windows du déclenchement d'un message de type WM_HELP (ou autres de la même famille), et vous permet de traiter ce message via le gestionnaire d'évènement OnHelp (propriété dans l'inspecteur d'objet) de type THelpEvent.

 
Sélectionnez
type THelpEvent = function (HelpType: THelpType; HelpContext: integer; HelpKeyword: string;
                            HelpFile: string; var Handled: boolean): boolean of object;
property OnHelp: THelpEvent;

Il est possible de gérer cet évènement au niveau de chaque form (TCustomForm.OnHelp), ou alors globalement au niveau de l'application (TApplication.OnHelp).

Afin de permettre à votre application d'ouvrir des fichiers d'aide 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 standards de l'aide vers des appels aux API qui traitent les fichiers CHM 32 bits.

Image non disponible

III-B. Mise en pratique pas à pas de l'intégration du fichier d'aide dans Delphi 6

Dans toute cette rubrique, je ne m'attarderai pas sur les portions de code qui sont communes à toute application Delphi, mais je détaillerai les portions de code propres aux appels à l'aide CHM. Ne vous inquiétez pas, les sources livrées avec ce tutoriel sont commentées. ;-)

En début de tutoriel, je vous ai montré l'interface finale du projet 'Sample'. Afin que vous puissiez comprendre les portions de code que je vais vous expliquer, regardez la composition de la form principale nommée 'fMain' :

Image non disponible

III-B-1. Unités à intégrer à votre projet

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é :

 
Sélectionnez
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é :

 
Sélectionnez
unit fMain;
interface
uses
Windows, ......, D6OnHelpFix;

III-B-2. Gestion de l'ouverture de l'aide CHM par appui sur la touche 'F1'

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 :

 
Sélectionnez
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 :

 
Sélectionnez
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 :

 
Sélectionnez
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 :

Image non disponible

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.

Image non disponible

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.

Image non disponible

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… :-)

III-B-3. Gestion de l'ouverture de l'aide CHM par clic sur un élément de menu

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 :

Image non disponible

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 :

 
Sélectionnez
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 :

 
Sélectionnez
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…

 
Sélectionnez
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…


précédentsommairesuivant

Copyright © 2003 Stéphane Vaillant. Aucune reproduction, même partielle, ne peut être faite de ce site ni de l'ensemble de son contenu : textes, documents, images, etc. sans l'autorisation expresse de l'auteur. Sinon vous encourez selon la loi jusqu'à trois ans de prison et jusqu'à 300 000 € de dommages et intérêts.