TN028: Bereitstellen kontextbezogener Hilfe

In diesem Hinweis werden die Regeln zum Zuweisen von Hilfekontext-IDs und anderen Hilfeproblemen in MFC beschrieben. Für die unterstützung kontextbezogener Hilfe ist der Hilfecompiler erforderlich, der in Visual C++ verfügbar ist.

Hinweis

Neben der Implementierung kontextbezogener Hilfe mithilfe von WinHelp unterstützt MFC auch die Verwendung der HTML-Hilfe. Weitere Informationen zu dieser Unterstützung und Programmierung mit HTML-Hilfe finden Sie in der HTML-Hilfe: Kontextbezogene Hilfe für Ihre Programme.

Unterstützte Hilfetypen

Es gibt zwei Arten kontextsensitiver Hilfe in Windows-Anwendungen implementiert. Der erste, der als "F1-Hilfe" bezeichnet wird, umfasst das Starten von WinHelp mit dem entsprechenden Kontext basierend auf dem aktuell aktiven Objekt. Die zweite ist der Modus "UMSCHALT+F1". In diesem Modus ändert sich der Mauszeiger auf den Hilfecursor, und der Benutzer klickt auf ein Objekt. Zu diesem Zeitpunkt wird WinHelp gestartet, um Hilfe für das Objekt zu geben, auf das der Benutzer geklickt hat.

Die Microsoft Foundation-Klassen implementieren beide Hilfeformen. Darüber hinaus unterstützt das Framework zwei einfache Hilfebefehle, "Hilfeindex" und "Verwenden der Hilfe".

Hilfedateien

Die Microsoft Foundation-Klassen gehen von einer einzelnen Hilfedatei aus. Diese Hilfedatei muss denselben Namen und Pfad wie die Anwendung aufweisen. Wenn die ausführbare Datei beispielsweise "C:\MyApplication\MyHelp.exe" lautet, muss die Hilfedatei "C:\MyApplication\MyHelp.hlp" sein. Sie legen den Pfad durch die m_pszHelpFilePath Membervariable der CWinApp-Klasse fest.

Hilfekontextbereiche

Die Standardimplementierung von MFC erfordert ein Programm, um einige Regeln zur Zuweisung von Hilfekontext-IDs zu befolgen. Diese Regeln sind eine Reihe von IDs, die bestimmten Steuerelementen zugeordnet sind. Sie können diese Regeln außer Kraft setzen, indem Sie verschiedene Implementierungen der verschiedenen Hilfe-bezogenen Memberfunktionen bereitstellen.

0x00000000 - 0x0000FFFF : user defined
0x00010000 - 0x0001FFFF : commands (menus/command buttons)
0x00010000 + ID_
(note: 0x18000-> 0x1FFFF is the practical range since command IDs are>=0x8000)
0x00020000 - 0x0002FFFF : windows and dialogs
0x00020000 + IDR_
(note: 0x20000-> 0x27FFF is the practical range since IDRs are <= 0x7FFF)
0x00030000 - 0x0003FFFF : error messages (based on error string ID)
0x00030000 + IDP_
0x00040000 - 0x0004FFFF : special purpose (non-client areas)
0x00040000 + HitTest area
0x00050000 - 0x0005FFFF : controls (those that are not commands)
0x00040000 + IDW_

Einfache Befehle "Hilfe"

Es gibt zwei einfache Hilfebefehle, die von den Microsoft Foundation-Klassen implementiert werden:

• ID_HELP_INDEX, die von CWinApp::OnHelpIndex implementiert wird

• ID_HELP_USING, die von CWinApp::OnHelpUsing implementiert wird

Der erste Befehl zeigt den Hilfeindex für die Anwendung an. Im zweiten wird die Hilfe des Benutzers zur Verwendung des WinHelp-Programms angezeigt.

Kontextbezogene Hilfe (F1-Hilfe)

Die F1-TASTE wird in der Regel in einen Befehl mit einer ID von ID_HELP übersetzt, indem eine Zugriffstaste in die Zugriffstastentabelle des Standard Fensters eingefügt wird. Der befehl ID_HELP kann auch von einer Schaltfläche mit einer ID von ID_HELP im Standard Fenster oder Dialogfeld generiert werden.

Unabhängig davon, wie der ID_HELP-Befehl generiert wird, wird er als normaler Befehl weitergeleitet, bis er einen Befehlshandler erreicht. Weitere Informationen zur MFC-Befehlsroutingarchitektur finden Sie in technischem Hinweis 21. Wenn die Anwendung die Hilfe aktiviert hat, wird der Befehl ID_HELP von CWinApp::OnHelp behandelt. Das Anwendungsobjekt empfängt die Hilfemeldung und leitet dann den Befehl entsprechend weiter. Dies ist erforderlich, da das Standardbefehlsrouting nicht ausreicht, um den spezifischen Kontext zu ermitteln.

CWinApp::OnHelp versucht, WinHelp in der folgenden Reihenfolge zu starten:

1. Sucht nach einem aktiven AfxMessageBox Anruf mit einer Hilfe-ID. Wenn derzeit ein Meldungsfeld aktiv ist, wird WinHelp mit dem Kontext gestartet, der für dieses Meldungsfeld geeignet ist.

2. Sendet eine WM_COMMANDHELP Nachricht an das aktive Fenster. Wenn dieses Fenster nicht durch Starten von WinHelp antwortet, wird dieselbe Nachricht dann an die Vorgänger dieses Fensters gesendet, bis die Nachricht verarbeitet wird oder das aktuelle Fenster ein Fenster der obersten Ebene ist.

3. Sendet einen ID_DEFAULT_HELP Befehl an das Standard Fenster. Dadurch wird die Standardhilfe aufgerufen. Dieser Befehl ist in der Regel zugeordnet CWinApp::OnHelpIndex.

Um die Standard-ID-Basiswerte (z. B. 0x10000 für Befehle und 0x20000 für Ressourcen wie Dialogfelder) global außer Kraft zu setzen, sollte die Anwendung CWinApp::WinHelp überschreiben.

Um diese Funktionalität und die Art und Weise außer Kraft zu setzen, wie ein Hilfekontext bestimmt wird, sollten Sie die WM_COMMANDHELP Nachricht behandeln. Möglicherweise möchten Sie spezifischere Hilferouting bereitstellen, als das Framework bereitstellt, da es nur so tief geht wie das aktuelle untergeordnete MDI-Fenster. Möglicherweise möchten Sie auch spezifischere Hilfe für ein bestimmtes Fenster oder Dialogfeld bereitstellen, möglicherweise basierend auf dem aktuellen internen Status dieses Objekts oder des aktiven Steuerelements innerhalb des Dialogfelds.

WM_COMMANDHELP

afx_msg LRESULT CWnd::OnCommandHelp(WPARAM wParam, LPARAM lParam)

WM_COMMANDHELP ist eine private Windows MFC-Nachricht, die vom aktiven Fenster empfangen wird, wenn Hilfe angefordert wird. Wenn das Fenster diese Nachricht empfängt, kann es mit Kontext aufgerufen CWinApp::WinHelp werden, der dem internen Zustand des Fensters entspricht.

lParam
Enthält den derzeit verfügbaren Hilfekontext. lParam ist null, wenn kein Hilfekontext ermittelt wurde. Eine Implementierung kann OnCommandHelp die Kontext-ID in lParam verwenden, um einen anderen Kontext zu ermitteln oder einfach an sie zu CWinApp::WinHelpübergeben.

wParam
Wird nicht verwendet und ist null.

Wenn die OnCommandHelp Funktion aufruftCWinApp::WinHelp, sollte true zurückgegeben werden. Durch zurückgeben von TRUE wird das Routing dieses Befehls an andere Klassen und an andere Fenster beendet.

Hilfemodus (Umschalt+F1 Hilfe)

Dies ist die zweite Form der kontextabhängigen Hilfe. Im Allgemeinen wird dieser Modus durch Drücken von UMSCHALT+F1 oder über das Menü/die Symbolleiste eingegeben. Sie wird als Befehl (ID_CONTEXT_HELP) implementiert. Der Nachrichtenfilter-Hook wird nicht verwendet, um diesen Befehl zu übersetzen, während ein modales Dialogfeld oder Menü aktiv ist, daher ist dieser Befehl nur für den Benutzer verfügbar, wenn die Anwendung die Standard Nachrichtenpumpe (CWinApp::Run) ausführt.

Nach der Eingabe dieses Modus wird der Hilfezeiger über alle Bereiche der Anwendung angezeigt, auch wenn die Anwendung normalerweise einen eigenen Cursor für diesen Bereich anzeigt (z. B. den Größenrahmen um das Fenster). Der Benutzer kann die Maus oder Tastatur verwenden, um einen Befehl auszuwählen. Anstatt den Befehl auszuführen, wird die Hilfe zu diesem Befehl angezeigt. Außerdem kann der Benutzer auf ein sichtbares Objekt auf dem Bildschirm klicken, z. B. eine Schaltfläche auf der Symbolleiste, und die Hilfe wird für dieses Objekt angezeigt. Dieser Hilfemodus wird von CWinApp::OnContextHelp.

Während der Ausführung dieser Schleife sind alle Tastatureingaben inaktiv, mit Ausnahme von Tasten, die auf das Menü zugreifen. Außerdem wird die Befehlsübersetzung weiterhin ausgeführt PreTranslateMessage , um dem Benutzer das Drücken einer Tastenkombination zu ermöglichen und Hilfe zu diesem Befehl zu erhalten.

Wenn in der Funktion bestimmte Übersetzungen oder Aktionen ausgeführt werden, die PreTranslateMessage nicht im UMSCHALT+F1-Hilfemodus ausgeführt werden sollten, sollten Sie das m_bHelpMode Mitglied CWinApp überprüfen, bevor Sie diese Vorgänge ausführen. Die CDialog Implementierung der PreTranslateMessage Überprüfungen vor dem Aufrufen IsDialogMessage, z. B. Dadurch werden die Tasten "Dialogfeldnavigation" während des UMSCHALT+F1-Modus in moduslosen Dialogfeldern deaktiviert. Darüber hinaus CWinApp::OnIdle wird er während dieser Schleife noch aufgerufen.

Wenn der Benutzer einen Befehl aus dem Menü auswählt, wird er als Hilfe zu diesem Befehl behandelt (über WM_COMMANDHELP siehe unten). Wenn der Benutzer auf einen sichtbaren Bereich des Anwendungsfensters klickt, wird festgelegt, ob es sich um einen Nichtclient-Klick oder einen Clientklick handelt. OnContextHelp behandelt die Zuordnung von Nichtclientklicks automatisch zu Clientklicks. Wenn es sich um einen Clientklick handelt, sendet es eine WM_HELPHITTEST an das Fenster, auf das geklickt wurde. Wenn dieses Fenster einen Wert ungleich Null zurückgibt, wird dieser Wert als Kontext für Hilfe verwendet. Wenn null zurückgegeben wird, OnContextHelp wird das übergeordnete Fenster versucht (und dies ist fehlgeschlagen, das übergeordnete Fenster usw.). Wenn kein Hilfekontext bestimmt werden kann, besteht die Standardeinstellung darin, einen ID_DEFAULT_HELP Befehl an das Standard-Fenster zu senden, das dann (normalerweise) zugeordnet CWinApp::OnHelpIndexist.

WM_HELPHITTEST

afx_msg LRESULT CWnd::OnHelpHitTest(
WPARAM, LPARAM lParam)

WM_HELPHITTEST handelt es sich um eine private MFC-Windows-Nachricht, die vom aktiven Fenster empfangen wird, auf das im UMSCHALT+F1-Hilfemodus geklickt wird. Wenn das Fenster diese Nachricht empfängt, wird eine DWORD-Hilfe-ID für die Verwendung durch WinHelp zurückgegeben.

LOWORD(lParam) enthält die X-Achsen-Gerätekoordinate, an der die Maus relativ zum Clientbereich des Fensters geklickt wurde.

HIWORD(lParam) enthält die Y-Achsenkoordinate.

wParam
wird nicht verwendet und ist null. Wenn der Rückgabewert nicht null ist, wird WinHelp mit diesem Kontext aufgerufen. Wenn der Rückgabewert null ist, wird das übergeordnete Fenster zur Hilfe abgefragt.

In vielen Fällen können Sie Hit-Testing-Code nutzen, den Sie möglicherweise bereits haben. Sehen Sie sich die Implementierung eines CToolBar::OnHelpHitTest Beispiels für die Behandlung der WM_HELPHITTEST Nachricht an (der Code nutzt den Treffertestcode, der auf Schaltflächen und QuickInfos CControlBarverwendet wird).

Unterstützung des MFC-Anwendungs-Assistenten und MAKEHM

Der MFC-Anwendungs-Assistent erstellt die erforderlichen Dateien zum Erstellen einer Hilfedatei (CNT- und HPJ-Dateien). Sie enthält auch eine Reihe vordefinierter RTF-Dateien, die vom Microsoft-Hilfecompiler akzeptiert werden. Viele der Themen sind abgeschlossen, aber einige müssen möglicherweise für Ihre spezifische Anwendung geändert werden.

Die automatische Erstellung einer Hilfezuordnungsdatei wird von einem Hilfsprogramm mit dem Namen MAKEHM unterstützt. Das MAKEHM-Hilfsprogramm kann die RESSOURCE einer Anwendung übersetzen. H-Datei zu einer Hilfezuordnungsdatei. Beispiel:

#define IDD_MY_DIALOG   2000
#define ID_MY_COMMAND   150

wird übersetzt in:

HIDD_MY_DIALOG    0x207d0
HID_MY_COMMAND    0x10096

Dieses Format ist mit der Einrichtung des Hilfecompilers kompatibel, die Kontext-IDs (die Zahlen auf der rechten Seite) mit Themennamen (die Symbole auf der linken Seite) zuordnet.

Der Quellcode für MAKEHM ist im MFC Programming Utilities-Beispiel MAKEHM verfügbar.

Hinzufügen von Hilfeunterstützung nach dem Ausführen des MFC-Anwendungs-Assistenten

Die beste Möglichkeit, Ihrer Anwendung Hilfe hinzuzufügen, besteht darin, die Option "Kontextbezogene Hilfe" auf der Seite "Erweiterte Features" des MFC-Anwendungs-Assistenten zu überprüfen, bevor Sie Ihre Anwendung erstellen. Auf diese Weise fügt der MFC-Anwendungs-Assistent automatisch die erforderlichen Nachrichtenzuordnungseinträge zur Unterstützung der Hilfe zu Ihrer CWinAppabgeleiteten Klasse hinzu.

Hilfe zu Meldungsfeldern

Hilfe zu Meldungsfeldern (manchmal als Warnungen bezeichnet) wird über die AfxMessageBox Funktion unterstützt, ein Wrapper für die MessageBox Windows-API.

Es gibt zwei Versionen von AfxMessageBox, eine für die Verwendung mit einer Zeichenfolgen-ID und eine für die Verwendung mit einem Zeiger auf Zeichenfolge (LPCSTR):

int AFXAPI AfxMessageBox(LPCSTR lpszText,
    UINT nType,
    UINT nIDHelp);

int AFXAPI AfxMessageBox(UINT nIDPrompt,
    UINT nType,
    UINT nIDHelp);

In beiden Fällen gibt es eine optionale Hilfe-ID.

Im ersten Fall ist der Standardwert für nIDHelp 0, der keine Hilfe für dieses Meldungsfeld angibt. Wenn der Benutzer F1 drückt, während z. B. das Meldungsfeld aktiv ist, erhält der Benutzer keine Hilfe (auch wenn die Anwendung Hilfe unterstützt). Wenn dies nicht wünschenswert ist, sollte eine Hilfe-ID für nIDHelp bereitgestellt werden.

Im zweiten Fall ist der Standardwert für nIDHelp -1, der angibt, dass die Hilfe-ID mit nIDPrompt identisch ist. Die Hilfe funktioniert nur, wenn die Anwendung hilfefähig ist. Sie sollten 0 für nIDHelp bereitstellen, wenn Sie möchten, dass das Meldungsfeld keine Hilfe unterstützt. Wenn die Nachricht aktiviert sein soll, aber eine andere Hilfe-ID als nIDPrompt wünschen, geben Sie einfach einen positiven Wert für nIDHelp anders als nIDPrompt an.

Siehe auch

Technische Hinweise – nach Nummern geordnet
Technische Hinweise – nach Kategorien geordnet