Udostępnij za pośrednictwem

TN028: obsługa pomocy kontekstowej

  • Artykuł

W tej notatce opisano reguły przypisywania identyfikatorów kontekstów Pomocy i innych problemów pomocy w MFC. Obsługa pomocy kontekstowej wymaga kompilatora pomocy dostępnego w języku Visual C++.

Uwaga

Oprócz implementowania pomocy kontekstowej przy użyciu winHelp, MFC obsługuje również korzystanie z pomocy HTML. Aby uzyskać więcej informacji na temat tej obsługi i programowania w Pomocy HTML, zobacz Pomoc HTML: Pomoc kontekstowa dla programów.

Typy obsługiwanej pomocy

Istnieją dwa typy pomocy kontekstowej zaimplementowane w aplikacjach systemu Windows. Pierwszy, określany jako "Pomoc F1", polega na uruchomieniu narzędzia WinHelp z odpowiednim kontekstem na podstawie aktualnie aktywnego obiektu. Drugi to tryb "Shift+ F1". W tym trybie kursor myszy zmienia się na kursor pomocy, a użytkownik przechodzi do kliknięcia obiektu. W tym momencie zostanie uruchomiona aplikacja WinHelp, aby udzielić pomocy dla obiektu, który użytkownik kliknął.

Klasy programu Microsoft Foundation implementują obie te formy pomocy. Ponadto platforma obsługuje dwa proste polecenia pomocy: Indeks Pomocy i Korzystanie z pomocy.

Pliki pomocy

Klasy programu Microsoft Foundation zakładają pojedynczy plik Pomocy. Ten plik Pomocy musi mieć taką samą nazwę i ścieżkę jak aplikacja. Jeśli na przykład plik wykonywalny to C:\MyApplication\MyHelp.exe, plik pomocy musi mieć wartość C:\MyApplication\MyHelp.hlp. Ścieżkę należy ustawić za pomocą zmiennej składowej m_pszHelpFilePath klasy CWinApp.

Zakresy kontekstów Pomocy

Domyślna implementacja MFC wymaga, aby program przestrzegał pewnych reguł dotyczących przypisywania identyfikatorów kontekstu pomocy. Te reguły są szeregiem identyfikatorów przydzielonych do określonych kontrolek. Te reguły można zastąpić, udostępniając różne implementacje różnych funkcji elementów członkowskich związanych z pomocą.

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_

Proste polecenia "Pomoc"

Istnieją dwa proste polecenia Pomocy implementowane przez klasy programu Microsoft Foundation:

Pierwsze polecenie pokazuje indeks Pomocy dla aplikacji. Drugi pokazuje pomoc użytkownika dotyczącą korzystania z programu WinHelp.

Pomoc kontekstowa (pomoc F1)

Klucz F1 jest zwykle tłumaczony na polecenie o identyfikatorze ID_HELP przez akcelerator umieszczony w tabeli akceleratora głównego okna. Polecenie ID_HELP może być również generowane przez przycisk z identyfikatorem ID_HELP w oknie głównym lub oknie dialogowym.

Niezależnie od sposobu generowania polecenia ID_HELP jest on kierowany jako normalne polecenie, dopóki nie osiągnie programu obsługi poleceń. Aby uzyskać więcej informacji na temat architektury routingu poleceń MFC, zapoznaj się z uwagami technicznymi 21. Jeśli aplikacja ma włączoną pomoc, polecenie ID_HELP będzie obsługiwane przez CWinApp::OnHelp. Obiekt aplikacji odbiera komunikat pomocy, a następnie odpowiednio kieruje polecenie. Jest to konieczne, ponieważ domyślny routing poleceń nie jest odpowiedni do określania najbardziej konkretnego kontekstu.

CWinApp::OnHelp próbuje uruchomić narzędzie WinHelp w następującej kolejności:

  1. Sprawdza aktywne AfxMessageBox wywołanie przy użyciu identyfikatora pomocy. Jeśli pole komunikatu jest obecnie aktywne, winHelp jest uruchamiane z kontekstem odpowiednim dla tego pola komunikatu.

  2. Wysyła komunikat WM_COMMANDHELP do aktywnego okna. Jeśli to okno nie odpowiada, uruchamiając narzędzie WinHelp, ten sam komunikat jest wysyłany do elementów głównych tego okna do momentu przetworzenia komunikatu lub bieżącego okna jest oknem najwyższego poziomu.

  3. Wysyła polecenie ID_DEFAULT_HELP do okna głównego. Spowoduje to wywołanie domyślnej Pomocy. To polecenie jest ogólnie mapowane na CWinApp::OnHelpIndex.

Aby globalnie zastąpić domyślne wartości podstawowe identyfikatora (np. 0x10000 dla poleceń i 0x20000 dla zasobów, takich jak okna dialogowe), aplikacja powinna zastąpić CWinApp::WinHelp.

Aby zastąpić tę funkcję i sposób określania kontekstu Pomocy, należy obsługiwać komunikat WM_COMMANDHELP. Możesz podać bardziej szczegółowy routing Pomocy niż zapewnia platforma, ponieważ jest to tylko tak głębokie, jak bieżące okno podrzędne MDI. Możesz również podać bardziej szczegółową pomoc dla określonego okna lub okna dialogowego, na przykład na podstawie bieżącego wewnętrznego stanu tego obiektu lub aktywnej kontrolki w oknie dialogowym.

WM_COMMANDHELP

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

WM_COMMANDHELP to prywatny komunikat MFC systemu Windows, który jest odbierany przez aktywne okno po zażądaniu pomocy. Gdy okno odbierze ten komunikat, może zostać wywołane CWinApp::WinHelp z kontekstem zgodnym ze stanem wewnętrznym okna.

Lparam
Zawiera obecnie dostępny kontekst Pomocy. parametr lParam jest zerowy , jeśli nie określono kontekstu Pomocy. Implementacja OnCommandHelp może użyć identyfikatora kontekstu w lParam do określenia innego kontekstu lub może po prostu przekazać go do CWinApp::WinHelp.

Wparam
Nie jest używany i będzie mieć wartość zero.

Jeśli funkcja wywołuje metodę OnCommandHelp , powinna zwrócić wartość TRUE.CWinApp::WinHelp Zwracanie wartości TRUE powoduje zatrzymanie routingu tego polecenia do innych klas i innych okien.

Tryb pomocy (Shift+F1 — Pomoc)

Jest to druga forma pomocy kontekstowej. Ogólnie rzecz biorąc, ten tryb jest wprowadzany przez naciśnięcie klawiszy SHIFT+F1 lub za pomocą menu/paska narzędzi. Jest on implementowany jako polecenie (ID_CONTEXT_HELP). Hak filtru komunikatów nie jest używany do tłumaczenia tego polecenia, gdy modalne okno dialogowe lub menu jest aktywne, dlatego to polecenie jest dostępne tylko dla użytkownika, gdy aplikacja wykonuje pompę komunikatów głównych (CWinApp::Run).

Po wprowadzeniu tego trybu kursor myszy Pomocy jest wyświetlany na wszystkich obszarach aplikacji, nawet jeśli aplikacja normalnie wyświetla własny kursor dla tego obszaru (na przykład obramowanie rozmiaru wokół okna). Użytkownik może użyć myszy lub klawiatury do wybrania polecenia. Zamiast wykonywać polecenie, zostanie wyświetlona Pomoc w tym poleceniu. Ponadto użytkownik może kliknąć widoczny obiekt na ekranie, taki jak przycisk na pasku narzędzi, a Pomoc zostanie wyświetlona dla tego obiektu. Ten tryb Pomocy jest udostępniany przez CWinApp::OnContextHelpprogram .

Podczas wykonywania tej pętli wszystkie dane wejściowe klawiatury są nieaktywne, z wyjątkiem klawiszy, które uzyskują dostęp do menu. Ponadto tłumaczenie poleceń jest nadal wykonywane za pomocą polecenia PreTranslateMessage , aby umożliwić użytkownikowi naciśnięcie klawisza akceleratora i otrzymanie pomocy dotyczącej tego polecenia.

Jeśli w funkcji występują konkretne tłumaczenia lub akcje, które nie powinny być wykonywane PreTranslateMessage w trybie pomocy SHIFT+F1, przed wykonaniem tych operacji należy sprawdzić element CWinApp członkowski m_bHelpMode. Implementacja CDialogPreTranslateMessage kontroli przed wywołaniem IsDialogMessagemetody , na przykład. Spowoduje to wyłączenie klawiszy "nawigacji okna dialogowego" w oknach dialogowych bez moderowania w trybie SHIFT+F1. Ponadto CWinApp::OnIdle funkcja jest nadal wywoływana w trakcie tej pętli.

Jeśli użytkownik wybierze polecenie z menu, jest on obsługiwany jako pomoc w tym poleceniu (za pośrednictwem WM_COMMANDHELP, zobacz poniżej). Jeśli użytkownik kliknie widoczny obszar okna aplikacji, należy określić, czy jest to kliknięcie klienta, czy kliknięcie klienta. OnContextHelp obsługuje automatyczne mapowanie kliknięć niekliencki na klienta. Jeśli jest to kliknięcie klienta, wysyła WM_HELPHITTEST do klikniętego okna. Jeśli to okno zwraca wartość niezerową, ta wartość jest używana jako kontekst pomocy. Jeśli zwraca zero, OnContextHelp spróbuje okno nadrzędne (i kończy się niepowodzeniem, jego element nadrzędny itd.). Jeśli nie można określić kontekstu Pomocy, wartością domyślną jest wysłanie polecenia ID_DEFAULT_HELP do okna głównego, które jest następnie (zwykle) mapowane na CWinApp::OnHelpIndex.

WM_HELPHITTEST

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

WM_HELPHITTEST to prywatny komunikat systemu Windows MFC, który jest odbierany przez aktywne okno kliknięte podczas trybu pomocy SHIFT+F1. Gdy okno odbierze ten komunikat, zwraca identyfikator pomocy DWORD do użycia przez WinHelp.

LOWORD(lParam) zawiera współrzędną urządzenia osi X, gdzie mysz została kliknięta względem obszaru klienta okna.

HIWORD(lParam) zawiera współrzędną osi Y.

Wparam
nie jest używana i będzie równa zero. Jeśli wartość zwracana jest niezerowa, winHelp jest wywoływana z tym kontekstem. Jeśli zwracana wartość to zero, w oknie nadrzędnym zostanie wyświetlone zapytanie o pomoc.

W wielu przypadkach możesz wykorzystać kod testowania trafień, który mógł już istnieć. Zobacz implementację CToolBar::OnHelpHitTest przykładu obsługi komunikatu WM_HELPHITTEST (kod korzysta z kodu testowego używanego na przyciskach i etykietkach narzędzi w programie CControlBar).

Obsługa kreatora aplikacji MFC i MAKEHM

Kreator aplikacji MFC tworzy pliki niezbędne do utworzenia pliku Pomocy (pliki cnt i hpj). Zawiera również wiele wstępnie utworzonych plików rtf, które są akceptowane przez kompilator Pomocy firmy Microsoft. Wiele tematów zostało ukończonych, ale niektóre z nich mogą być modyfikowane dla określonej aplikacji.

Automatyczne tworzenie pliku "mapowanie pomocy" jest obsługiwane przez narzędzie o nazwie MAKEHM. Narzędzie MAKEHM może przetłumaczyć zasób aplikacji. Plik H do pliku mapowania Pomocy. Przykład:

#define IDD_MY_DIALOG   2000
#define ID_MY_COMMAND   150

zostanie przetłumaczony na:

HIDD_MY_DIALOG    0x207d0
HID_MY_COMMAND    0x10096

Ten format jest zgodny z obiektem kompilatora Pomocy, który mapuje identyfikatory kontekstu (liczby po prawej stronie) z nazwami tematów (symbolami po lewej stronie).

Kod źródłowy programu MAKEHM jest dostępny w przykładzie MAKEHM MFC Programming Utilities.

Dodawanie pomocy technicznej po uruchomieniu Kreatora aplikacji MFC

Najlepszym sposobem dodania pomocy do aplikacji jest sprawdzenie opcji "Pomoc kontekstowa" na stronie Funkcje zaawansowane Kreatora aplikacji MFC przed utworzeniem aplikacji. Dzięki temu Kreator aplikacji MFC automatycznie dodaje niezbędne wpisy mapy komunikatów do klasy CWinApp-pochodnej w celu obsługi Pomocy.

Pomoc dotycząca pól komunikatów

Pomoc dotycząca pól komunikatów (czasami nazywanych alertami) jest obsługiwana za pośrednictwem AfxMessageBox funkcji , otoki interfejsu MessageBox API systemu Windows.

Istnieją dwie wersje AfxMessageBoxelementu , jeden do użycia z identyfikatorem ciągu, a drugi do użycia ze wskaźnikiem do ciągu (LPCSTR):

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

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

W obu przypadkach istnieje opcjonalny identyfikator pomocy.

W pierwszym przypadku wartość domyślna nIDHelp to 0, która nie wskazuje pomocy dla tego pola komunikatu. Jeśli użytkownik naciśnie klawisz F1, gdy takie jak pole komunikatu jest aktywne, użytkownik nie otrzyma pomocy (nawet jeśli aplikacja obsługuje Pomoc). Jeśli nie jest to pożądane, należy podać identyfikator pomocy dla nIDHelp.

W drugim przypadku wartość domyślna nIDHelp to -1, która wskazuje, że identyfikator pomocy jest taki sam jak nIDPrompt. Pomoc będzie działać tylko wtedy, gdy aplikacja jest włączona, oczywiście). Jeśli chcesz, aby pole komunikatu nie obsługiwało pomocy technicznej, należy podać wartość 0 dla elementu nIDHelp. Jeśli chcesz włączyć komunikat Pomoc, ale chcesz uzyskać inny identyfikator pomocy niż nIDPrompt, po prostu podaj dodatnią wartość nIDHelp inną niż nIDPrompt.

Zobacz też

Uwagi techniczne według numerów
Uwagi techniczne według kategorii