Gestion par défaut de l'aide F1 dans les applications VCL

De RAD Studio
Aller à : navigation, rechercher

Remonter à Appel de l'aide HTML depuis les applications

Le moyen standard d'activer l'aide dans les applications est d'appuyer sur F1. L'EDI de RAD Studio supporte les options appropriées permettant de définir les paramètres d'aide pour la génération automatique de code pour l'activation de l'aide invoquée par l'appui sur F1. Dans ce cas, RAD Studio génère automatiquement le code par défaut nécessaire à l'exécution d'un appel approprié à la fonction de gestion de l'aide invoquée par l'appui sur F1 dans les applications VCL.

Cette rubrique décrit comment définir les paramètres des appels aux fonctions de gestion d'aide et comment ces appels sont exécutés. Notez que la discussion suivante s'applique seulement aux applications d'interface utilisateur graphique VCL.

Paramètres d'aide à définir

Quand vous appuyez sur F1, l'événement OnHelp déclenche la fiche détenant la focalisation. Par conséquent, votre application exécute le gestionnaire d'événements par défaut de l'événement OnHelp. L'EDI génère le code du gestionnaire d'événements OnHelp en utilisant les paramètres d'aide spécifiés. Dans l'EDI, vous pouvez spécifier les paramètres d'aide HelpFile, HelpType, HelpContext et HelpKeyword qui sont décrits dans les sections suivantes.

HelpFile

Tout d'abord, vous devez spécifier les fichiers d'aide qui contiennent les rubriques d'aide pour votre application. Vous pouvez spécifier un ou plusieurs fichiers d'aide. Vous pouvez spécifier le fichier d'aide principal pour une application en utilisant la propriété TApplication.HelpFile de l'objet Application global et aussi un fichier d'aide personnel pour chaque fiche, en utilisant la propriété TForm.HelpFile de l'objet Fiche correspondant.

Vous pouvez spécifier ces HelpFiles à la conception sous la forme de propriétés d'EDI correspondantes, utilisées pour définir par programme les propriétés HelpFile des objets correspondants.

Le moyen habituel de désigner le fichier d'aide principal pour une application est d'utiliser la propriété HelpFile de l'objet Application global.

Ouvrez la boîte de dialogue Options de projet (Projet > Options) et sélectionnez la page Apparence (sous Application). Dans l'option Fichier d'aide, spécifiez le fichier d'aide. Cliquez sur Parcourir. Par défaut, la boîte de dialogue Fichier d'aide de l'application présente seulement les fichiers avec l'extension .hlp. Pour spécifier d'autres types de fichiers d'aide, sélectionnez le type Tous les fichiers (*.*) dans le contrôle Fichiers de type. Vous serez ensuite capable de sélectionner des fichiers d'aide de types tels que .CHM, .HTML, et d'autres.

Cette option définit la propriété Application.HelpFile. Cette propriété définit le fichier d'aide principal de l'application. Quand l'application reçoit une commande de gestion d'aide, elle utilise par défaut ce fichier d'aide pour exécuter la commande d'aide.

Pour spécifier un fichier d'aide individuel pour une fiche particulière, vous pouvez utiliser la propriété HelpFile de cette fiche.

Dans le Concepteur de fiches, sélectionnez votre fiche. L'inspecteur d'objets présente les propriétés de cette fiche, comme dans la figure suivante :

HelpFile

Dans la colonne de droite de la propriété HelpFile, spécifiez Form1.chm. Cela définit la propriété TForm.HelpFile de l'objet Form1. Cette propriété définit le fichier d'aide Form1.chm pour la fiche Form1 particulière.

L'application recherche généralement le fichier d'aide dans le répertoire à partir duquel le fichier exécutable de l'application s'exécute. Par conséquent, si le fichier d'aide spécifié se trouve dans un autre répertoire, vous devez alors spécifier le chemin relatif à ce fichier. Par exemple, vous pouvez spécifier .\Help\Form1.chm.

Le gestionnaire d'événements OnHelp par défaut utilise le fichier d'aide spécifié dans la propriété HelpFile de la fiche détenant la focalisation. Si la propriété TForm.HelpFile contient une chaîne vide, le gestionnaire d'événements utilise alors le fichier d'aide spécifié dans la propriété HelpFile de l'objet Application global.

HelpType, HelpContext et HelpKeyword

Pour générer le code du gestionnaire d'événements par défaut pour l'événement OnHelp, l'EDI doit connaître la rubrique d'aide à afficher. Les valeurs des propriétés HelpContext et HelpKeyword peuvent définir la rubrique à afficher. La propriété HelpType définit laquelle de ces deux propriétés utiliser.

Dans l'inspecteur d'objets relatif à la fiche, cliquez sur la colonne de droite de la propriété HelpType. Si vous sélectionnez la valeur htContext, la valeur spécifiée dans la propriété HelpContext est alors utilisée. Si vous sélectionnez la valeur htKeyword, la valeur spécifiée dans la propriété HelpKeyword est alors utilisée.

Que faut-il ajouter au code généré

Les applications développées avec RAD Studio utilisent les visionneuses d'aide externes pour afficher les différents types de fichiers d'aide. Vous devez indiquer à votre application la visionneuse d'aide externe à utiliser.

Wrappers de visionneuses d'aide externes

La VCL a été conçue pour être indépendante de la visionneuse d'aide externe. Toutes les fonctionnalités d'aide utilisées par les gestionnaires d'événements d'aide par défaut sont déclarées dans les interfaces de l'unité System.HelpIntfs. La VCL fournit les packages qui contiennent les classes implémentant ces interfaces avec une visionneuse d'aide externe particulière (qui gère le type particulier de fichiers d'aide). Par exemple, l'unité Vcl.HtmlHelpViewer implémente un wrapper pour l'API de HTMLHelp pour la visionneuse de fichiers d'aide CHM (Aide Microsoft HTML).

Cette indépendance (à partir de visionneuses d'aide externes) signifie que vous avez seulement besoin de spécifier l'unité appropriée -- en fournissant l'implémentation des interfaces HelpIntfs pour une visionneuse d'aide externe particulière -- dans la section uses. Par exemple, vous pouvez spécifier l'unité Vcl.HtmlHelpViewer pour visualiser les fichiers d'aide CHM.

Par exemple, avec les propriétés traitées ci-dessus (HelpFile, HelpType, HelpContext et HelpKeyword) définies, le gestionnaire d'événements OnHelp par défaut peut utiliser la fonction de gestion d'aide comme ceci :

IHelpSystem.ShowContextHelp(Form1.HelpContext, Form1.HelpFile);

si HelpType = htContext, et comme ceci :

IHelpSystem.ShowHelp(Form1.HelpKeyword, Form1.HelpFile);

si HelpType = htKeyword. Ici IHelpSystem est l'interface déclarée dans l'unité HelpIntfs.

Accéder aux visionneuses d'aide externes

Les sections suivantes décrivent comment IHelpSystem et les autres interfaces, déclarées dans l'unité HelpIntfs, sont implémentées par les classes dans une unité qui fournit un wrapper pour une visionneuse d'aide externe. Par exemple, examinez l'unité Vcl.HtmlHelpViewer qui fournit un wrapper pour l'API de la fonction HTMLHelp. L'unité Vcl.HtmlHelpViewer implémente la classe THTMLHelpViewer qui fournit une implémentation pour les interfaces de l'unité HelpIntfs. Toutefois, la classe THTMLHelpViewer est déclarée dans la section implementation de l'unité. Par conséquent, vous devez comprendre comment les membres de cette classe sont accessibles hors de l'unité Vcl.HtmlHelpViewer.

L'unité HelpIntfs fournit deux fonctions globales : RegisterViewer et GetHelpSystem. Ces fonctions ont les déclarations suivantes :

function RegisterViewer(const newViewer: ICustomHelpViewer; out Manager: IHelpManager): Integer;
function GetHelpSystem(out System: IHelpSystem): Boolean;

La section d'initialisation de l'unité Vcl.HtmlHelpViewer exécute les deux appels suivants :

HelpViewer := THtmlHelpViewer.Create;
HelpIntfs.RegisterViewer(HelpViewerIntf, HelpViewer.FHelpManager);

Ces appels créent un objet de type THtmlHelpViewer et recensent l'objet visionneuse d'aide externe encapsulé en tant qu'objet du gestionnaire du système d'aide -- HelpViewer.FHelpManager -- de type IHelpManager.

Pour invoquer la visionneuse d'aide externe recensée, le code peut appeler la fonction simple HelpIntfs.GetHelpSystem, qui peut accéder à l'objet stocké dans HelpViewer.FHelpManager, puis renvoie un objet de type IHelpManager dans l'objet de type IHelpSystem. TApplication a la propriété HelpSystem qui fournit aussi un accès à cet objet de type IHelpSystem, par lequel les méthodes de TApplication appellent les fonctions de la visionneuse d'aide. Les objets de type IHelpSystem fournissent IHelpSystem.ShowContextHelp, IHelpSystem.ShowHelp, et d'autres fonctions d'aide. Le gestionnaire d'événements OnHelp par défaut et le code utilisateur peuvent appeler ces fonctions.

Etapes pour l'affichage de l'aide F1

Quand vous appuyez sur F1, l'application active le gestionnaire d'événements par défaut pour l'événement OnHelp de la fiche détenant la focalisation. Les sections précédentes de cette rubrique ont abordés les aspects théoriques de la définition des propriétés d'aide dans l'inspecteur d'objets et l'ajout du code nécessaire à l'activation de la page d'aide adéquate.

Pour vous exercer, utilisez les étapes suivantes.

Pour afficher l'aide F1

  1. Définissez la propriété HelpFile de l'objet Application global (la propriété TApplication.HelpFile) ou de fiches particulières (la propriété TForm.HelpFile). Par exemple, vous pouvez définir :
TForm.HelpFile = Form1.chm
  1. Pour une fiche particulière, sélectionnez la propriété HelpType et définissez htContext ou htKeyword. Par exemple, vous pouvez définir
TForm.HelpType = htContext
Définissez ensuite la valeur ContextID adéquate dans la propriété TForm.HelpContext. ContextID doit être un entier identifiant une rubrique du fichier d'aide spécifié par HelpFile. Par exemple, dans le cas de fichiers d'aide CHM, vous devez mapper les IDs de contexte symboliques des rubriques d'aide sur les valeurs ContextID numériques de la section [MAP] de votre fichier projet (.hhp). Par exemple, définissez
TForm.HelpContext = 714
Désormais, l'appui sur F1 affiche la rubrique avec le ContextID égal à 714 d'un fichier d'aide CHM identifié dans HelpFile.
Sinon, définissez
TForm.HelpType = htKeyword
Définissez ensuite la valeur Keyword adéquate dans la propriété TForm.HelpKeyword. Désormais, l'appui sur F1 affiche la rubrique ayant la valeur Keyword spécifiée comme la valeur de sa balise Alink.
  1. Dans les applications Delphi, ajoutez l'unité Vcl.HtmlHelpViewer à la clause uses du module principal de votre application.
    Dans les applications C++, ajoutez la directive #include Vcl.HtmlHelpViewer.hpp.
    Ajoutez#pragma package(smart_init) et #pragma link "Vcl.HtmlHelpViewer"
    Cela définit que votre application utilise l'API de la fonction HTMLHelp qui affiche les fichiers d'aide CHM..
  2. Sélectionnez la commande Exécuter > Exécuter. Votre application s'ouvre.
  3. Sélectionnez la fiche Form1. Appuyez sur F1. Le gestionnaire d'événements OnHelp par défaut, généré automatiquement, affiche la rubrique d'aide spécifiée par la valeur HelpContext (ou HelpKeyword) du fichier d'aide .CHM spécifié.

Notez qu'aucune programmation manuelle n'a été nécessaire. Toute la gestion de l'aide invoquée par l'appui sur F1 a été implémentée automatiquement. Vous avez seulement à spécifier les paramètres d'aide adéquats en utilisant l'inspecteur d'objets.

Voir aussi