Behandeln der Onlinehilfe
Onlinehilfe kann in einer Vielzahl von Formen verfügbar sein, von detaillierten konzeptionellen Informationen bis hin zu schnellen Definitionen. Dieses Thema enthält folgende Abschnitte:
Informationen zu Hilfe
Ein wichtiges Element einer benutzerfreundlichen Anwendung ist in der Onlinehilfe verfügbar. Windows bietet Funktionen und Nachrichten, die bei Verwendung in Verbindung mit der Windows-Hilfeanwendung die Implementierung von Onlinehilfe in Ihrer Anwendung vereinfachen. In dieser Übersicht werden die Elemente von Windows erläutert, die Onlinehilfe unterstützen. Es wird beschrieben, wie Sie diese Elemente verwenden, um Benutzern die Möglichkeit zu geben, Hilfe anzufordern, und es wird erläutert, wie Die Windows-Hilfeanwendung zum Anzeigen von Hilfe verwendet wird.
Hilfeanfragen
Die meisten Windows-basierten Anwendungen bieten Onlinehilfeinformationen in verschiedenen Formen, von konzeptioneller Hilfe, die den Zweck der Funktionen einer Anwendung erläutert, bis hin zu Popuphilfen, die schnelle Definitionen einzelner Elemente in der Benutzeroberfläche der Anwendung bereitstellen. Sie verwenden Funktionen und Nachrichten, um Benutzern verschiedene Möglichkeiten zu geben, zugriff auf diese Informationen anzufordern. In den folgenden Abschnitten werden diese Hilfeanfragen beschrieben.
Menü "Hilfe"
Die meisten Anwendungen bieten Benutzerzugriff auf Hilfeinformationen, indem sie ein Hilfemenü im Standard-Fenster 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 antwortet, indem sie die entsprechenden Hilfeinformationen anzeigt, z. B. eine Liste mit Hilfethemen, einen Index oder eine Einführung in die Anwendung.
Hilfe von der Tastatur
Windows bietet Benutzern Zugriff auf Informationen über die Tastatur, indem es die Anwendung benachrichtigt, wenn der Benutzer die F1-Taste drückt. Das System sendet eine WM_HELP Nachricht 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 Nachricht an das übergeordnete Fenster. Wenn ein Menü aktiv ist, wenn F1 gedrückt wird, sendet das System die Nachricht 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 hat 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 detaillierte Informationen zu dem Element enthält, für das Hilfe angefordert wird. Sie verwenden diese Informationen, um das anzuzeigende Hilfethema zu bestimmen. Die HELPINFO-Struktur enthält auch die Koordinaten des Mauscursors zu dem Zeitpunkt, zu dem der Benutzer die Taste gedrückt hat. Sie können diese Informationen verwenden, um Hilfe basierend auf der Position des Mauscursors bereitzustellen.
Hilfe von der Maus
Windows bietet dem Benutzer Zugriff auf Informationen über die Maus, indem es die Anwendung benachrichtigt, wenn der Benutzer auf die rechte Maustaste klickt oder nach dem Klicken auf die Schaltfläche Frage (?) auf ein Fenster, ein Steuerelement oder ein Menü klickt. Die Anwendung reagiert, indem hilfeinformationen angezeigt werden, die dem angegebenen Fenster, Steuerelement oder Menü zugeordnet sind.
Das System sendet eine WM_CONTEXTMENU Nachricht, wenn der Benutzer auf die rechte Maustaste klickt. Das Fenster, auf das geklickt wurde, empfängt die Nachricht. Wenn das Fenster ein untergeordnetes Fenster ist, z. B. ein Steuerelement, übergibt die DefWindowProc-Funktion die Nachricht an das übergeordnete Fenster. Die WM_CONTEXTMENU Meldung gibt die Koordinaten des Mauscursors an. Die x-Koordinate befindet sich im Wort mit niedriger Reihenfolge des lParam-Parameters , und die y-Koordinate befindet sich im Wort mit hoher Ordnung. 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_HELP Meldung, 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 eine Frageschaltfläche zu einer Titelleiste hinzufügen, indem Sie beim Erstellen des Fensters die WS_EX_CONTEXTHELP Formatvorlage in der CreateWindowEx-Funktion angeben. Der lParam-Parameter von WM_HELP ist ein Zeiger auf eine HELPINFO-Struktur , die detaillierte Informationen zu dem Element enthält, für das Hilfe angefordert wird, einschließlich der Koordinaten des Mauscursors zum Zeitpunkt, als 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, sollten die entsprechenden Hilfeinformationen angezeigt werden. Da die Windows-Hilfeanwendung eine konsistente Benutzeroberfläche bereitstellt, wird empfohlen, dass Anwendungen die Windows-Hilfe anstelle anderer Methoden verwenden. Um die Windows-Hilfe zum Anzeigen von Hilfeinformationen anweisen zu können, verwendet eine Anwendung die WinHelp-Funktion und gibt Details an, z. B. die anzuzeigenden Informationen und die Form des Fensters, in dem sie angezeigt werden sollen. In den folgenden Abschnitten wird erläutert, wie Sie Mithilfe von WinHelp Hilfeinformationen anzeigen.
Hilfedateien
Um Hilfeinformationen anzuzeigen, müssen Sie beim Aufrufen der WinHelp-Funktion eine Hilfedatei angeben. Die Hilfedatei muss das Windows-Hilfedateiformat (HLP) und mindestens ein Thema aufweisen. Jedes Thema ist eine eigenständige Informationseinheit, z. B. eine konzeptionelle Beschreibung, eine Reihe von Anweisungen, ein Bild, eine Glossardefinition usw. Themen müssen eindeutig identifiziert werden, damit die Windows-Hilfe sie bei jeder Anforderung finden kann. Intern verwendet die Windows-Hilfe Themenbezeichner, um Themen zu suchen, aber Anwendungen verwenden am häufigsten Kontextbezeichner (eindeutige ganzzahlige Werte), um die anzuzeigenden Themen anzugeben. Der Autor der Hilfedatei muss Kontextbezeichner explizit Themenbezeichnern im Abschnitt [MAP] der Projektdatei zuordnen, die zum Erstellen der Hilfedatei verwendet wird.
Wenn Sie eine Hilfedatei angeben, aber keinen Pfad angeben, sucht WinHelp nach der Hilfedatei im Hilfeverzeichnis oder in einem Verzeichnis, das durch die UMGEBUNGSvariable PATH angegeben wird. Darüber hinaus kann WinHelp eine Hilfedatei finden, 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 denselben 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 Speicherortinformationen 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, die mit Ihren Entwicklungstools bereitgestellt wird.
Starten der Windows-Hilfe
Im folgenden Beispiel wird die WinHelp-Funktion verwendet, um die Windows-Hilfeanwendung zu starten und die Hilfedatei im Thema Inhalt zu öffnen.
HWND hwnd; // main window handle
BOOL bResult // for checking Boolean function result
bResult = WinHelp(hWnd, "WINNT.HLP", HELP_CONTENTS, 0L);
In diesem nächsten Beispiel wird die Benutzerhilfedatei geöffnet, die Datei nach dem Thema durchsucht, das einer Schlüsselwort (keyword) Zeichenfolge zugeordnet ist, und das Thema wird dann 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 Befehl HELP_FINDER aufrufen. Im Dialogfeld Hilfethemen können Benutzer themen auswählen, die angezeigt werden sollen, indem er die Titel der Themen, die den Themen zugeordneten Schlüsselwörter oder die in den Themen gefundenen Wörter und Ausdrücke anzeigt. Anwendungen zeigen dieses Dialogfeld in der Regel an, wenn der Benutzer einen Befehl aus dem Menü Hilfe auswäht, z. B. Hilfethemen. 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üsselwort (keyword) Index 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 Befehl HELP_CONTEXT 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, anstelle von Informationen zu einem bestimmten Steuerelement oder Menü. In solchen Fällen kann der Benutzer die Hilfedatei weiterhin durchsuchen und nach entsprechenden Informationen suchen, bevor er zur Anwendung zurückkehrt.
Der befehl HELP_CONTEXT ruft eine reguläre instance der Windows-Hilfe auf, sodass der Benutzer andere Themen in der Hilfedatei finden kann. In der Regel wird das Standard Hilfefenster angezeigt, das eine Titelleiste, ein Systemmenü, Schaltflächen zum Minimieren und Maximieren, ein Standard Menü, 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 durch die Hilfedatei navigieren, indem er Hotlinks oder Navigationsschaltflächen im Standard Fenster verwendet. Die reguläre instance der Windows-Hilfe kann auch verwendet werden, um Hilfe in einem oder mehreren sekundären Fenstern anstelle des Standard-Fensters 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 befehl HELP_WM_HELP oder HELP_CONTEXTMENU aufrufen. Diese Befehle zeigen ein Thema in einem Popupfenster in der Nähe des entsprechenden Steuerelements oder Menüs an. Damit der Benutzer sofort zur Arbeit in der Anwendung zurückkehren kann, wird das Popupfenster zerstört, sobald der Benutzer eine Taste drückt oder auf die linke Maustaste klickt.
Sie verwenden den Befehl HELP_WM_HELP, wenn Sie WM_HELP Nachrichten für Steuerungsfenster verarbeiten. Da die meisten Steuerelemente die WM_HELP Nachricht an die DefWindowProc-Funktion übergeben, verarbeitet die entsprechende Dialogfeldprozedur (oder die übergeordnete Fensterprozedur) diese Nachricht. Anstatt einen bestimmten Kontextbezeichner anzugeben, muss die Dialogfeldprozedur ein Array von Steuerelement- und Kontextbezeichnerpaaren zusammen mit dem Steuerelementhandle an WinHelp übergeben, das im hItemHandle-Member der HELPINFO-Struktur angegeben ist, das mit der WM_HELP Nachricht übergeben wird. 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 die übergeordnete Fensterprozedur) diese Nachricht. Die Prozedur gibt ein Array von Steuerelement- und Kontextbezeichnerpaaren an. Es gibt auch das Handle im wParam-Parameter an, wenn WinHelp aufgerufen wird, sodass 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 zuerst den Befehl Was ist das? in einem Menü an. Wenn der Benutzer den Befehl wä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 HELP_CONTEXT-Befehl, ruft aber das Popup-instance der Windows-Hilfe auf, die von HELP_WM_HELP und HELP_CONTEXTMENU verwendet wird. Anwendungen können diesen Befehl als Reaktion auf WM_HELP Nachrichten 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 jedem 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, die 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 SetWindowContextHelpId-Funktion , um einem Fenster oder Steuerelement einen Kontextbezeichner zuzuweisen, und die SetMenuContextHelpId-Funktion , um einem Menü einen Kontextbezeichner zuzuweisen. Sie können den Kontextbezeichner für ein Fenster oder Menü abrufen, indem Sie die Funktion GetWindowContextHelpId oder GetMenuContextHelpId verwenden.
Schlüsselwortsuche
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 (keyword) ist einfach eine Zeichenfolge, die einem oder mehreren Themen zugeordnet ist. Die Windows-Hilfe erfasst alle Schlüsselwörter in einer Hilfedatei, platziert sie in einer Tabelle und zeigt sie in der Liste Index des Dialogfelds Hilfethemen an. Wenn der Benutzer eine Schlüsselwort (keyword) auswählt, zeigt die Windows-Hilfe das zugehörige Hilfethema an. Wenn dem Schlüsselwort (keyword) mehrere Themen zugeordnet sind, wird eine Liste der Themen angezeigt, 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 teilweisen Schlüsselwörtern zu suchen und anzuzeigen. Sie geben den Befehl, die Schlüsselwort (keyword) Zeichenfolge, die Hilfedatei und das Handle für das Besitzerfenster an. In allen Fällen zeigt WinHelp das entsprechende Thema an, wenn eine einzelne Übereinstimmung gefunden wird. 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 (für HELP_MULTIKEY) an.
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 für Hilfedateien, die für Windows Version 3 erstellt wurden, nicht unterstützt. x) Es kann auch über mehrere Hilfedateien hinweg nach Schlüsselwörtern suchen, wenn die angegebene Hilfedatei über eine contents(.cnt)-Datei verfügt, die :Index- oder :Link-Befehle enthält. Mit dem Befehl HELP_KEY sucht WinHelp nach Schlüsselwörtern in allen Dateien, die durch diese Befehle angegeben werden. Mit den Befehlen HELP_MULTIKEY und HELP_PARTIALKEY durchsucht die Funktion alle Dateien mit Ausnahme der durch :Link-Befehle angegebenen Dateien.
Standardmäßig erkennt die Windows-Hilfe nur die Schlüsselwort (keyword) Tabelle, die durch das K-Fußnotenzeichen in der Hilfequelldatei identifiziert wird. Sie können die Windows-Hilfe anweisen, zusätzliche Schlüsselwort (keyword) Tabellen zu erstellen, indem Sie in der Hilfequelldatei ein anderes Fußnotenzeichen als K mit der Schlüsselwort (keyword) Definition hinzufügen. (Das Fußnotenzeichen A ist jedoch reserviert.) Sie müssen alle zusätzlichen Schlüsselwort (keyword) Tabellen definieren, indem Sie MULTIKEY-Anweisungen im Abschnitt [OPTIONEN] der Projektdatei beim Erstellen der Hilfedatei verwenden.
Eine Anwendung kann den Befehl HELP_SETINDEX mit der WinHelp-Funktion verwenden, um Windows-Hilfe anweisen, eine andere Schlüsselwort (keyword) Tabelle als K in der Indexliste anzuzeigen. Wenn Sie die Windows-Hilfe anweisen möchten, nach einem Schlüsselwort (keyword) in einer alternativen Schlüsselwort (keyword) Tabelle zu suchen, kann eine Anwendung den Befehl HELP_MULTIKEY verwenden. Sie geben die Schlüsselwort (keyword) und Schlüsselwort (keyword) Tabelle in einer MULTIKEYHELP-Struktur an, die Sie an WinHelp übergeben.
Wenn WinHelp ein Thema anzeigt, wird es in dem Fenster angezeigt, das in der Fußnote ">" für das Thema angegeben ist, in dem fenster, das durch den Befehl :Base in der Inhaltsdatei oder im Standard-Fenster angegeben wird. Wenn das Standard Fenster bereits für eine andere Hilfedatei geöffnet ist, wenn Sie WinHelp aufrufen, blendet die Funktion das Standard Fenster während der Suche aus. In diesem Fall wird das fenster Standard durch Abbrechen der Dialogfelder "Themen gefunden" und "Hilfethemen" geschlossen.
Sekundäre Hilfefenster
Das Standard Fenster der Windows-Hilfeanwendung wird als primäres Fenster bezeichnet. Die 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 einschließen und der Leiste Schaltflächen hinzufügen. Sie können auch festlegen, dass die Windows-Hilfe die Höhe des sekundären Fensters automatisch an das Thema anpasst.
Sie müssen sekundäre Fenster im Abschnitt [WINDOWS] Ihrer Hilfeprojektdatei definieren und dabei den Namen und optional die Anfangsgröße und position jedes Fensters angeben. Sie können die Windows-Hilfeanwendung anweisen, 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 sie die Adresse einer HELPWININFO-Struktur und den befehl HELP_SETWINPOS in einem Aufruf von WinHelp angibt. HELPWININFO gibt den Namen des Fensters sowie dessen neue Größe und Position an.
Schulung Karte Hilfe
Mithilfe von Training Karte Hilfe kann eine Anwendung eine Abfolge von Anweisungen anzeigen, um den Benutzer durch die Schritte einer Aufgabe zu führen. Ein Trainings-Karte besteht in der Regel aus Text, der einen bestimmten Schritt und Schaltflächen erläutert, die TCard-Makros zugeordnet sind, sodass 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 Hotlinks zu anderen Themen in der Hilfedatei enthalten.
Eine Anwendung initiiert das Training Karte instance der Windows-Hilfe, indem sie die WinHelp-Funktion aufruft und den befehl HELP_TCARD in Kombination mit einem anderen Befehl angibt, z. B. HELP_CONTEXT. Wenn der Benutzer anschließend auf eine Schaltfläche im trainingsbasierten Karte klickt, auf einen Hotspot klickt, der dem TCard-Makro zugewiesen ist, oder die Trainings-Karte schließt, benachrichtigt Windows-Hilfe die Anwendung, indem sie eine WM_TCARD-Nachricht sendet. Der wParam-Parameter identifiziert die Schaltflächen- oder Benutzeraktion, und der lParam-Parameter enthält zusätzliche Daten, deren Bedeutung vom Wert von wParam abhängt.
Hilfe abbrechen
Die Windows-Hilfe erfordert, dass eine Anwendung die Hilfe explizit abbricht, damit sie alle Ressourcen freigeben 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 angibt. Beachten Sie, dass dies für die Popup-instance der Windows-Hilfe nicht gilt. Eine Anwendung sollte nicht versuchen, ein Popup-instance zu schließen.
Wenn eine Anwendung WinHelp aufgerufen hat, muss sie die Hilfe abbrechen, bevor sie ihr Standard Fenster schließt (z. B. als Reaktion auf die WM_DESTROY Nachricht in der Standard Fensterprozedur). Eine Anwendung muss WinHelp nur einmal aufrufen, um die Hilfe abzubrechen, unabhängig davon, wie viele Hilfedateien sie geöffnet hat. Die Windows-Hilfe wird weiterhin ausgeführt, bis alle Anwendungen oder DLLs die Hilfe abgebrochen haben.
Zum Schließen des Trainings Karte instance der Windows-Hilfe müssen Sie beim Aufrufen von WinHelp sowohl die befehle HELP_TCARD als auch HELP_QUIT angeben. Eine Anwendung muss die Trainings-Karte instance der Windows-Hilfe nicht abbrechen, wenn der Benutzer sie zuerst abbricht. Windows-Hilfe benachrichtigt eine Anwendung, wenn der Benutzer das Training Karte instance abbricht, indem die WM_TCARD Nachricht gesendet wird, wobei der wParam-Parameter auf IDCLOSE festgelegt ist.
Verwenden der Hilfe
In diesem Abschnitt erfahren Sie, wie Sie kontextbezogene Hilfe für ein Dialogfeld bereitstellen und die Darstellung eines sekundären Hilfefensters festlegen.
- Bereitstellen von Hilfe in einem Dialogfeld
- Festlegen der Darstellung eines sekundären Hilfefensters
Bereitstellen von Hilfe in einem Dialogfeld
Um kontextbezogene Hilfe in einem Dialogfeld bereitzustellen, 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, und der zweite ist 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-Nachrichten verarbeiten. Die Dialogfeldprozedur empfängt WM_HELP , wenn der Benutzer die Taste drückt und WM_CONTEXTMENU , wenn der Benutzer auf die rechte Maustaste klickt.
Der lParam-Parameter von WM_HELP enthält die Adresse einer HELPINFO-Struktur . Das hItemHandle-Element dieser Struktur identifiziert das Steuerelement, für das der Benutzer Hilfe angefordert hat. Sie müssen dieses Handle zusammen mit dem Befehl HELP_WM_HELP, 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 die Windows-Hilfe, die das entsprechende Thema findet und in einem Popupfenster anzeigt. Wenn das Steuerelement über einen Bezeichner von -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, dass Sie statischen Text vor Steuerelementen in einer Ressourcendatei platzieren.
Beim Aufrufen der WinHelp-Funktion ähnelt die Verarbeitung WM_CONTEXTMENU mit den folgenden beiden Ausnahmen der Verarbeitung WM_HELP :
- Sie übergeben den wParam-Parameter von WM_CONTEXTMENU, d. h. das Handle an das Steuerelement, das die Nachricht gesendet hat.
- Sie geben den befehl HELP_CONTEXTMENU anstelle von HELP_WM_HELP an.
Der befehl HELP_CONTEXTMENU bewirkt, dass die Windows-Hilfe ein Menü anzeigt, bevor das Hilfethema angezeigt wird. Das Menü ist systemdefiniert. Es ermöglicht dem Benutzer, Hilfe für das Steuerelement anzuzeigen oder das Dialogfeld Hilfethemen anzuzeigen.
Das folgende Beispiel zeigt, wie Kontextbezogene 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 sie den befehl HELP_SETWINPOS und die Adresse einer HELPWININFO-Struktur an die WinHelp-Funktion übergibt. Die Member von HELPWININFO geben den Namen des zu ändernden Fensters und 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" festgelegt. Der Name muss im Abschnitt [WINDOWS] 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;
}