Programmieren von WinHelp-Funktionen

Sie können Ihre Anwendung so programmieren, dass Benutzer die Möglichkeit haben, auf Ihr Hilfesystem in der Microsoft-Hilfe zuzugreifen. Ein Hilfesystem kann aus einer oder mehreren Dateien bestehen. Dem Benutzer erscheint das Hilfesystem jedoch als Teil Ihrer Anwendung.

Mit den Befehlen SET HELP TO und SET TOPIC TO oder mit der WinHelp-Funktion, die in diesem Abschnitt beschrieben wird, können Sie eine grafische Hilfe bzw. eine Hilfe im DBF-Format in eine Visual FoxPro-Anwendung einbinden. SET HELP TO gibt hierbei den Namen der benutzerdefinierten Hilfedatei für die Anwendung an. SET TOPIC TO legt das kennzeichnende Schlüsselwort für ein Thema in der benutzerdefinierten Hilfedatei fest.

Verwenden der WinHelp-Funktion

Eine andere Möglichkeit, innerhalb Ihrer Anwendung auf die Hilfe zuzugreifen, ist durch die WinHelp-Funktion gegeben. Die WinHelp-Funktion ist ein Teil der Windows-API (Application Programming Interface, Schnittstelle für Anwendungsprogrammierung). Die WinHelp-Funktion ist nur auf der Windows-Plattform verfügbar.

Die WinHelp-Funktion kann zusätzlich zur HelpContextID-Eigenschaft eingesetzt werden, z. B., um eine zweite Hilfedatei aufzurufen.

Tipp   Wenn Sie SET HELP TO, HELP ID und SET TOPIC TO verwenden, braucht die WinHelp-Funktion nicht verwendet zu werden.

Verwenden der WinHelp-Funktion

1. Definieren Sie die zu übergebenden Befehlsparameter in Ihrer Anwendung.

   Eine Beschreibung dieser Parameter finden Sie weiter unten in diesem Abschnitt unter "Der wCmd-Parameter".

2. Legen Sie die Bibliothek mit SET LIBRARY TO fest und definieren Sie die verwendeten Variablen. Dies erfolgt normalerweise im Initialisierungscode für die Hauptdatei der Anwendung.

   SET LIBRARY TO SYS(2004) + "FOXTOOLS.FLL" ADDITIVE
   Help = RegFn("Help", "LCIC", "I")
   

   Als Bibliothek muss Foxtools.fll festgelegt werden. SYS(2004) gibt das Visual FoxPro-Stammverzeichnis zurück, in dem sich die Datei Foxtools.fll befindet.

   Wenn Sie ein Hilfethema durch Senden des entsprechenden K-Schlüsselwortes aufrufen möchten, definieren Sie mit RegFn( ) eine Variable wie die Variable Help im oben genannten Beispiel. Wenn Sie ein Hilfethema anhand der zugewiesenen Nummer öffnen möchten, definieren Sie mit RegFn eine Variable wie die Variable HelpI im oben genannten Beispiel und verwenden für dwData statt einer Zeichenfolge eine Nummer. Wenn Sie Nummern übergeben, müssen Sie diese im Abschnitt [MAP] der HPJ-Datei den eindeutigen Kontextzeichenfolgen zuordnen, die mit den Rautenfußnoten (#) festgelegt werden.

3. Verwenden Sie CallFn( ) zum Aufrufen der Funktion.

   Wenn Ihre Hilfedatei z. B. den Namen Myhelpfile.hlp hat, können Sie ein Hilfethema in Myhelpfile.hlp über das entsprechende K-Schlüsselwort aufrufen:

   #define HELP_KEY 0x0101
   wCmd = HELP_KEY
   cFilename = Myhelpfile.hlp"
   dwData = "Add Menu Items at Run Time"
   CallFn(Help, MainHWND(), cFileName, wCmd, dwData)
   

Näheres zu den FoxTools-Funktionen finden Sie in Foxtools.chm im Verzeichnis Vfp98\Tools.

Festlegen von WinHelp-Parametern

Mit den folgenden Parametern werden Optionen für die WinHelp-Funktion festgelegt.

Der hWnd-Parameter

Der hWnd-Parameter kennzeichnet das Fenster, das die Hilfe anfordert. Die Hilfe verwendet diesen Bezeichner, um rückverfolgen zu können, von welchen Anwendungen die Hilfe angefordert wurde. In Visual FoxPro verwenden Sie für den hWnd-Parameter die MainHWND( )-Funktion, die in der Bibliothek Foxtools.fll enthalten ist.

Das lpzFileName-Argument

Das lpzFileName-Argument ist eine Zeichenfolge, mit der ein gültiger Pfad und ein Dateiname für die Hilfedatei angegeben wird, die das gewünschte Thema enthält. Die Zeichenfolge wird als Wert übergeben.

Der wCmd-Parameter

Der wCmd-Parameter legt entweder die Art der Suche fest oder zeigt an, dass die Anwendung die Hilfe nicht länger benötigt. Für den Parameter können die folgenden Werte gesetzt werden.

Der dwData-Parameter

Mit dem dwData-Parameter wird das Thema übergeben, für das die Anwendung Hilfe anfordert. Inhalt und Format dieses Parameters sind von dem Wert für wCmd abhängig, der beim Aufruf der WinHelp-Funktion von der Anwendung übergeben wird.

In den meisten Fällen wird das dwData-Argument als Wert übergeben. In Visual FoxPro ist dies die Standardeinstellung.

Je nach den gegebenen Umständen kann dwData in der vorhergehenden Zeile entweder eine Zeichenfolge mit einem zu suchenden Schlüsselwort oder einen numerischen Wert mit einer Kontextnummer für ein bestimmtes Thema beinhalten.

In der folgenden Liste wird für jeden Wert von wCmd das entsprechende Format für dwData angegeben*.*

Da mit der WinHelp-Funktion entweder eine Kontextnummer oder ein Schlüsselwert angegeben werden kann, unterstützt diese Funktion sowohl kontextbezogene Hilfe als auch Suchläufe nach Themen in der Hilfedatei.

Anmerkung   Wenn eine Hilfedatei zwei oder mehr Indizes enthält, muss die Anwendung einen Index als Standardindex festlegen. Um zu gewährleisten, dass der korrekte Index eingestellt bleibt, sollte die Anwendung die Hilfe mit dem wCmd-Parameter, auf HELP_SETINDEX gesetzt, aufrufen (wobei dwData den entsprechenden Kontextbezeichner angibt). Nach jedem Aufruf der Hilfe sollte ein Befehl mit der Parametereinstellung HELP_CONTEXT folgen. Verwenden Sie auf keinen Fall HELP_INDEX mit HELP_SETINDEX.

Reservieren der F1-Taste für die Hilfe

Wenn der Benutzer in Ihrer Anwendung die F1-Taste drückt, kann Visual FoxPro ein kontextbezogenes Hilfethema anzeigen. Hierzu weisen Sie einer Hilfekontextnummer ein Thema in Ihrer Hilfetabelle zu und geben diese Nummer als Wert für die HelpContextID-Eigenschaft des Formulars bzw. des Steuerelements ein. Wenn das Formular oder das Steuerelement den Fokus besitzt und der Benutzer die F1-Taste drückt, zeigt Visual FoxPro das entsprechende Hilfethema an.

Anmerkung   Standardmäßig ist die F1-Taste für die kontextbezogene Hilfe aktiviert. Da es sich hierbei um einen anerkannten Standard für die Hilfe handelt, wird empfohlen, diese Tastenzuordnung nicht zu verändern.

Einfügen von Hilfeschaltflächen in Formularen

Wenn Sie in Ihren Formularen eine Hilfeschaltfläche vorsehen, wird der Zugriff auf die Hilfe noch weiter vereinfacht. Dies ist insbesondere dann sinnvoll, wenn es sich bei den Benutzern um Neueinsteiger handelt.

Festlegen eines Kontextbezugs und Hinzufügen einer Hilfeschaltfläche

1. Geben Sie im Init-Ereignis des Formulars als HelpContextID-Eigenschaft für alle Formularobjekte den gleichen Wert ein, den Sie dem Hilfethema zugewiesen haben. Wenn diese Nummer z. B. den Wert 7 hat, können Sie den folgenden Befehl verwenden:

   THIS.SetAll("HelpContextID", 7)
   

2. Fügen Sie in Ihr Formular eine Befehlsschaltfläche ein.

3. Geben Sie für die Caption-Eigenschaft der Schaltfläche Hilfe ein.

4. Fügen Sie im Click-Ereignis der Befehlsschaltfläche den folgenden Befehl ein:

   HELP ID THIS.HelpContextID
   

   Tipp   Speichern Sie die Hilfeschaltfläche als Klasse, um sie später zu anderen Formularen hinzufügen zu können. Weitere Informationen zum Speichern von Objekten als Klassen finden Sie unter Erstellen von Formularen.

Verlassen der Hilfe

Bei der Hilfe-Anwendung handelt es sich um eine gemeinsam genutzte Ressource, die allen Windows-Anwendungen zur Verfügung steht. Da die Hilfe auch eine eigenständige Anwendung darstellt, kann der Benutzer sie auch wie jede andere Anwendung ausführen. Ihre Anwendung hat demzufolge nur eine beschränkte Kontrolle über die Hilfe-Anwendung.

Zwar kann Ihre Anwendung das Hilfe-Anwendungsfenster nicht direkt schließen, sie kann aber der Hilfe-Anwendung anzeigen, dass die Hilfe nicht länger benötigt wird. Vor dem Schließen des Hauptfensters sollte Ihre Anwendung daher die Hilfe mit dem wCmd-Parameter HELP_QUIT aufrufen. Hiermit wird der Hilfe angezeigt, dass Ihre Anwendung sie nicht mehr benötigt.

Eine Anwendung, die im Verlauf ihrer Ausführung die Hilfe aufgerufen hat, muss vor dem Beenden der Anwendung die Hilfe mit dem wCmd-Parameter HELP_QUIT aufrufen.

Wenn eine Anwendung mehr als eine Hilfedatei öffnet, muss zum Verlassen der Hilfe-Anwendung die WinHelp-Funktion für jede dieser Dateien aufgerufen werden.

Wenn eine Anwendung oder eine DLL (Dynamic-Link Library) eine Hilfedatei geöffnet hat, die entsprechende Instanz der Hilfe-Anwendung aber nicht länger aktiv sein soll, muss die Anwendung oder DLL die Hilfe mit dem wCmd-Parameter HELP_QUIT aufrufen, um diese Instanz der Hilfe-Anwendung zu beenden.

Anmerkung   Vor dem Schließen sollte eine Anwendung oder DLL immer die Hilfe für alle geöffneten Hilfedateien aufrufen. Eine Hilfedatei ist dann geöffnet, wenn die Hilfe zuvor mit dem entsprechenden Namen der Hilfedatei aufgerufen wurde.

Die Hilfe-Anwendung bleibt so lange geöffnet, bis alle Fenster, die bis dahin die Hilfe aufgerufen haben, die Hilfe mit dem wCmd-Parameter HELP_QUIT beenden. Wenn eine Anwendung nicht alle Hilfe-Instanzen beendet, bleibt die Hilfe-Anwendung auch dann geöffnet, wenn alle Anwendungen, die bis dahin Hilfe angefordert haben, beendet wurden.

Siehe auch

Implementieren der WinHelp-Direkthilfe | Hinzufügen von Kontextbezügen zur WinHelp | Erstellen der grafischen Hilfe | SET HELP TO | SET TOPIC TO | SET LIBRARY TO | WinHelp 4.0 | Erstellen von Hilfe im DBF-Format