TN028: Unterstützung der kontextbezogenen Hilfe
Dieser Hinweis wird die Regeln für das Zuweisen von kontext-ID Hilfe und von-anderer Hilfe in MFC.Unterstützung der kontextbezogenen Hilfe die erfordert, dass der Compiler Hilfe, der in Visual C++ verfügbar ist.
.gif "Hinweis") Hinweis |
|---|
Zusätzlich zum Implementieren von kontextbezogener Hilfe mit dem WinHelp, MFC unterstützt auch mithilfe der Help.Weitere Informationen über diese Unterstützung und das Programmieren mit HTML-Hilfe finden Sie unter : Help Kontextbezogene Hilfe für die Programme. |
Typen der die Hilfefunktion unterstützt
Es gibt zwei Typen von kontextabhängiger Hilfe implementiert in Windows-Anwendungen.Das erste, so genannte "F1-Hilfe" beinhaltet startendes WinHelp in den entsprechenden Kontext auf der Grundlage des aktuell aktive Objekt.Das zweite Element ist "UMSCHALT+F1-" - Modus.In diesem Modus ändert sich der Mauszeiger in den Hilfecursor, und der Benutzer wird fortgesetzt, um für ein Objekt zu klicken.An diesem Punkt wird WinHelp gestartet, um die Hilfe für das Objekt zu gewähren, den der Benutzer geklickt hat.
Das Microsoft Foundation Classes-Werkzeug beide Formen der Hilfe.Außerdem unterstützt das Framework zwei einfache Hilfe, Hilfeindex und mithilfe.
Hilfedateien
Die Microsoft Foundations-Klassen nehmen eine einzelne Hilfedatei an.Diese Hilfedatei muss denselben Namen und Pfad der Anwendung verfügen.Wenn z. B. die ausführbare Datei C:\MyApplication\MyHelp.exe ist, muss die Hilfedatei C:\MyApplication\MyHelp.hlp sein.legen Sie den Pfad von der m_pszHelpFilePath-Membervariable CWinApp-Klasse.
Hilfe-Kontext-Bereiche
Die Standardimplementierung von MFC benötigt ein Programm bestimmten Regeln über die Zuweisung von IDs Hilfekontext zu befolgen.Diese Regeln sind ein Bereich der ID, die auf bestimmte Steuerelemente zugeordnet ist.Sie können diese Regeln außer Kraft setzen, indem Sie verschiedene Implementierungen der verschiedenen HELP-verknüpften 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 "Hilfe-" Befehle
Es gibt zwei grundlegende Hilfe, die von Microsoft Foundation Classes implementiert werden:
ID_HELP_INDEX implementiert wird, das von CWinApp::OnHelpIndex
ID_HELP_USING implementiert wird, das von CWinApp::OnHelpUsing
Der erste Befehl zeigt den Hilfeindex für die Anwendung an.Im zweiten Beispiel wird die Benutzer können zur Verwendung des WinHelp programms an.
Kontextbezogene Hilfe (F1-Hilfe)
Die F1-TASTE wird normalerweise einem Befehl mit einer ID von ID_HELP über eine Tastenkombination übersetzt, die in der Zugriffstastentabelle des Hauptfensters platziert wird.Der ID_HELP Befehl kann auch über eine Schaltfläche mit einer ID von ID_HELP im Hauptfenster oder im 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 über die MFC-Befehl Routing Architektur finden Sie unter Technischer Hinweis 21 an.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 Standardbefehls routing nicht zum Bestimmen des Kontexts bestimmtsten geeignet ist.
Versucht,CWinApp::OnHelp WinHelp in der folgenden Reihenfolge:
Überprüfungen für einen aktiven AfxMessageBox Aufruf mit einer Hilfe ID.Wenn ein Meldungsfeld gerade aktiv ist, wird WinHelp mit dem Kontext ausgelöst, der auf diesen Meldungsfeld geeignet ist.
Sendet eine WM_COMMANDHELP-Meldung des aktiven Fensters.Wenn dieses Fenster nicht durch startendes WinHelp antwortet, wird die gleiche Nachricht dann auf den Vorgängern dieses Fensters gesendet, wenn die Meldung verarbeitet wurde, oder das aktive Fenster ein Fenster der obersten Ebene befindet.
Sendet einen ID_DEFAULT_HELP-Befehl an das Hauptfenster.Dadurch wird die Standardhilfsfunktion auf.Dieser Befehl ist im Allgemeinen CWinApp::OnHelpIndex zugeordnet.
Um die Standard-ID basiswerte global überschrieben werden (z. B.0x10000 für Befehle und 0x20000 für Ressourcen wie Dialogfelder), die Anwendung sollten CWinApp::WinHelp überschreiben.
Um diese Funktionalität und die Methode zu überschreiben die ein Hilfekontext bestimmt wird, sollten Sie die WM_COMMANDHELP-Meldung bearbeiten.Sie möchten möglicherweise als spezifischerer routing Hilfe zur Verfügung stellen das Framework bereitgestellt werden, da es nur so tief wie der aktuelle untergeordnete MDI-Fenster an.Sie können auch bestimmte Hilfe Informationen für ein bestimmtes Fenster oder ein Dialogfeld, werden auf Grundlage des aktuellen internen Zustand dieses Objekts oder das aktive Steuerelement im Dialogfeld bereitstellen können.
WM_COMMANDHELP
afx_msg LRESULT CWnd::OnCommandHelp(WPARAM wParam, LPARAM lParam)
WM_COMMANDHELP handelt es sich um eine private Meldung, die von MFC Windows das aktive Fenster empfangen wird, wenn Hilfe angefordert wird.Wenn das Fenster diese Nachricht empfängt, ruft es möglicherweise CWinApp::WinHelp den Kontext an, der den internen Zustand des Fensters entspricht.
lParam
Enthält den derzeit verfügbaren Hilfekontext.lParam ist null, wenn keine Hilfekontext bestimmt wurde.Eine Implementierung von OnCommandHelp kann die Kontext-ID in lParam verwenden, um einem anderen Kontext zu bestimmen, oder es kann ihn auf CWinApp::WinHelp gerade übergeben.wParam
Wird nicht verwendet und ist Null sein.
Wenn die OnCommandHelp-Funktionsaufrufe CWinApp::WinHelp, es TRUE zurückgeben.Die Rückgabe von TRUE beendet das Routing dieses Befehls an andere Klassen und anderen Fenstern.
Hilfe-Modus (UMSCHALT+F1-Hilfe)
Dies ist die zweite Form der kontextbezogener Hilfe.Im Allgemeinen wird dieser Modus eingeführt, indem UMSCHALT+F1 oder über das Menü oder die Symbolleiste drückt.Es wird als Befehl (ID_CONTEXT_HELP) implementiert.Der Meldungsfilter hook wird nicht verwendet, um diesen Befehl zu übersetzen, während ein modales Dialogfeld oder ein Menü aktiv ist. Daher ist dieser Befehl an den Benutzer nur verfügbar, wenn die Anwendung die Haupt-Meldungsverteilschleife (CWinApp::Run) ausgeführt wird.
Nachdem Sie diesen Modus erhalten hat, wird der Hilfe mauszeiger in allen Bereichen der Anwendung angezeigt, selbst wenn die Anwendung normalerweise seinen eigenen Cursor für diesen Bereich anzeigen würde (z. B. den Größenanpassungsrahmen um das Fenster).Der Benutzer kann die Maus oder der Tastatur, um einen Befehl auszuwählen.Statt den Befehl auszuführen angezeigt wird, Hilfe zu diesem Befehl.Außerdem kann der Benutzer auf ein sichtbares Objekt auf dem Bildschirm, z. B. einer Schaltfläche auf der Symbolleiste und Hilfe klicken, wird für dieses Objekt angezeigt.Dieser Modus der Hilfe wird von CWinApp::OnContextHelp bereitgestellt.
Während der Ausführung der Schleife, kann alle Tastatureingaben, außer Schlüssel inaktiv, die das Menü zugreifen.Außerdem Befehls übersetzung wird weiterhin über PreTranslateMessage ausgeführt, um dem Benutzer zu ermöglichen, um eine Tastenkombination drücken und auf Hilfe zu diesem Befehl empfangen soll.
Wenn es bestimmte Übersetzungen vorhanden ist oder die Aktionen, die in PreTranslateMessage stattfinden, arbeiten, das während des Modus UMSCHALT+F1-Hilfe stattfinden sollen, sollten Sie den m_bHelpMode-Member von CWinApp überprüfen, bevor Sie diese Vorgänge ausführen.Die CDialog Implementierung von PreTranslateMessage überprüft, bevor sie IsDialogMessage aufruft, z.Dieses Dialogfeld "deaktiviert" navigations Tasten auf nicht modale Dialogfelder während UMSCHALT+F1-Modus.Außerdem wird CWinApp::OnIdle noch während dieser Schleife aufgerufen.
Wenn der Benutzer einen Befehl aus dem Menü ausgewählt wird, wird es als Hilfe zu diesem Befehl behandelt, WM_COMMANDHELP(siehe unten).Wenn der Benutzer auf einen sichtbaren Bereich des Fensters Anwendung klickt, wird eine Angabe gemacht, ob es ein, oder klicken Sie auf Nicht-Client ein Client mit einem ist.Zuordnen von Nicht-Client das Handle OnContextHelp Klicken automatisch an den Client klickt.Wenn ein Client auf WM_HELPHITTEST ist, sendet es an das Fenster, auf das geklickt wurde.Wenn dieses Fenster ein Wert ungleich 0 (null) zurückgegeben wird, wird dieser Wert als den Kontext für die Hilfe verwendet.Wenn er null zurückgibt, versucht OnContextHelp das übergeordnete Fenster (und das Lassen das das übergeordnete Element usw.).Wenn ein Hilfekontext nicht bestimmt werden kann, ist der Standardwert, ID_DEFAULT_HELP einen Befehl auf das Hauptfenster zu senden, die normalerweise) ( CWinApp::OnHelpIndex zugeordnet ist.
WM_HELPHITTEST
afx_msg LRESULT CWnd::OnHelpHitTest(WPARAM, LPARAM lParam)
WM_HELPHITTEST ist eine private Fenstermeldung MFC, die durch das aktive Fenster empfangen wird, das während des Modus UMSCHALT+F1-Hilfe geklickt wird.Wenn das Fenster diese Nachricht empfängt, gibt es eine DWORD Hilfe ID für WinHelp zurück.
LOWORD (lParam)
enthält die x-Achse-Gerätekoordinate, an der mit der Maus relativ zum Clientbereich des Fensters geklickt wurde.HIWORD (lParam)
enthält die y-Achse-Koordinate.wParam
wird nicht verwendet und ist Null sein.Wenn der Rückgabewert nicht 0 ist, wird WinHelp diesem Kontext bezeichnet.Wenn der Rückgabewert (null) ist, wird die Hilfe für das übergeordnete Fenster abgefragt.
In vielen Fällen können Sie Code für Treffertests verwenden, den Sie bereits verfügen.Zeigen Sie die Implementierung von CToolBar::OnHelpHitTest als ein Beispiel für die Behandlung der Meldung WM_HELPHITTEST (der Code nutzt die Trefferüberprüfung von Code, der auf Schaltflächen und QuickInfos in CControlBar verwendet wird).
MFC-Anwendungs-Assistenten-Unterstützung und MAKEHM
Der MFC-Anwendungs-Assistent erstellt die erforderlichen Dateien zu erstellen, um eine HTML Help (.cnt- und .hpj-Dateien).Sie enthält auch eine Reihe vordefinierter .rtf-Dateien ein, die vom Microsoft-Hilfe-Compiler akzeptiert werden.Viele Themen sind vollkommen müssen einige, aber möglicherweise für eine bestimmte Anwendung geändert werden.
Automatische Erstellung einer zuordnungs "Hilfe" Datei wird durch ein Dienstprogramm MAKEHM unterstützt.Das MAKEHM-Hilfsprogramm kann das RESOURCE.H-Datei einer Anwendung an eine Hilfe zuordnungsdatei übersetzen.Beispiele:
#define IDD_MY_DIALOG 2000
#define ID_MY_COMMAND 150
wird in übersetzt:
HIDD_MY_DIALOG 0x207d0
HID_MY_COMMAND 0x10096
Dieses Format ist mit der Funktion des Hilfe compilers kompatibel, die Kontext ID (die Zahlen auf der rechten Seite) (Themen mit Namen zugeordnet werden die Symbole auf der linken Seite).
Der Quellcode für MAKEHM ist in MFC benutzerfreundliche Programming Beispiel MAKEHM verfügbar.
Hilfeunterstützung hinzugefügt werden, nachdem der MFC-Anwendungs-Assistent ausgeführt wurde
Die beste Möglichkeit zur Unterstützung der Anwendung hinzugefügt werden, die Option "der kontextbezogenen Hilfe" auf der Seite Erweiterte Features des MFC-Anwendungs-Assistenten zu überprüfen, bevor sie die Anwendung erstellt werden soll.Daher der MFC-Anwendungs-Assistent fügt automatisch die notwendigen Einträge für Meldungszuordnungs dem CWinApp abgeleitete Klasse können Unterstützungs hinzu.
Hilfe in Meldungsfeldern
Hilfe in Meldungsfenstern (gelegentlich aufgerufen AfxMessageBox Warnungen) wird von der Funktion ein Wrapper für die MessageBox Windows-API unterstützt.
Es gibt zwei Versionen von AfxMessageBox, einem für die Verwendung mit Zeichenfolgen-ID und anderen für die Verwendung mit einem Zeiger auf die 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 (null), womit keine Hilfe für das Meldungsfeld angibt.Wenn der Benutzer F1 drückt, während das Meldungsfeld aktiviert ist, erhält der Benutzer keine Hilfe (selbst wenn die Anwendung die Hilfefunktion unterstützt).Wenn dies nicht erwünscht ist, sollte eine Hilfe ID für nIDHelp bereitgestellt werden.
Im zweiten Fall ist der Standardwert für nIDHelp -1, der die Hilfe ID entspricht nIDPrompt angibt.Hilfe funktioniert nur, wenn die Anwendung HELP-aktiviert ist natürlich).Sie sollten 0 für nIDHelp bereitstellen, wenn Sie möchten, dass das Meldungsfeld keine Hilfeunterstützung haben.Wenn die Meldung die Hilfe aktiviert sein soll, aber eine andere Hilfe ID als nIDPrompt möchten, erstellen Sie einfach einen positiven Wert für das nIDHelp bereit, die der von nIDPrompt unterscheidet.