TN028: Podpora kontextové nápovědy
Tato poznámka popisuje pravidla pro přiřazení ID kontextu nápovědy a dalších problémech nápovědy v knihovně MFC.Kontextová nápověda a odborná pomoc vyžaduje kompilátor nápovědy, která je k dispozici v aplikaci Visual C++.
[!POZNÁMKA]
Kromě provádění kontextovou nápovědu k použití WinHelp, MFC podporuje také pomocí nápovědy HTML.Další informace o této podpory a programování pomocí nápovědy HTML naleznete v tématu nápovědy HTML: Context-Sensitive Help for Your Programs.
Typy podporovaných nápovědy
Existují dva typy zobrazení kontextové nápovědy v aplikacích systému Windows implementována.První, označovány jako "Nápověda F1" zahrnuje spuštění nápovědy s odpovídající kontext založené na aktivní objekt.Druhým je režim "Shift + F1".V tomto režimu kurzor myši se změní na kurzor nápovědy a klepněte na objekt uživatele pokračuje.V tomto okamžiku je poskytnout nápovědu pro objekt, na který uživatel klepnul na spuštěno WinHelp.
Microsoft Foundation Classes provedení obou těchto formách pomoci.Kromě toho rozhraní framework podporuje dva příkazy jednoduchý nápovědy, rejstříku nápovědy a pomoci.
Soubory nápovědy
Microsoft Foundation classes předpokládají jeden soubor nápovědy.Tento soubor nápovědy musí mít stejný název a cestu jako aplikace.Například pokud je spustitelný soubor C:\MyApplication\MyHelp.exe musí být v souboru nápovědy C:\MyApplication\MyHelp.hlp.Nastavení cesty až m_pszHelpFilePath členské proměnné Třída CWinApp.
Rozsahy kontextové nápovědy
Výchozí implementace MFC vyžaduje program dodržovat některá pravidla o přiřazení kontextové nápovědy ID.Tato pravidla jsou rozsahu ID přiděleny určité ovládací prvky.Poskytnutím různými implementacemi různé funkce týkající se nápovědy člena můžete přepsat tato pravidla.
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_
Příkazy jednoduché "Help"
Existují dva jednoduché příkazy nápovědy, které jsou implementovány pomocí Microsoft Foundation Classes:
ID_HELP_INDEX, který je implementovánCWinApp::OnHelpIndex
ID_HELP_USING, který je implementovánCWinApp::OnHelpUsing
První příkaz zobrazí rejstřík nápovědy pro aplikaci.Druhá ukazuje Nápověda pro uživatele v programu WinHelp.
Kontextová nápověda (F1 Nápověda)
Klávesa F1 je obvykle přeložen do příkazu s ID ID_HELP pomocí akcelerátoru umístěn do hlavního okna tabulky akcelerátoru.ID_HELP Příkaz může být také generovány tlačítko s ID ID_HELP na hlavní okno nebo dialogové okno pole.
Bez ohledu na to, jak ID_HELP příkaz je generován, je směrována jako normální příkaz, dokud nedosáhne popisovač příkazu.Další informace o příkazu směrovací architekturou knihovny MFC naleznete v Technická poznámka: 21.Pokud má aplikace nápovědy povoleno, ID_HELP příkaz bude zpracována CWinApp::OnHelp.Objekt aplikace obdrží zprávu nápovědy a přesměruje příkazu odpovídajícím způsobem.To je nezbytné, protože výchozí příkaz směrování není dostatečné pro stanovení kontextu nejvíce specifické.
CWinApp::OnHelpdošlo k pokusu o spuštění nápovědy v následujícím pořadí:
Hledá aktivní AfxMessageBox volání s pomoci ID.Pokud je aktivní okno, je spuštěno WinHelp s kontextem, který je třeba toto okno se zprávou.
Odešle zprávu WM_COMMANDHELP na aktivní okno.Pokud okno neodpoví spuštěním WinHelp, tato zpráva se přemístí předchůdce tohoto okna dokud zpracovat zprávu nebo je aktuální okno okno nejvyšší úrovně.
Odešle příkaz ID_DEFAULT_HELP do hlavního okna.Tím se spustí výchozí Nápověda.Tento příkaz je obvykle mapován na CWinApp::OnHelpIndex.
Globálně přepsat výchozí ID základní hodnoty (např.) 0x10000 pro příkazy a 0x20000 zdroje jako jsou dialogová okna), aplikace musí přepsat CWinApp::WinHelp.
Pokud chcete přepsat tuto funkci a tak, že je určen nápovědy kontext, zpracovávat zprávy WM_COMMANDHELP.Můžete chtít poskytují podrobnější nápovědu směrování než poskytuje rámec, jak pouze funguje hluboké aktuální podřízené okno MDI.Můžete také poskytnout další nápovědu pro konkrétní okno nebo dialogové okno, případně na základě aktuální vnitřní stavu objektu nebo aktivní ovládací prvek v dialogovém okně.
WM_COMMANDHELP
afx_msg LRESULT CWnd::OnCommandHelp(WPARAM wParam, LPARAM lParam)
WM_COMMANDHELP je soukromá zpráva Windows MFC neobdrží aktivního okna, pokud je požadována pomoc.Pokud okno obdrží tuto zprávu, může volat CWinApp::WinHelp s kontextem, který odpovídá vnitřní stav v okně.
lParam
Obsahuje aktuálně dostupné nápovědy kontext.lParamPokud byla zjištěna žádná nápověda kontext je nula.Implementace OnCommandHelp pomocí ID kontextu v lParam k určit jiný kontext nebo jen předat k CWinApp::WinHelp.wParam
Není použit a bude nula.
Pokud OnCommandHelp volání funkce CWinApp::WinHelp, měl by být vrácen TRUE.Vrácení TRUE přestane směrování tohoto příkazu do jiných tříd a k dalším oknům.
Režim nápovědy (Nápověda Shift + F1)
Toto je druhý formulář kontextovou nápovědu.Tento režim obvykle zadává stisknutím kombinace kláves SHIFT + F1 nebo prostřednictvím nabídky panelu nástrojů.Je implementován jako příkaz (ID_CONTEXT_HELP).Háčkem filtr zprávy není použita k převodu tohoto příkazu při modálního dialogového okna nebo nabídka je aktivní, proto tento příkaz je k dispozici pouze uživateli, pokud aplikace provádí hlavní pumpu zpráv (CWinApp::Run).
Po zadání tohoto režimu je myší kurzor nápovědy se zobrazí přes všechny oblasti aplikace, i v případě, že aplikace by obvykle zobrazí vlastní kurzor pro tuto oblast (například změnu velikosti ohraničení kolem okna).Uživatel je schopen pomocí myši nebo klávesnice vyberte příkaz.Místo provádění příkazu, zobrazí nápovědu k tomuto příkazu.Navíc uživatel může kliknout na objekt viditelný na obrazovce, například na tlačítko na panelu nástrojů a zobrazí se Nápověda pro daný objekt.Tento režim nápovědy je k dispozici v CWinApp::OnContextHelp.
Během provádění této smyčky, všechny vstupy klávesnice je neaktivní, s výjimkou klíče, které přístup k nabídce.Také se stále provádí překlad příkazu prostřednictvím PreTranslateMessage umožňuje uživatelům stiskem klávesy akcelerátoru a vyvolat nápovědu k příkazu.
Pokud jsou zejména překlady nebo akce, přičemž umístěte PreTranslateMessage funkce, která by neměla probíhat během režimu SHIFT + F1 nápovědu, byste měli zkontrolovat m_bHelpMode člen CWinApp před provedením těchto operací.CDialog Provedení PreTranslateMessage to kontroluje před volací IsDialogMessage, např.SHIFT + F1 v režimu zakáže klávesy "dialog navigace" na nemodální dialogová okna.Kromě toho CWinApp::OnIdle je stále volány během této smyčky.
Pokud uživatel zvolí příkaz z nabídky, je zpracována jako nápovědu pro tento příkaz (prostřednictvím WM_COMMANDHELP, viz níže).Pokud uživatel klepne na viditelné části okna aplikace, není rozhodnuto, zda se jedná nonclient nebo klepněte na klienta.OnContextHelpmapování popisovačů nonclient klepne na kliknutí klienta automaticky.Je-li klepněte na klienta, potom odešle WM_HELPHITTEST do okna, které bylo kliknuto.Pokud okno vrátí nenulovou hodnotu, tato hodnota slouží jako kontextu nápovědu.Nula, vrátí-li OnContextHelp se pokusí nadřazené okno (které se nadřazené a podobně).Pokud nelze určit kontextové nápovědy, ve výchozím nastavení je poslat ID_DEFAULT_HELP příkaz do hlavního okna je pak (obvykle) mapována na CWinApp::OnHelpIndex.
WM_HELPHITTEST
afx_msg LRESULT CWnd::OnHelpHitTest(WPARAM, LPARAM lParam)
WM_HELPHITTEST je klepnutí SHIFT + F1 nápovědu v režimu aktivní okno Doručená zpráva windows soukromé knihovny MFC.Pokud okno obdrží tuto zprávu, vrátí ID nápovědy DWORD pro použití s WinHelp.
LOWORD(lParam)
obsahuje souřadnice osy x zařízení, kde bylo stisknuto tlačítko myši vzhledem ke klientské oblasti okna.HIWORD(lParam)
obsahuje souřadnice y.wParam
není použit a bude nula.Pokud je vrácená hodnota nenulová, se nazývá WinHelp s tímto kontextem.Je-li vrácená hodnota nulová, je dotazován nadřazené okno Nápověda.
V mnoha případech můžete využít přístupů k testování kódu, může již.Viz provádění CToolBar::OnHelpHitTest příklad zpracování WM_HELPHITTEST zprávy (kód využívá přístupů testovací kód používaný pro tlačítka a popisy v CControlBar).
Podpora průvodce aplikace knihovny MFC a MAKEHM
Průvodce aplikace knihovny MFC vytvoří soubory potřebné k sestavení souboru nápovědy (soubory .cnt a soubor s příponou HPJ).Zahrnuje také počet předem RTF soubory, které jsou přijímány kompilátoru nápovědy společnosti Microsoft.Mnoho témat je dokončeno, ale některé třeba upravit pro konkrétní aplikaci.
Automatické vytvoření souboru "pomoci mapování" je podporován nástroj nazvaný MAKEHM.Nástroj MAKEHM lze překládat prostředku aplikace.H souboru mapování souboru nápovědy.Příklad:
#define IDD_MY_DIALOG 2000
#define ID_MY_COMMAND 150
budou přeloženy do:
HIDD_MY_DIALOG 0x207d0
HID_MY_COMMAND 0x10096
Tento formát je kompatibilní se zařízením kompilátor nápovědy, která mapuje názvy témat (symboly na levé straně) ID kontextu (čísla na pravé straně).
Zdrojový kód pro MAKEHM je k dispozici v ukázce knihovny MFC programování nástroje MAKEHM.
Přidání nápovědy po spuštění Průvodce aplikací knihovny MFC
Chcete-li zkontrolovat možnost "Context-sensitive Help" na stránce Pokročilé funkce Průvodce aplikací knihovny MFC před vytvořením aplikace je nejlepší způsob, jak přidat nápovědu k aplikaci.Tak Průvodce aplikací knihovny MFC automaticky přidá nezbytné zprávy položek mapy do vašeho CWinApp-odvozené třídy pro podporu nápovědy.
Nápověda k zprávami
Nápovědu týkající se zprávou (někdy se nazývá oznámení) je podporováno až AfxMessageBox funkce, obálka pro MessageBox rozhraní API systému Windows.
Existují dvě verze AfxMessageBox, jeden pro použití s ID řetězce a další pomocí ukazatele na řetězec (LPCSTR):
int AFXAPI AfxMessageBox(LPCSTR lpszText, UINT nType, UINT nIDHelp);
int AFXAPI AfxMessageBox(UINT nIDPrompt, UINT nType, UINT nIDHelp);
V obou případech je volitelné Nápověda ID.
V prvním případě výchozí hodnota nIDHelp je 0, což znamená žádná nápověda pro toto okno se zprávou.Pokud uživatel stiskne klávesu F1, zatímco například zpráva je aktivní pole, uživatel neobdrží pomoc (i v případě, že aplikace podporuje usnadnění).Pokud to není žádoucí, je třeba stanovit nIDHelp a ID nápovědy.
V druhém případě je výchozí hodnota pro nIDHelp -1, což znamená, že nápověda ID je stejný jako nIDPrompt.Nápověda bude fungovat pouze v případě, že aplikace je povolena Nápověda, samozřejmě).0 pro nIDHelp by měla poskytnout, pokud chcete, aby okna se zprávou se žádná Nápověda a odborná pomoc.Se má zpráva nápovědy povolena, ale touží pomoc jiné ID, než nIDPrompt, jednoduše stanovit odlišnou nIDPrompt nIDHelp kladnou hodnotu.