Behandeln der Onlinehilfe

Onlinehilfe kann in einer Vielzahl von Formen verfügbar sein, von detaillierten konzeptuellen Informationen bis hin zu schnellen Definitionen. Dieses Thema enthält folgende Abschnitte:

Informationen zur Hilfe

Ein wichtiges Element einer benutzerfreundlichen Anwendung ist direkt in der Onlinehilfe verfügbar. Windows stellt Funktionen und Meldungen bereit, die die Implementierung von Onlinehilfe in Ihrer Anwendung erleichtern, wenn sie in Verbindung mit der Windows Help-Anwendung verwendet werden. In dieser Übersicht werden die Elemente von Windows erläutert, die Onlinehilfe unterstützen. Es wird beschrieben, wie diese Elemente verwendet werden, um Benutzern die Möglichkeit zu geben, Hilfe anzufordern, und es wird erläutert, wie sie die Windows-Hilfeanwendung verwenden, um Hilfe anzuzeigen.

Hilfeanfragen

Die meisten Windows-basierten Anwendungen bieten Onlinehilfeinformationen in einer Vielzahl von Formen, von konzeptioneller Hilfe, die den Zweck der Funktionen einer Anwendung erläutert, bis hin zu Popuphilfe, die schnelle Definitionen einzelner Elemente auf der Benutzeroberfläche der Anwendung bereitstellt. Sie verwenden Funktionen und Nachrichten, um Benutzern eine Vielzahl von Möglichkeiten zum Anfordern des Zugriffs auf diese Informationen zu bieten. In den folgenden Abschnitten werden diese Hilfeanfragen beschrieben.

Menü "Hilfe"

Die meisten Anwendungen bieten Benutzern Zugriff auf Hilfeinformationen, indem sie ein Hilfemenü in das Hauptfenster einschließen. Wenn der Benutzer ein Element aus einem Hilfemenü auswählt, empfängt die entsprechende Fensterprozedur eine WM _ COMMAND-Meldung, die das ausgewählte Element identifiziert. Die Anwendung reagiert, indem sie die entsprechenden Hilfeinformationen anzeigt, z. B. eine Liste mit Hilfethemen, einen Index oder eine Einführung in die Anwendung.

Hilfe über die Tastatur

Windows bietet Benutzern Zugriff auf Hilfeinformationen über die Tastatur, indem die Anwendung benachrichtigt wird, wenn der Benutzer die TASTE F1 drückt. Das System sendet eine _ WM-HILFEmeldung an das Fenster, das den Tastaturfokus hatte, als der Benutzer die TASTE gedrückt hat. Wenn das Fenster ein untergeordnetes Fenster ist (z. B. ein Steuerelement in einem Dialogfeld), übergibt die DefWindowProc-Funktion die Meldung an das übergeordnete Fenster. Wenn ein Menü aktiv ist, wenn F1 gedrückt wird, sendet das System die Meldung an das Fenster, das dem Menü zugeordnet ist. Die Anwendung reagiert, indem hilfeinformationen angezeigt werden, die dem Fenster, Steuerelement oder Menü zugeordnet sind, das den Fokus besitzt oder aktiv ist. Wenn der Benutzer beispielsweise ein Steuerelement in einem Dialogfeld auswählt und F1 drückt, zeigt die Anwendung Hilfeinformationen für dieses Steuerelement an.

Der lParam-Parameter von WM _ HELP ist ein Zeiger auf eine HELPINFO-Struktur, die ausführliche Informationen über das Element enthält, für das Hilfe angefordert wird. Anhand dieser Informationen bestimmen Sie das anzuzeigende Hilfethema. Die HELPINFO-Struktur enthält auch die Koordinaten des Mauszeigers zum Zeitpunkt, zu dem der Benutzer die Taste gedrückt hat. Sie können diese Informationen verwenden, um Hilfe basierend auf der Position des Mauszeigers bereitzustellen.

Hilfe mit der Maus

Windows bietet dem Benutzer Zugriff auf Hilfeinformationen mit der Maus, indem die Anwendung benachrichtigt wird, wenn der Benutzer nach dem Klicken auf die Schaltfläche Frage (?) mit der rechten Maustaste oder auf ein Fenster, Steuerelement oder Menü klickt. Die Anwendung antwortet, indem hilfeinformationen angezeigt werden, die dem angegebenen Fenster, Steuerelement oder Menü zugeordnet sind.

Das System sendet eine WM _ CONTEXTMENU-Nachricht, wenn der Benutzer mit der rechten Maustaste klickt. Das Fenster, auf das geklickt wurde, empfängt die Meldung. Wenn das Fenster ein untergeordnetes Fenster ist, z. B. ein Steuerelement, übergibt die DefWindowProc-Funktion die Meldung an das übergeordnete Fenster. Die WM _ CONTEXTMENU-Nachricht gibt die Koordinaten des Mauszeigers an. Die x-Koordinate befindet sich im Niedrigordnungswort des lParam-Parameters, und die y-Koordinate befindet sich im Wort in hoher Reihenfolge. Wenn der Benutzer auf ein Steuerelement geklickt hat, ist der wParam-Parameter das Handle für das Steuerelement, das den Klick empfangen hat.

Das System sendet eine _ WM-HILFEmeldung, wenn der Benutzer auf ein Element in einem Fenster klickt, nachdem er auf die Schaltfläche Frage (?) geklickt hat, die in der Titelleiste des Fensters angezeigt wird. Sie können einer Titelleiste eine Frageschaltfläche hinzufügen, indem Sie beim Erstellen des Fensters den WS _ EX _ CONTEXTHELP-Stil in der CreateWindowEx-Funktion angeben. Der lParam-Parameter von WM _ HELP ist ein Zeiger auf eine HELPINFO-Struktur, die ausführliche Informationen über das Element enthält, für das Hilfe angefordert wird, einschließlich der Koordinaten des Mauscursors zum Zeitpunkt, zu dem der Benutzer auf die Maustaste geklickt hat.

Die Schaltfläche Frage wird nur für die Verwendung in Dialogfeldern empfohlen. In der Vergangenheit haben Anwendungen Benutzern Zugriff auf Hilfeinformationen zu einem Dialogfeld gewährt, indem sie eine Hilfeschaltfläche im Dialogfeld bereitgestellt haben. Diese Methode wird nicht mehr empfohlen. Verwenden Sie stattdessen die Schaltfläche Frage.

Hilfeanzeige und Windows Hilfe

Sobald eine Anwendung eine Hilfeanfrage erhält, sollte sie die entsprechenden Hilfeinformationen anzeigen. Da die Windows Help-Anwendung eine konsistente Benutzeroberfläche bietet, wird empfohlen, dass Anwendungen anstelle anderer Methoden Windows Hilfe verwenden. Um Windows Hilfe zum Anzeigen von Hilfeinformationen zu leiten, verwendet eine Anwendung die WinHelp-Funktion und gibt Details wie die anzuzeigenden Informationen und die Form des Fensters an, in dem sie angezeigt werden soll. In den folgenden Abschnitten wird erläutert, wie Sie mit WinHelp Hilfeinformationen anzeigen.

Hilfedateien

Um Hilfeinformationen anzuzeigen, müssen Sie beim Aufrufen der WinHelp-Funktion eine Hilfedatei angeben. Die Hilfedatei muss das Dateiformat Windows Hilfe (.hlp) und mindestens ein Thema aufweisen. Jedes Thema ist eine unterschiedliche Informationseinheit, z. B. eine konzeptionelle Beschreibung, eine Reihe von Anweisungen, ein Bild, eine Glossardefinition usw. Themen müssen eindeutig identifiziert werden, damit Windows Hilfe sie finden kann, wenn sie angefordert werden. Intern verwendet Windows Hilfe Themenbezeichner, um Themen zu suchen, aber Anwendungen verwenden am häufigsten Kontextbezeichner (eindeutige ganzzahlige Werte), um die anzuzeigenden Themen anzugeben. Der Ersteller der Hilfedatei muss Kontextbezeichner explizit Themenbezeichnern im [ ] MAP-Abschnitt der Projektdatei zuordnen, die zum Erstellen der Hilfedatei verwendet wird.

Wenn Sie eine Hilfedatei angeben, aber keinen Pfad angeben, sucht WinHelp im Hilfeverzeichnis oder in einem von der PATH-Umgebungsvariablen angegebenen Verzeichnis nach der Hilfedatei. Darüber hinaus kann WinHelp eine Hilfedatei suchen, deren Name im folgenden Registrierungsspeicherort aufgeführt ist:

HKEY_LOCAL_MACHINE
   Software
      Microsoft
         Windows
            Help

Um die Registrierung nutzen zu können, müssen Sie einen Wertnamen erstellen, der den gleichen Namen wie Ihre Hilfedatei hat. Der diesem Namen zugewiesene Wert muss das Verzeichnis sein, in dem sich die Hilfedatei befindet.

Wenn WinHelp die angegebene Hilfedatei nicht finden kann, wird ein Dialogfeld angezeigt, in dem der Benutzer den Speicherort der Hilfedatei angeben kann. Da WinHelp die Standortinformationen in der Registrierung speichert, wird nicht erneut nach dem Speicherort derselben Hilfedatei gefragt.

Weitere Informationen zum Erstellen und Erstellen einer Hilfedatei finden Sie in der Dokumentation zu Ihren Entwicklungstools.

Starten Windows Hilfe

Im folgenden Beispiel wird die WinHelp-Funktion verwendet, um die Windows-Hilfeanwendung zu starten und die Hilfedatei in ihrem Thema Inhalt zu öffnen.

HWND hwnd;     // main window handle 
BOOL bResult   // for checking Boolean function result 

bResult = WinHelp(hWnd, "WINNT.HLP", HELP_CONTENTS, 0L);

Im nächsten Beispiel wird die Benutzerhilfedatei geöffnet, die Datei nach dem Thema durchsucht, das einer Schlüsselwortzeichenfolge zugeordnet ist, und dann wird das Thema angezeigt.

HWND hwnd;     // main window handle 
BOOL bResult   // for checking Boolean function result 

bResult = WinHelp(hWnd, "WINNT.HLP", HELP_KEY, (DWORD) "finding topics");

Dialogfeld "Hilfethemen"

Sie können das Dialogfeld Hilfethemen anzeigen, indem Sie die WinHelp-Funktion mit dem HELP _ FINDER-Befehl aufrufen. Im Dialogfeld Hilfethemen können Benutzer anzuzeigende Themen auswählen, indem sie die Titel der Themen, die den Themen zugeordneten Schlüsselwörter oder die Wörter und Ausdrücke in den Themen anzeigen. Anwendungen zeigen dieses Dialogfeld in der Regel an, wenn der Benutzer im Menü Hilfe einen Befehl wie Hilfethemen ausgibt. Eine Anwendung kann dieses Dialogfeld auch anzeigen, wenn der Benutzer die Taste drückt, wenn kein bestimmtes Fenster, Steuerelement oder Menü in der Anwendung den Fokus hat oder aktiv ist.

In der Vergangenheit haben Anwendungen die Befehle HELP _ CONTENTS und HELP _ INDEX mit der WinHelp-Funktion verwendet, um das Thema Inhalt und den Schlüsselwortindex der Hilfedatei anzuzeigen. Diese Befehle werden nicht mehr empfohlen. Verwenden Sie stattdessen den Befehl HELP _ FINDER.

Informationsthemen

Sie können ein bestimmtes Thema anzeigen, indem Sie die WinHelp-Funktion mit dem _ HELP CONTEXT-Befehl aufrufen und den Kontextbezeichner für das Thema angeben. Anwendungen verwenden in der Regel den Befehl HELP _ CONTEXT als Reaktion auf Benutzeranforderungen für Themen, die konzeptionelle Informationen oder prozedurale Hilfe enthalten, anstatt Informationen zu einem bestimmten Steuerelement oder Menü. In solchen Fällen kann der Benutzer die Hilfedatei weiter durchsuchen und nach verwandten Informationen suchen, bevor er zur Anwendung zurückkehrt.

Der _ HELP CONTEXT-Befehl ruft eine reguläre Instanz von Windows Help auf, sodass der Benutzer andere Themen in der Hilfedatei finden kann. In der Regel wird das Hauptfenster Hilfe angezeigt, das eine Titelleiste, ein Systemmenü, Schaltflächen zum Minimieren und Maximieren, ein Hauptmenü, eine optionale Navigationsleiste, einen Größenrahmen und einen Clientbereich enthält. Der Text des ausgewählten Themas wird im Clientbereich angezeigt, und der Benutzer kann mithilfe von hot-Links oder Navigationsschaltflächen im Hauptfenster durch die Hilfedatei navigieren. Die reguläre Instanz von Windows Hilfe kann auch verwendet werden, um Hilfe in einem oder mehreren sekundären Fenstern anstelle des Hauptfensters anzuzeigen.

Popupthemen

Sie können ein Popupthema anzeigen, das Informationen zu einem bestimmten Steuerelement oder Menü enthält, indem Sie die WinHelp-Funktion mit dem _ Help WM _ HELP- oder HELP _ CONTEXTMENU-Befehl aufrufen. Diese Befehle zeigen ein Thema in einem Popupfenster in der Nähe des entsprechenden Steuerelements oder Menüs an. Damit der Benutzer sofort wieder in der Anwendung arbeiten kann, wird das Popupfenster zerstört, sobald der Benutzer eine Taste drückt oder mit der linken Maustaste klickt.

Sie verwenden den _ HELP WM _ HELP-Befehl, wenn Sie WM _ HELP-Meldungen für Steuerfenster verarbeiten. Da die meisten Steuerelemente die WM _ HELP-Nachricht an die DefWindowProc-Funktion übergeben, verarbeitet die entsprechende Dialogfeldprozedur (oder übergeordnete Fensterprozedur) diese Meldung. Anstatt einen bestimmten Kontextbezeichner zu geben, muss die Dialogfeldprozedur ein Array von Steuerelement- und Kontextbezeichnerpaaren zusammen mit dem Steuerelementhandle, das im hItemHandle-Member der HELPINFO-Struktur angegeben ist, das mit der WM _ HELP-Nachricht übergeben wird, an WinHelp übergeben. Die Funktion bestimmt den Bezeichner des Steuerelements, für das die WM _ HELP-Nachricht generiert wurde, und verwendet den übereinstimmenden Kontextbezeichner, um das entsprechende Thema anzuzeigen.

Sie verwenden den Befehl HELP _ CONTEXTMENU, wenn Sie WM _ CONTEXTMENU-Nachrichten verarbeiten. Da die meisten Steuerelemente die WM _ CONTEXTMENU-Nachricht an die DefWindowProc-Funktion übergeben, verarbeitet die entsprechende Dialogfeldprozedur (oder übergeordnete Fensterprozedur) diese Meldung. Die Prozedur gibt ein Array von Steuerelement- und Kontextbezeichnerpaaren an. Außerdem wird das Handle im wParam-Parameter beim Aufrufen von WinHelp angegeben, damit die Funktion den entsprechenden Kontextbezeichner aus dem Array auswählen und das entsprechende Thema anzeigen kann. Im Gegensatz zum Help WM HELP-Befehl zeigt HELP CONTEXTMENU zunächst den Befehl _ _ What es _ This? (Was ist das?) in einem Menü an. Wenn der Benutzer den Befehl auswählt, zeigt WinHelp das Thema an. Andernfalls wird die Anforderung abgebrochen.

Sie können Popupthemen auch anzeigen, indem Sie den Befehl HELP CONTEXTPOPUP verwenden und einen _ Kontextbezeichner des Themas angeben. Dieser Befehl ähnelt dem Befehl HELP CONTEXT, ruft jedoch die Popupinstanz von Windows Help, die von HELP WM HELP und _ _ HELP _ _ CONTEXTMENU verwendet wird. Anwendungen können diesen Befehl als Reaktion auf WM _ HELP-Meldungen verwenden, um Hilfe für Menüs und Fenster anzuzeigen, die keine Steuerelemente in einem Dialogfeld sind. Um diesen Befehl am effektivsten zu verwenden, sollte die Anwendung diesen Menüs und Fenstern Kontextbezeichner zuweisen.

Sie können einem beliebigen Fenster oder Menü in der Anwendung einen Kontextbezeichner zuweisen. Wenn eine WM _ HELP-Nachricht generiert wird, schließt das System den Kontextbezeichner in die HELPINFO-Struktur ein, der in der WM HELP-Nachricht an das übergeordnete Fenster _ übergeben wird. Das übergeordnete Fenster kann dann den Kontextbezeichner an WinHelp übergeben, um das angeforderte Hilfethema anzuzeigen.

Sie verwenden die Funktion SetWindowContextHelpId, um einem Fenster oder Steuerelement einen Kontextbezeichner zu zuweisen, und die SetMenuContextHelpId-Funktion, um einem Menü einen Kontextbezeichner zu zuweisen. Sie können den Kontextbezeichner für ein Fenster oder Menü mithilfe der Funktion GetWindowContextHelpId oder GetMenuContextHelpId abrufen.

Schlüsselwortsuchen

Sie können dem Benutzer das Suchen und Anzeigen von Themen ermöglichen, indem Sie Themen in der Hilfedatei Schlüsselwörter zuweisen. Ein Schlüsselwort ist einfach eine Zeichenfolge, die einem oder mehrere Themen zugeordnet ist. Windows Die Hilfe sammelt alle Schlüsselwörter in einer Hilfedatei, platziert sie in einer Tabelle und zeigt sie in der Indexliste des Dialogfelds Hilfethemen an. Wenn der Benutzer ein Schlüsselwort auswählt, zeigt die Windows-Hilfe das zugeordnete Hilfethema oder, wenn dem Schlüsselwort mehrere Themen zugeordnet sind, eine Liste von Themen an, aus denen der Benutzer auswählen kann.

In einer Anwendung können Sie den Befehl HELP KEY, HELP PARTIALKEY oder HELP MULTIKEY mit der _ _ _ WinHelp-Funktion verwenden, um Hilfethemen basierend auf ganzen oder partiellen Schlüsselwörtern zu suchen und anzuzeigen. Sie geben den Befehl, die Schlüsselwortzeichenfolge, die Hilfedatei und das Handle für das Besitzerfenster an. Wenn eine einzelne Übereinstimmung gefunden wird, zeigt WinHelp in allen Fällen das entsprechende Thema an. Wenn mehrere Übereinstimmungen gefunden werden, zeigt die Funktion das Dialogfeld Themen gefunden an, und der Benutzer kann auswählen, welches Thema angezeigt werden soll. Wenn keine Übereinstimmung gefunden wird, zeigt WinHelp entweder die Indexliste (für HELP KEY und HELP PARTIALKEY) oder eine Fehlermeldung _ an _ (für HELP _ MULTIKEY).

Ihre Anwendung kann in einem einzigen Aufruf von WinHelp nach mehreren Schlüsselwörtern suchen, indem sie die Schlüsselwörter durch Semikolons trennt. (Die Suche nach mehreren Schlüsselwörtern wird nicht für Hilfedateien unterstützt, die für Windows 3 erstellt wurden. x) Es kann auch in mehreren Hilfedateien nach Schlüsselwörtern suchen, wenn die angegebene Hilfedatei über eine Contents(.cnt)-Datei mit den Befehlen :Index oder :Link verfügt. Mit dem Befehl HELP KEY sucht WinHelp in allen Dateien, die von diesen _ Befehlen angegeben werden, nach Schlüsselwörtern. Mit den Befehlen HELP MULTIKEY und HELP PARTIALKEY durchsucht die Funktion alle Dateien außer den dateien, die _ _ von :Link-Befehlen angegeben werden.

Standardmäßig erkennt Windows Hilfe nur die Schlüsselworttabelle, die durch das Fußnotenzeichen K in der Hilfequellendatei identifiziert wird. Sie können die Windows, um zusätzliche Schlüsselworttabellen zu erstellen, indem Sie in der Hilfequellendatei ein anderes Fußnotenzeichen als K mit der Schlüsselwortdefinition hinzufügen. (Das Fußnotezeichen A ist jedoch reserviert.) Sie müssen beim Erstellen der Hilfedatei zusätzliche Schlüsselworttabellen mithilfe von MULTIKEY-Anweisungen im Abschnitt OPTIONS der [ ] Projektdatei definieren.

Eine Anwendung kann den Befehl HELP SETINDEX mit der WinHelp-Funktion verwenden, um Windows Help an die Anzeige einer anderen Schlüsselworttabelle als K in der _ Indexliste zu richten. Um Windows hilfe an die Suche nach einem Schlüsselwort in einer alternativen Schlüsselworttabelle zu richten, kann eine Anwendung den Befehl HELP _ MULTIKEY verwenden. Sie geben das Schlüsselwort und die Schlüsselworttabelle in einer MULTIKEYHELP-Struktur an, die Sie an WinHelp übergeben.

Wenn WinHelp ein Thema anzeigt, wird es in dem Fenster angezeigt, das durch die Fußnote ">" für das Thema angegeben wird, in dem fenster, das durch den Befehl :Base in der Inhaltsdatei angegeben wird, oder im Hauptfenster. Wenn das Hauptfenster bereits für eine andere Hilfedatei geöffnet ist, wenn Sie WinHelp aufrufen, blendet die Funktion das Hauptfenster während der Suche aus. In diesem Fall wird das Hauptfenster durch Abbrechen der Dialogfelder Gefundene Themen und Hilfethemen geschlossen.

Sekundäre Hilfefenster

Das Hauptfenster der Windows-Hilfeanwendung wird als primäres Fenster bezeichnet. Windows Hilfe kann auch Hilfethemen in einem sekundären Fenster anzeigen. Im Gegensatz zum primären Hilfefenster enthält ein sekundäres Fenster keine Menüleiste. Sie können eine Navigationsleiste in ein sekundäres Fenster hinzufügen und der Leiste Schaltflächen hinzufügen. Sie können auch festlegen, dass Windows Hilfe automatisch die Höhe des sekundären Fensters an das Thema anpassen soll.

Sie müssen sekundäre Fenster im Windows-Abschnitt Ihrer Hilfeprojektdatei definieren und dabei den Namen und optional die Anfangsgröße und [ ] -position jedes Fensters angeben. Sie können die Windows-Hilfeanwendung anfügen, um ein Thema in einem sekundären Fenster anzuzeigen, indem Sie eine eckige Klammer (>) und den Namen, den Sie für das sekundäre Fenster definiert haben, an den Namen der Hilfedatei anfügen. Die resultierende Zeichenfolge wird dann an die WinHelp-Funktion übergeben.

Eine Anwendung kann die Größe und Position eines primären oder sekundären Fensters ändern, indem die Adresse einer HELPWININFO-Struktur und der HELP SETWINPOS-Befehl in einem Aufruf von _ WinHelp angegeben werden. HELPWININFO gibt den Namen des Fensters und seine neue Größe und Position an.

Hilfe zur Trainingskarte

Mithilfe der Trainingskartenhilfe kann eine Anwendung eine Abfolge von Anweisungen anzeigen, um den Benutzer durch die Schritte einer Aufgabe zu führen. Eine Trainingskarte besteht in der Regel aus Text, der einen bestimmten Schritt erläutert, und Schaltflächen, die TCard-Makros zugeordnet sind, mit denen der Benutzer der Anwendung mitteilen kann, was als Nächstes zu tun ist. Trainingskarten können nur in sekundären Fenstern angezeigt werden und dürfen keine hot-Links zu anderen Themen in der Hilfedatei enthalten.

Eine Anwendung initiiert die Trainingskarteninstanz von Windows Help, indem sie die WinHelp-Funktion aufruft und den Help TCARD-Befehl in Kombination mit einem anderen Befehl _ wie HELP CONTEXT _ ankn.) Wenn der Benutzer anschließend auf eine Schaltfläche in der Trainingskarte klickt, auf einen Hotspot klickt, der dem TCard-Makro zugewiesen ist, oder die Trainingskarte schließt, benachrichtigt Windows Help die Anwendung durch Senden einer _ WM-TCARD-Nachricht. Der wParam-Parameter identifiziert die Schaltfläche oder Benutzeraktion, und der lParam-Parameter enthält zusätzliche Daten, deren Bedeutung vom Wert von wParam abhängt.

Abbrechen der Hilfe

Windows Hilfe erfordert, dass eine Anwendung die Hilfe explizit abbricht, damit sie alle Ressourcen frei geben kann, die zum Nachverfolgen der Anwendung und ihrer Hilfedateien verwendet werden. Die Anwendung kann dies jederzeit tun, indem sie die WinHelp-Funktion aufruft und den BEFEHL HELP _ QUIT anknt. Beachten Sie, dass dies nicht für die Popupinstanz der Windows gilt. Eine Anwendung sollte nicht versuchen, eine Popupinstanz zu schließen.

Wenn eine Anwendung WinHelpaufruft, muss sie die Hilfe abbrechen, bevor sie ihr Hauptfenster schließt (z. B. als Reaktion auf die WM DESTROY-Nachricht im _ Hauptfensterprozedur). Eine Anwendung muss WinHelp nur einmal aufrufen, um die Hilfe abzubricht, unabhängig davon, wie viele Hilfedateien sie geöffnet hat. Windows Die Hilfe wird so lange ausgeführt, bis alle Anwendungen oder DLLs die Hilfe abgebrochen haben.

Um die Trainingskarteninstanz von Windows Hilfe zu schließen, müssen Sie beim Aufrufen von WinHelp die Befehle HELP TCARD und _ HELP _ QUIT angeben. Eine Anwendung muss die Trainingskarteninstanz von Windows Hilfe nicht abbrechen, wenn der Benutzer sie zuerst abbricht. Windows Die Hilfe benachrichtigt eine Anwendung, wenn der Benutzer die Trainingskarteninstanz abbricht, indem sie die _ WM-TCARD-Nachricht mit dem parameter wParam sendet, der auf IDCLOSE festgelegt ist.

Verwenden der Hilfe

In diesem Abschnitt wird gezeigt, wie Sie kontextorientierte Hilfe für ein Dialogfeld bereitstellen und die Darstellung eines sekundären Hilfefensters festlegen.

Bereitstellen von Hilfe in einem Dialogfeld

Um kontextorientierte Hilfe in einem Dialogfeld zu bieten, müssen Sie ein Array erstellen, das aus Paaren von DWORD-Werten besteht. Der erste Wert in jedem Paar ist der Bezeichner eines Steuerelements im Dialogfeld, der zweite der Kontextbezeichner des Hilfethemas für das Steuerelement. Das Array sollte ein Bezeichnerpaar für jedes Steuerelement im Dialogfeld enthalten.

Die Dialogfeldprozedur muss die WM _ HELP- und WM _ CONTEXTMENU-Meldungen verarbeiten. Das Dialogfeldprozedur empfängt WM _ HELP, wenn der Benutzer die Taste drückt, und WM _ CONTEXTMENU, wenn der Benutzer mit der rechten Maustaste klickt.

Der lParam-Parameter von WM _ HELP enthält die Adresse einer HELPINFO-Struktur. Der hItemHandle-Member dieser Struktur identifiziert das Steuerelement, für das der Benutzer Hilfe angefordert hat. Sie müssen dieses Handle zusammen mit dem Help WM HELP-Befehl, dem Namen Ihrer Hilfedatei und einem Zeiger auf das Array von Bezeichnern an die WinHelp-Funktion _ _ übergeben. Die WinHelp-Funktion durchsucht das Array nach dem Steuerelementbezeichner des angegebenen Steuerelements und ruft dann den entsprechenden Hilfekontextbezeichner ab. Als Nächstes übergibt die Funktion den Hilfekontextbezeichner an Windows Hilfe, die das entsprechende Thema findet und in einem Popupfenster anzeigt. Wenn das Steuerelement über den Bezeichner -1 verfügt, sucht das System nach dem nächsten Steuerelement, bei dem es sich um einen Tabstopp handelt, und verwendet dann seinen Bezeichner, um den Hilfekontextbezeichner zu finden. Aus diesem Grund ist es wichtig, statischen Text vor Steuerelementen in einer Ressourcendatei zu platzieren.

Beim Aufrufen der WinHelp-Funktion ähnelt die Verarbeitung von WM _ CONTEXTMENU der Verarbeitung von WM _ HELP mit diesen beiden Ausnahmen:

  • Sie übergeben den wParam-Parameter aus WM _ CONTEXTMENU.Dies ist das Handle für das Steuerelement, das die Nachricht gesendet hat.
  • Sie geben den Befehl HELP _ CONTEXTMENU anstelle von HELP WM HELP _ _ an.

Der Befehl _ HELP CONTEXTMENU bewirkt, Windows Hilfe ein Menü anzeigt, bevor das Hilfethema angezeigt wird. Das Menü ist systemdefiniert. Dadurch kann der Benutzer Hilfe für das Steuerelement oder das Dialogfeld Hilfethemen anzeigen.

Im folgenden Beispiel wird gezeigt, wie kontextorientierte Hilfe in einem Dialogfeld implementiert wird.

LRESULT CALLBACK EditDlgProc(HWND hwndDlg, UINT uMsg, 
                             WPARAM wParam, LPARAM lParam) 
{ 
    // Create an array of control identifiers and context identifiers. 
    static DWORD aIds[ ] = 
    { 
        ID_SAVE,   IDH_SAVE, 
        ID_DELETE, IDH_DELETE, 
        ID_COPY,   IDH_COPY, 
        ID_PASTE,  IDH_PASTE, 
        0,0 
    }; 

    switch (uMsg) 
    { 
        case WM_HELP: 
            WinHelp(((LPHELPINFO)lParam)->hItemHandle, "helpfile.hlp", 
                    HELP_WM_HELP, (DWORD)(LPSTR)aIds); 
            break; 

        case WM_CONTEXTMENU: 
            WinHelp((HWND)wParam, "helpfile.hlp", HELP_CONTEXTMENU, 
                    (DWORD)(LPVOID)aIds); 
            break; 
        
        // Process other messages here. 
    } 
    return FALSE; 
}

Festlegen der Darstellung eines sekundären Hilfefensters

Eine Anwendung kann die Größe, Position und den Status eines sekundären Hilfefensters festlegen, indem der HELP SETWINPOS-Befehl und die Adresse einer _ HELPWININFO-Struktur an die WinHelp-Funktion übergeben werden. Die Member von HELPWININFO geben den Namen des zu ändernden Fensters sowie die neue Größe, Position und den Status des Fensters an.

Im folgenden Beispiel wird die Darstellung eines sekundären Fensters mit dem Namen "wnd _ menu" (wnd-Menü) definiert. Der Name muss im Windows-Abschnitt [ ] der Hilfeprojektdatei definiert werden.

BOOL DoWindowSize(VOID) 
{ 
    HANDLE hhwi; 
    LPHELPWININFO lphwi; 
    WORD wSize; 
    char *szWndName = "wnd_menu"; 
    size_t NameLength;      // Does not include the terminating null character
    HRESULT hr
    BOOL retval;

    hr = StringCbLengthA(szWndName, STRSAFE_MAX_CCH, &NameLength);
    
    if (SUCCEEDED(hr))
    {
        // Add 1 to account for the name string's terminating null character.
        NameLength++;
        
        // The HELPWININFO structure contains a minimal TCHAR array of size [2] 
        // that is used for the window name. Since sizeof(HELPWININFO) 
        // includes those two TCHARS, they must be subtracted from the 
        // total when adding the actual string length to calculate the  
        // size of the structure. 
        wSize = sizeof(HELPWININFO) - 2 + NameLength; 
    }
    else
        // Something's amiss with the string.
        return FALSE;
        
    hhwi  = GlobalAlloc(GHND, wSize); 
    lphwi = (LPHELPWININFO)GlobalLock(hhwi); 

    lphwi->wStructSize = wSize; 
    lphwi->x    = 256;      // horizontal position 
    lphwi->y    = 256;      // vertical position 
    lphwi->dx   = 767;      // width 
    lphwi->dy   = 512;      // height 
    lphwi->wMax = SW_SHOW;  // show the window 
    
    // secondary window
    hr = StringCbCopyA(lphwi->rgchMember, sizeof(lphwi->rgchMember), szWndName);
    
    if (SUCCEEDED(hr))
    {
        WinHelp(hwnd, "myhelp.hlp", HELP_SETWINPOS, (DWORD)lphwi); 
     
        GlobalUnlock(hhwi); 
        GlobalFree(hhwi); 

        return TRUE; 
    }
    else
        // There was a problem copying the window name.
        return FALSE;
}