Standardbehandlung von F1-Hilfe in VCL-Anwendungen

Aus RAD Studio
Wechseln zu: Navigation, Suche

Nach oben zu Aufrufen von HTML-Hilfe aus Anwendungen

Das Drücken von F1 ist das Standardvorgehen zum Aktivieren von Hilfe in Anwendungen. Die IDE von RAD Studio unterstützt Optionen zur Definition von Hilfeparametern für die automatische Erzeugung von Code zur Aktivierung der Hilfe beim Drücken von F1. In diesem Fall erzeugt RAD Studio automatisch den Standardcode, der zum Ausführen eines entsprechenden Aufrufs der Hilfebehandlungsfunktion beim Drücken von F1 in VCL-Anwendungen erforderlich ist.

In diesem Thema wird die Definition von Parametern für Aufrufe der Hilfebehandlungsfunktionen und die Ausführung dieser Aufrufe beschrieben. Die folgenden Erläuterungen beziehen sich ausschließlich auf VCL-GUI-Anwendungen.

Erforderliche Hilfeparameter

Beim Drücken von F1 wird in dem Formular, das den Fokus hat, das Ereignis OnHelp ausgelöst. Die Anwendung führt als Ergebnis die Standard-Ereignisbehandlungsroutine des Ereignisses OnHelp aus. Die IDE erzeugt die OnHelp-Ereignisbehandlungsroutine mit den angegebenen Hilfeparametern. Sie können in der IDE die Hilfeparameter HelpFile, HelpType, HelpContext und HelpKeyword festlegen. Diese Parameter werden in den folgenden Abschnitten beschrieben.

HelpFile

Zunächst müssen Sie die Hilfedateien festlegen, die die Hilfethemen für Ihre Anwendung enthalten. Sie können eine oder mehrere Hilfedateien angeben. Die Haupthilfedatei für eine Anwendung kann mit der Eigenschaft TApplication.HelpFile des globalen Application-Objekts und individuelle Hilfedateien für einzelne Formulare können mit der Eigenschaft TForm.HelpFile des zugehörigen Form-Objekts festgelegt werden.

Diese HelpFile-Dateien können beim Entwurf als entsprechende IDE-Eigenschaften für die programmseitige Definition der HelpFile-Eigenschaften des zugehörigen Objekts angegeben werden.

Normalerweise wird einer Anwendung die Haupthilfedatei über die Eigenschaft HelpFile des globalen Application-Objekts zugewiesen.

Öffnen Sie das Dialogfeld Projektoptionen (Projekt > Optionen), und wählen Sie die Seite Erscheinungsbild (unter Anwendung) aus. Geben Sie in das Feld Hilfedatei die Hilfedatei ein. Klicken Sie auf Durchsuchen. Das Dialogfeld Hilfedatei der Anwendung zeigt per Vorgabe nur die Dateien mit der Erweiterung .hlp an. Zum Festlegen von anderen Hilfedateitypen wählen Sie im Steuerelement Dateitypen den Typ Alle Dateien (*.*) aus. Anschließend können Sie Hilfedateien der Typen .CHM, .HTML und andere auswählen.)

Diese Option setzt die Eigenschaft Application.HelpFile. Diese Eigenschaft definiert die Haupthilfedatei für die Anwendung. Wenn die Anwendung einen Hilfebehandlungsbefehl empfängt, führt sie standardmäßig den Hilfebefehl mit dieser Hilfedatei aus.

Eine einzelne Hilfedatei für ein bestimmtes Formular können Sie mit der Eigenschaft HelpFile dieses Formulars festlegen.

Wählen Sie im Formular-Designer das Formular aus; im Objektinspektor werden die Eigenschaften dieses Formulars (siehe die folgende Abbildung) angezeigt:

HelpFile

Geben Sie in der rechten Spalte der Eigenschaft HelpFile den Namen Form1.chm ein. Damit wird die Eigenschaft TForm.HelpFile des Objekts Form1 definiert. Diese Eigenschaft setzt die Hilfedatei Form1.chm für das Formular Form1.

Die Anwendung sucht in der Regel die Hilfedatei in dem Verzeichnis, aus dem die ausführbare Datei der Anwendung ausgeführt wird. Wenn die angegebene Hilfedatei sich in einem anderen Verzeichnis befindet, sollten Sie daher den relativer Pfad zu dieser Datei angeben. Sie könnten beispielsweise .\Help\Form1.chm angeben.

Die OnHelp-Standard-Ereignisbehandlungsroutine verwendet die in der Eigenschaft HelpFile des Formulars mit dem Fokus angegebene Hilfedatei. Wenn die Eigenschaft TForm.HelpFile einen leeren String enthält, dann verwendet die Ereignisbehandlungsroutine die in der Eigenschaft HelpFile des globalen Application-Objekts angegebene Hilfedatei.

HelpType, HelpContext und HelpKeyword

Zum Erzeugen des Codes für die Standard-Ereignisbehandlungsroutine des Ereignisses OnHelp muss die IDE über das anzuzeigende Hilfethema informiert sein. Die Werte der Eigenschaften HelpContext und HelpKeyword können definieren, welches Thema angezeigt werden soll. Die Eigenschaft HelpType definiert, welche dieser beiden Eigenschaften verwendet werden soll.

Klicken Sie im Objektinspektor für das Formular mit der rechten Maustaste in die rechte Spalte der Eigenschaft HelpType. Wenn Sie den Wert htContext auswählen, dann wird der in der Eigenschaft HelpContext angegebene Wert verwendet. Bei dem Wert htKeyword wird der in der Eigenschaft HelpKeyword angegebene Wert verwendet.

Ergänzen des erzeugten Codes

Mit RAD Studio entwickelte Anwendungen verwenden zur Anzeige verschiedener Typen von Hilfedateien externe Hilfe-Viewer. Sie müssen Ihrer Anwendung mitteilen, welcher externe Hilfe-Viewer verwendet werden soll.

Wrapper von externen Hilfe-Viewern

Die VCL ist unabhängig von externen Hilfe-Viewer. Alle von den Standard-Ereignisbehandlungsroutinen der Hilfe verwendeten Hilfefunktionen sind in Interfaces der Unit System.HelpIntfs deklariert. Die VCL stellt Packages mit Klassen bereit, die diese Interfaces mit einem bestimmten externen Hilfe-Viewer (für den speziellen Typ der Hilfedatei) implementieren. Beispielweise implementiert die Unit Vcl.HtmlHelpViewer für die Viewer von CHM-Hilfedateien (Microsoft HTML Help) einen Wrapper für die HTMLHelp-API.

Diese Unabhängigkeit (von externen Hilfe-Viewern) bedeutet, dass Sie nur in der uses-Klausel die geeignete Unit angeben müssen, die die Implementierung der HelpIntfs-Interfaces für einen bestimmten externen Hilfe-Viewer bereitstellt. Sie können beispielsweise die Unit Vcl.HtmlHelpViewer' zur Anzeige von CHM-Hilfedateien angeben.

Wenn Sie die Eigenschaften HelpFile, HelpType, HelpContext und HelpKeyword definiert haben, kann die OnHelp-Standard-Ereignisbehandlungsroutine die Hilfebehandlungsfunktion folgendermaßen verwenden: 

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

Bei HelpType = htContext wie folgt: 

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

Bei HelpType = htKeyword. Hier ist IHelpSystem das in der Unit HelpIntfs deklariert Interface.

Zugreifen auf externe Hilfe-Viewer

In den folgenden Abschnitten wird die Implementierung von IHelpSystem und anderen in der Unit HelpIntfs deklarierten Interfaces durch Klassen in einer Unit erläutert, die einen Wrapper für einen externen Hilfe-Viewer bereitstellt. Die Unit Vcl.HtmlHelpViewer enthält beispielsweise einen Wrapper für die HTMLHelp-Funktions-API. Die Unit 'Vcl.HtmlHelpViewer implementiert die Klasse THTMLHelpViewer, die eine Implementierung für Interfaces aus der Unit HelpIntfs bereitstellt. Die Klasse THTMLHelpViewer ist aber im implementation-Abschnitt der Unit deklariert. Deshalb müssen Sie wissen, wie auf Member dieser Klasse von außerhalb der Unit Vcl.HtmlHelpViewer zugegriffen werden kann.

Die Unit HelpIntfs enthält zwei globale Funktionen: RegisterViewer und GetHelpSystem. Diese Funktionen haben die folgenden Deklarationen: 

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

Im initialization-Abschnitt der Unit Vcl.HtmlHelpViewer werden die folgenden Aufrufe ausgeführt: 

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

Diese Aufrufe erstellen ein Objekt vom Typ THtmlHelpViewer und registrieren das gekapselte externe Hilfe-Viewer-Objekt als ein Hilfesystem-Managerobjekt (HelpViewer.FHelpManager) vom Typ IHelpManager.

Zum Aufrufen des registrierten externen Hilfe-Viewers kann im Code die Funktion HelpIntfs.GetHelpSystem aufgerufen werden, die auf das im HelpViewer.FHelpManager gespeicherte Objekt zugreift und dann ein IHelpManager-Typobjekt im Typobjekt IHelpSystem zurückgibt. TApplication hat die Eigenschaft HelpSystem, die auch den Zugriff auf dieses IHelpSystem-Typobjekt ermöglicht, über das TApplication-Methoden die Hilfe-Viewer-Funktionen aufrufen. IHelpSystem-Typobjekte stellen unter anderem die Hilfefunktionen IHelpSystem.ShowContextHelp und IHelpSystem.ShowHelp bereit. Diese Funktionen können von der Standard-Ereignisbehandlungsroutine OnHelp und dem Benutzercode aufgerufen werden.

Schritte für die Anzeige der F1-Hilfe

Wenn Sie F1 drücken, aktiviert die Anwendung die Standard-Ereignisbehandlungsroutine für das Ereignis OnHelp des Formulars mit dem Fokus. In den vorherigen Abschnitten dieses Themas wurden die theoretischen Aspekte des Setzens der Hilfeeigenschaften im Objektinspektor und das Hinzufügen des zur ordnungsgemäßen Aktivierung der Hilfeseite erforderlichen Codes behandelt.

Befolgen Sie zum Umsetzen dieser theoretischen Aspekte in die Praxis die folgenden Schritte.

So zeigen Sie die F1-Hilfe an:

  1. Setzen Sie die Eigenschaft HelpFile des globalen Application-Objekts (die Eigenschaft TApplication.HelpFile) oder eines bestimmten Formulars (die Eigenschaft TForm.HelpFile). Zum Beispiel:
TForm.HelpFile = Form1.chm
  1. Wählen Sie für ein bestimmtes Formular die Eigenschaft HelpType aus, und setzen Sie htContext oder htKeyword. Zum Beispiel:
TForm.HelpType = htContext
Setzen Sie dann in der Eigenschaft TForm.HelpContext den entsprechenden ContextID-Wert. ContextID sollte ein Integerwert sein, der ein Thema in der in HelpFile angegebenen Hilfedatei festlegt. Bei CHM-Hilfedateien müssen Sie beispielsweise im [MAP]-Abschnitt Ihrer Projektdatei (.hhp) symbolische Kontext-IDs von Hilfethemen zu numerischen ContextID-Werten zuordnen. Zum Beispiel:
TForm.HelpContext = 714
Durch Drücken von F1 wird nun das Thema mit der ContextID714 aus einer in HelpFile angegebenen CHM-Hilfedatei angezeigt.
Oder:
TForm.HelpType = htKeyword
Setzen Sie dann in der Eigenschaft TForm.HelpKeyword den entsprechenden Keyword-Wert. Durch Drücken von F1 wird nun das Thema angezeigt, dessen Alink-Tag-Wert mit dem angegebenen Keyword-Wert übereinstimmt.
  1. In Delphi-Anwendungen fügen Sie der uses-Klausel des Hauptmoduls Ihrer Anwendung die Unit Vcl.HtmlHelpViewer hinzu.
    In C++-Anwendungen fügen Sie die Direktive #include Vcl.HtmlHelpViewer.hpp hinzu.
    Fügen Sie #pragma package(smart_init) und #pragma link "Vcl.HtmlHelpViewer" hinzu.
    Damit wird definiert, dass Ihre Anwendung die API der Funktion HTMLHelp verwendet, die die CHM-Hilfedateien anzeigt.
  2. Wählen Sie den Befehl Start > Start. Ihre Anwendung wird geöffnet.
  3. Wählen Sie das Formular Form1 aus. Drücken Sie F1. Die automatisch erzeugte Standard-Ereignisbehandlungsroutine OnHelp zeigt das im HelpContext- (oder HelpKeyword-)Wert in der festgelegten .CHM-Hilfedatei angegebene Thema an.

Hierbei war keine manuelle Programmierung erforderlich. Die gesamte Behandlung für das Drücken von F1 wurde automatisch implementiert. Sie müssen nur die passenden Hilfeparameter im Objektinspektor eingeben.

Siehe auch

Abgerufen von „https://docwiki.embarcadero.com/RADStudio/Sydney/d/index.php?title=Standardbehandlung_von_F1-Hilfe_in_VCL-Anwendungen&oldid=209028“