Sdílet prostřednictvím

TN028: Podpora kontextové nápovědy

  • Článek

Tato poznámka popisuje pravidla pro přiřazování ID kontextů nápovědy a dalších problémů nápovědy v prostředí MFC. Podpora nápovědy citlivé na kontext vyžaduje kompilátor nápovědy, který je k dispozici v jazyce Visual C++.

Poznámka

Kromě implementace nápovědy citlivé na kontext pomocí WinHelp podporuje MFC také použití nápovědy HTML. Další informace o této podpoře a programování pomocí nápovědy HTML naleznete v nápovědě HTML: Kontextově citlivá nápověda pro vaše programy.

Podporované typy nápovědy

Existují dva typy kontextové nápovědy implementované v aplikacích pro Windows. První, označovaná jako "Nápověda F1", zahrnuje spuštění WinHelp s odpovídajícím kontextem na základě aktuálně aktivního objektu. Druhý je režim Shift+ F1. V tomto režimu se kurzor myši změní na kurzor nápovědy a uživatel pokračuje kliknutím na objekt. V tomto okamžiku je WinHelp spuštěna, aby poskytla nápovědu pro objekt, na který uživatel klikl.

Třídy Služby Microsoft Foundation implementují obě tyto formy nápovědy. Kromě toho architektura podporuje dva jednoduché příkazy nápovědy, index nápovědy a použití nápovědy.

Soubory nápovědy

Třídy Služby Microsoft Foundation předpokládají jeden soubor nápovědy. Tento soubor nápovědy musí mít stejný název a cestu jako aplikace. Pokud je například spustitelný soubor C:\MyApplication\MyHelp.exe, musí být soubor nápovědy C:\MyApplication\MyHelp.hlp. Cestu nastavíte prostřednictvím m_pszHelpFilePath členské proměnné CWinApp Class.

Rozsahy kontextu nápovědy

Výchozí implementace knihovny MFC vyžaduje, aby program dodržoval některá pravidla týkající se přiřazení ID kontextu nápovědy. Tato pravidla představují řadu ID přidělených konkrétním ovládacím prvkům. Tato pravidla můžete přepsat poskytnutím různých implementací různých členských funkcí souvisejících s nápovědou.

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_

Jednoduché příkazy "Nápověda"

Existují dva jednoduché příkazy nápovědy implementované třídami Microsoft Foundation:

První příkaz zobrazí index nápovědy pro aplikaci. Druhá zobrazuje uživatelskou nápovědu k používání programu WinHelp.

Kontextová nápověda (nápověda F1)

Klávesa F1 se obvykle překládá na příkaz s ID ID_HELP akcelerátorem umístěným do tabulky akcelerátoru hlavního okna. Příkaz ID_HELP může být také generován tlačítkem s ID ID_HELP v hlavním okně nebo dialogovém okně.

Bez ohledu na to, jak se příkaz ID_HELP vygeneruje, se směruje jako normální příkaz, dokud nedosáhne obslužné rutiny příkazu. Další informace o architektuře směrování příkazů MFC najdete v technické poznámce 21. Pokud má aplikace povolenou nápovědu, bude ID_HELP příkaz zpracován CWinApp ::OnHelp. Objekt aplikace obdrží zprávu nápovědy a pak příkaz odpovídajícím způsobem směruje. To je nezbytné, protože výchozí směrování příkazů není adekvátní k určení nejvýraznějšího kontextu.

CWinApp::OnHelp pokusí spustit WinHelp v následujícím pořadí:

  1. Kontroluje aktivní AfxMessageBox hovor s ID nápovědy. Pokud je pole zprávy aktuálně aktivní, spustí se WinHelp s kontextem, který je pro toto pole zprávy vhodný.

  2. Odešle zprávu WM_COMMANDHELP do aktivního okna. Pokud toto okno nereaguje spuštěním nástroje WinHelp, odešle se stejná zpráva nadřazeným členům tohoto okna, dokud se zpráva nezpracuje nebo aktuální okno není okno nejvyšší úrovně.

  3. Odešle příkaz ID_DEFAULT_HELP do hlavního okna. Tím se vyvolá výchozí nápověda. Tento příkaz je obecně namapován na CWinApp::OnHelpIndex.

Pokud chcete globálně přepsat výchozí základní hodnoty ID (například 0x10000 pro příkazy a 0x20000 pro prostředky, jako jsou dialogy), měla by aplikace přepsat CWinApp::WinHelp.

Chcete-li tuto funkci přepsat a určit způsob, jakým je určen kontext nápovědy, měli byste zpracovat WM_COMMANDHELP zprávu. Můžete chtít poskytnout konkrétnější směrování nápovědy, než poskytuje architektura, protože jde pouze do hloubky jako aktuální podřízené okno MDI. Můžete také poskytnout konkrétnější nápovědu pro konkrétní okno nebo dialogové okno, třeba na základě aktuálního interního stavu tohoto objektu nebo aktivního ovládacího prvku v dialogovém okně.

WM_COMMANDHELP

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

WM_COMMANDHELP je soukromá zpráva prostředí Windows MFC, která je přijata aktivním oknem při vyžádání nápovědy. Když okno obdrží tuto zprávu, může volat CWinApp::WinHelp s kontextem, který odpovídá internímu stavu okna.

Lparam
Obsahuje aktuálně dostupný kontext nápovědy. LParam je nula, pokud nebyl zjištěn žádný kontext nápovědy. Implementace OnCommandHelp může použít ID kontextu v lParam k určení jiného kontextu nebo může pouze předat .CWinApp::WinHelp

wParam
Nepoužívá se a bude nula.

OnCommandHelp Pokud funkce voláCWinApp::WinHelp, měla by vrátit hodnotu PRAVDA. Vrácení hodnoty TRUE zastaví směrování tohoto příkazu do jiných tříd a do jiných oken.

Režim nápovědy (nápověda Shift+F1)

Toto je druhá forma kontextové nápovědy. Obecně platí, že tento režim se používá stisknutím kombinace kláves SHIFT+F1 nebo pomocí nabídky nebo panelu nástrojů. Implementuje se jako příkaz (ID_CONTEXT_HELP). Háček filtru zpráv se nepoužívá k překladu tohoto příkazu v době, kdy je aktivní modální dialogové okno nebo nabídka, a proto je tento příkaz k dispozici pouze uživateli, když aplikace spouští hlavní čerpadlo zpráv (CWinApp::Run).

Po přechodu do tohoto režimu se kurzor myši nápovědy zobrazí ve všech oblastech aplikace, i když by aplikace normálně zobrazovala vlastní kurzor pro danou oblast (například ohraničení velikosti kolem okna). Uživatel může k výběru příkazu použít myš nebo klávesnici. Místo spuštění příkazu se zobrazí nápověda k danému příkazu. Uživatel může také kliknout na viditelný objekt na obrazovce, například na tlačítko na panelu nástrojů, a nápověda se zobrazí pro daný objekt. Tento režim nápovědy poskytuje CWinApp::OnContextHelp.

Během provádění této smyčky je veškerý vstup klávesnice neaktivní, s výjimkou kláves, které přistupí k nabídce. Překlad příkazů se také provádí prostřednictvím, PreTranslateMessage aby uživatel mohl stisknout klávesu akcelerátoru a získat pomoc s tímto příkazem.

Pokud ve funkci probíhají PreTranslateMessage konkrétní překlady nebo akce, které by se neměly provádět v režimu nápovědy SHIFT+F1, měli byste před provedením těchto operací zkontrolovat m_bHelpMode člena CWinApp . PreTranslateMessage Implementace CDialog kontroly před voláním IsDialogMessage, například. Tím se v bezmodových dialogech během režimu SHIFT+F1 zakáže "navigace v dialogovém okně". Kromě toho se CWinApp::OnIdle během této smyčky stále volá.

Pokud uživatel vybere příkaz z nabídky, zpracuje se jako nápověda pro tento příkaz (prostřednictvím WM_COMMANDHELP viz níže). Pokud uživatel klikne na viditelnou oblast okna aplikace, určí se, jestli se jedná o neklikání klienta nebo o kliknutí klienta. OnContextHelp zpracovává mapování kliknutí jiných klientů na klientská kliknutí automaticky. Pokud se jedná o kliknutí klienta, odešle WM_HELPHITTEST do okna, na které se kliklo. Pokud toto okno vrátí nenulovou hodnotu, použije se tato hodnota jako kontext nápovědy. Pokud vrátí nulu, OnContextHelp pokusí se nadřazené okno (a dojde k jeho selhání, nadřazený objekt atd.). Pokud kontext nápovědy nelze určit, výchozí hodnota je odeslat ID_DEFAULT_HELP příkaz do hlavního okna, což je pak (obvykle) namapováno na CWinApp::OnHelpIndex.

WM_HELPHITTEST

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

WM_HELPHITTEST je zpráva o privátních oknech MFC, která byla přijata aktivním oknem při kliknutí během režimu nápovědy SHIFT+F1. Když okno obdrží tuto zprávu, vrátí ID nápovědy DWORD pro použití winHelp.

LOWORD(lParam) obsahuje souřadnici zařízení osy X, kde byla myš klikaná vzhledem k oblasti klienta okna.

HIWORD(lParam) obsahuje souřadnici osy Y.

wParam
se nepoužívá a bude nula. Pokud je návratová hodnota nenulová, winHelp je volána s tímto kontextem. Pokud je návratová hodnota nula, zobrazí se dotaz na pomoc nadřazené okno.

V mnoha případech můžete využít kód pro testování, který už máte. Podívejte se na implementaci příkladu CToolBar::OnHelpHitTest zpracování WM_HELPHITTEST zprávy (kód využívá kód hit-test použitý u tlačítek a popisů tlačítek).CControlBar

Podpora průvodce aplikací MFC a MAKEHM

Průvodce aplikací MFC vytvoří potřebné soubory k vytvoření souboru nápovědy (soubory .cnt a .hpj). Obsahuje také řadu předem připravených souborů .rtf, které přijímá microsoft Help Compiler. Řada témat je hotová, ale některé můžou být potřeba upravit pro vaši konkrétní aplikaci.

Automatické vytvoření souboru "mapování nápovědy" je podporováno nástrojem s názvem MAKEHM. Nástroj MAKEHM může přeložit prostředek aplikace. Soubor H na soubor mapování nápovědy. Příklad:

#define IDD_MY_DIALOG   2000
#define ID_MY_COMMAND   150

se přeloží do:

HIDD_MY_DIALOG    0x207d0
HID_MY_COMMAND    0x10096

Tento formát je kompatibilní s objektem kompilátoru nápovědy, který mapuje ID kontextu (čísla na pravé straně) s názvy témat (symboly na levé straně).

Zdrojový kód pro MAKEHM je k dispozici v ukázce MAKEHM programovacích nástrojů MFC.

Přidání podpory nápovědy po spuštění Průvodce aplikací MFC

Nejlepší způsob, jak do aplikace přidat nápovědu, je před vytvořením aplikace zkontrolovat možnost Kontextově citlivá nápověda na stránce Rozšířené funkce v Průvodci aplikací MFC. Průvodce aplikací MFC tak automaticky přidá potřebné položky mapy zpráv do vaší CWinApp-odvozené třídy pro podporu nápovědy.

Nápověda ke zprávám

Nápověda ke zprávám (někdy označovaná jako upozornění) je podporována prostřednictvím AfxMessageBox funkce, obálky pro rozhraní API systému MessageBox Windows.

Existují dvě verze AfxMessageBox, jedna pro použití s ID řetězce a druhá pro použití s ukazatelem na řetězec (LPCSTR):

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

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

V oboupřípadechch

V prvním případě je výchozí hodnota nIDHelp 0, což značí, že pro toto pole zprávy není k dispozici žádná nápověda. Pokud uživatel stiskne klávesu F1, pokud je například pole se zprávou aktivní, uživatel neobdrží nápovědu (i když aplikace podporuje nápovědu). Pokud to není žádoucí, měli byste pro nIDHelp poskytnout ID nápovědy.

V druhém případě je výchozí hodnota nIDHelp -1, což označuje ID nápovědy je stejné jako nIDPrompt. Nápověda bude fungovat jenom v případě, že je aplikace povolená samozřejmě). Pokud chcete, aby okno se zprávou nemělo podporu nápovědy, měli byste zadat hodnotu 0 pro nIDHelp. Pokud chcete, aby byla zpráva povolená, ale potřebujete jiné ID nápovědy než nIDPrompt, jednoduše zadejte kladnou hodnotu pro nIDHelp odlišnou od hodnoty nIDPrompt.

Viz také

Technické poznámky podle čísel
Technické poznámky podle kategorií