TN028: obsługa pomocy kontekstowej
Uwaga ta opisuje zasady przypisywania identyfikatorów kontekstów pomocy i innych kwestii pomocy w MFC.Obsługa pomoc kontekstową wymaga kompilatora pomocy, który jest dostępny w programie Visual C++.
[!UWAGA]
Oprócz wykonywania pomocy kontekstowej używając programu WinHelp, MFC obsługuje także, przy użyciu pomocy w formacie HTML.Aby uzyskać więcej informacji na temat tej obsługi i programowania przy pomocy w formacie HTML, zobacz pomocy w formacie HTML: Context-Sensitive Pomoc dla programów swój.
Rodzaje pomocy, obsługiwane
Istnieją dwa rodzaje pomocy kontekstowej zaimplementowane w aplikacjach systemu Windows.Pierwszy, zwany "Pomoc F1" polega na uruchamianiu WinHelp z odpowiedniego kontekstu na podstawie aktualnie aktywnego obiektu.Druga jest tryb "Shift + F1".W tym trybie kursor myszy zmienia się na kursor pomocy, a użytkownik przechodzi do kliknij obiekt.W tym momencie WinHelp jest uruchamiane udzielenia pomocy dla obiektu, który kliknął użytkownik.
Microsoft Foundation Classes w życie obu tych formach pomocy.Ponadto platforma obsługuje dwa polecenia Pomoc prosty indeks pomocy i korzystanie z pomocy.
Pliki pomocy
Microsoft Foundation classes założono pojedynczego pliku pomocy.Ten plik pomocy musi mieć taką samą nazwę i ścieżkę jako aplikacja.Na przykład jeśli plik wykonywalny jest C:\MyApplication\MyHelp.exe do pliku pomocy musi być C:\MyApplication\MyHelp.hlp.Ustawianie ścieżki za pomocą m_pszHelpFilePath zmienną z Klasa CWinApp.
Zakresy kontekstu pomocy
Domyślna implementacja MFC wymaga programu do reguły dotyczące przypisania kontekstu pomocy identyfikatorów.Zasady te są zakres identyfikatorów przydzielone do określonych kontroli.Reguły te można zastąpić, dostarczając różne implementacje różnych funkcji dotyczących pomocy państwa.
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_
Polecenia prosty "pomoc"
Istnieją dwa prostych poleceń pomocy, które są implementowane przez Microsoft Foundation Classes:
ID_HELP_INDEX, który jest wykonywany przezCWinApp::OnHelpIndex
ID_HELP_USING, który jest wykonywany przezCWinApp::OnHelpUsing
Pierwsze polecenie zawiera indeks pomocy dla aplikacji.Drugi pokazuje pomoc użytkownika przy użyciu programu Pomoc systemu Windows.
Pomoc kontekstowa (Pomoc F1)
Klawisz F1 zazwyczaj jest tłumaczony na polecenie o identyfikatorze ID_HELP przez akcelerator umieszczane w głównym oknie akcelerator tabeli.ID_HELP Polecenie może być również generowany przez przycisk o identyfikatorze ID_HELP na główne okno lub okno dialogowe.
Bez względu na sposób, w jaki ID_HELP polecenia jest generowany, aż osiągnie on program obsługi poleceń jest przesyłana jako polecenie Normalny.Aby uzyskać więcej informacji na temat architektury polecenia routingu MFC odnoszą się do technicznej 21 Uwaga.Jeśli aplikacja ma włączone, Pomoc ID_HELP polecenia zostanie obsłużony przez CWinApp::OnHelp.Obiekt application odbiera komunikat pomocy, a następnie przekierowuje odpowiednio polecenie.Jest to konieczne, ponieważ routing polecenia domyślne nie są wystarczające do określenia najbardziej szczególnym kontekście.
CWinApp::OnHelppróbuje uruchomić WinHelp w następującej kolejności:
Sprawdza, czy aktywny AfxMessageBox zadzwonić do pomocy ID.Jeśli okno komunikatu jest obecnie aktywne, WinHelp jest uruchamiany w kontekście właściwe jest to okno.
Wysyła wiadomość WM_COMMANDHELP do aktywnego okna.Jeśli to okno nie odpowiada poprzez uruchomienie WinHelp, tej samej wiadomości są następnie wysyłane przodków danego okna aż wiadomość jest przetwarzana lub bieżące okno jest okno najwyższego poziomu.
Wysyła polecenie ID_DEFAULT_HELP do głównego okna.Wywołuje Pomoc domyślną.Polecenie to zazwyczaj jest mapowany do CWinApp::OnHelpIndex.
Aby globalnie zastąpić domyślne wartości podstawowe ID (np. 0x10000 dla poleceń i 0x20000 dla zasobów, takich jak okna dialogowe), aplikacji należy zastąpić CWinApp::WinHelp.
Aby zastąpić tę funkcję i sposób ustalona w kontekście pomocy, powinien obsługiwać komunikat WM_COMMANDHELP.Możesz routują bardziej szczegółowych pomocy niż środowisko framework zapewnia, jak to tylko jest tak głęboko bieżącego okna podrzędnego MDI.Można również dostarczać bardziej szczegółowe Pomoc dla okno lub okno dialogowe, może być oparte na bieżący stan wewnętrzny tego obiektu lub aktywnego formantu w oknie dialogowym.
WM_COMMANDHELP
afx_msg LRESULT CWnd::OnCommandHelp(WPARAM wParam, LPARAM lParam)
WM_COMMANDHELP jest prywatną wiadomość Windows MFC otrzymany przez aktywnego okna, gdy pomoc zostanie wywołana.Gdy okno otrzymuje tę wiadomość, może wywołać CWinApp::WinHelp z kontekstem pasujący okna stanu wewnętrznego.
lParam
Zawiera aktualnie dostępne kontekstu pomocy.lParamjest równa zero, jeśli brak kontekstu Pomoc zostały ustalone.Implementacja OnCommandHelp można użyć Identyfikatora kontekstu w lParam do określenia różnych kontekstu lub po prostu można przekazać go do CWinApp::WinHelp.wParam
Nie jest używany i będzie równa zero.
Jeśli OnCommandHelp wywołania funkcji CWinApp::WinHelp, powinien zwrócić TRUE.Zwracanie TRUE Zatrzymuje routing to polecenie na inne grupy ubezpieczeń, a także do innych okien.
Tryb Pomoc (Shift + F1 Pomoc)
Jest to druga forma pomocy kontekstowej.Ogólnie rzecz biorąc w tym trybie jest wprowadzana przez naciśnięcie klawisza SHIFT + F1 lub za pośrednictwem narzędzi/menu.Jest ona zrealizowana jako polecenia (ID_CONTEXT_HELP).Hak filtr wiadomości nie jest używany do tłumaczenia tego polecenia podczas modalnego okna dialogowego lub menu jest aktywne, dlatego to polecenie jest dostępne tylko dla użytkownika przy aplikacja jest wykonywany pompy głównej wiadomości (CWinApp::Run).
Po wprowadzeniu tego trybu, kursor myszy pomocy jest wyświetlany na wszystkich obszarach aplikacji, nawet jeśli aplikacja normalnie byłyby wyświetlane własnej kursor dla danego obszaru (na przykład zmiany rozmiaru obramowania okna).Użytkownik jest w stanie wybierz polecenie za pomocą myszy lub klawiatury.Zamiast wykonywania polecenia, uzyskać pomoc na temat tego polecenia jest wyświetlany.Ponadto użytkownik może kliknąć obiekt widoczne na ekranie, takich jak przycisk na pasku narzędzi i pomocy będą wyświetlane dla tego obiektu.Ten rodzaj pomocy jest świadczone przez CWinApp::OnContextHelp.
Podczas wykonywania tej pętli, wszystkie klawiatury input jest nieaktywny, z wyjątkiem dla kluczy, które uzyskać dostęp do menu.Ponadto polecenia nadal wykonywana za pośrednictwem PreTranslateMessage Aby zezwolić użytkownikowi na naciśnij klawisz skrótu i uzyskać pomoc dotyczącą tego polecenia.
Jeżeli istnieją szczególne tłumaczenia lub działań w tej dziedzinie należy umieścić w PreTranslateMessage funkcji, które nie powinno mieć miejsce podczas trybu SHIFT + F1 Pomoc, należy sprawdzić m_bHelpMode członek CWinApp przed wykonaniem tych czynności.CDialog Realizacji PreTranslateMessage to sprawdza przed wywołaniem funkcji IsDialogMessage, np.W trybie SHIFT + F1 powoduje wyłączenie kluczy "okno Nawigacja" na Niemodalne okna dialogowe.Dodatkowo CWinApp::OnIdle nadal jest wywoływana podczas tej pętli.
Jeśli użytkownik wybierze polecenie z menu, jest on traktowany jak uzyskać pomoc na temat tego polecenia (przez WM_COMMANDHELP, patrz poniżej).Jeśli użytkownik klika widoczny obszar okna aplikacji, dokonywana jest ustalenie, czy jest to nonclient lub kliknij klienta.OnContextHelpMapowanie uchwyty nonclient klika automatycznie kliknięć klienta.Jeśli jest kliknij klienta, a następnie wysyła WM_HELPHITTEST do okna, który został kliknięty.Jeśli okno zwraca wartość różną od zera, że wartość jest używana jako kontekst dla pomocy.Jeśli funkcja zwraca wartość 0, OnContextHelp próbuje okno nadrzędne (i nie spełniając tego, nadrzędnego i tak dalej).Jeśli nie można określić kontekstu pomocy, ustawieniem domyślnym jest wysyłanie ID_DEFAULT_HELP polecenia do głównego okna, który jest mapowany (zazwyczaj) do CWinApp::OnHelpIndex.
WM_HELPHITTEST
afx_msg LRESULT CWnd::OnHelpHitTest(WPARAM, LPARAM lParam)
WM_HELPHITTEST jest wiadomość prywatną windows MFC otrzymany przez aktywne okno kliknięciu w trybie pomocy SHIFT + F1.Po oknie wyświetlany jest następujący komunikat, zwraca identyfikator pomocy DWORD do użytku przez WinHelp.
LOWORD(lParam)
zawiera współrzędnych urządzenia osi x, gdzie został kliknięty przycisk myszy względem obszaru klienta okna.HIWORD(lParam)
zawiera współrzędnej osi y.wParam
nie jest używany i będzie równa zero.Jeśli wartość zwracana jest różna od zera, WinHelp jest wywoływana z tego kontekstu.Jeśli wartość zwracana jest wartość zero, okno nadrzędne jest badany pod kątem pomocy.
W wielu przypadkach można wykorzystać badania hit kodu, który już masz.Zobacz wykonania CToolBar::OnHelpHitTest na przykład obsługi WM_HELPHITTEST wiadomości (kod wykorzystuje kod hit test używany na przyciskach i etykietki narzędzi w CControlBar).
Obsługa kreatora aplikacji MFC i MAKEHM
Kreator aplikacji MFC tworzy pliki niezbędne do utworzenia pliku pomocy (plików .hpj i .cnt).Obejmuje to również liczbę plików .rtf gotowe, które są akceptowane przez kompilatorem Pomocy.Wiele tematów są kompletne, ale niektóre mogą wymagać modyfikacji dla konkretnego zastosowania.
Automatyczne tworzenie pliku "pomoc mapowania" jest obsługiwane przez narzędzie o nazwie MAKEHM.Narzędzia MAKEHM można tłumaczyć ZASOBU aplikacji.H plik do pliku mapowania pomocy.Na przykład:
#define IDD_MY_DIALOG 2000
#define ID_MY_COMMAND 150
zostanie zamieniona na:
HIDD_MY_DIALOG 0x207d0
HID_MY_COMMAND 0x10096
Ten format jest zgodny z kompilatora pomocy instrumentu, który mapuje identyfikatorów kontekstu (numery po prawej stronie) z nazwy tematów (symbole po lewej stronie).
Kod źródłowy dla MAKEHM jest dostępny w próbce narzędzia programowania MFC MAKEHM.
Dodawanie pomoc techniczna po uruchomieniu Kreatora aplikacji MFC
Aby zaznaczyć opcję "Context-sensitive Help" na stronie funkcje zaawansowane Kreatora aplikacji MFC przed utworzeniem aplikacji jest najlepszym sposobem, aby dodać Pomoc do aplikacji.W ten sposób Kreator aplikacji MFC automatycznie dodaje wpisy map wiadomości niezbędne do swojej CWinApp-klasy do obsługi pomocy.
Pomoc na temat okna komunikatów
Uzyskać pomoc na temat okien komunikatów (czasami nazywany alerty) jest obsługiwane za pośrednictwem AfxMessageBox funkcja, otoki dla MessageBox interfejsu API systemu Windows.
Istnieją dwie wersje AfxMessageBox, jeden do użytku z napis ID, a inny do użytku 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 jest opcjonalne Pomoc identyfikatora.
W pierwszym przypadku wartość domyślna dla nIDHelp jest 0, co oznacza pomoc dla tego okna komunikatu.Jeśli użytkownik naciśnie klawisz F1 podczas takich jak wiadomości pole jest aktywne, użytkownik nie otrzyma pomocy (nawet jeśli aplikacja obsługuje pomocy).Jeśli nie jest to pożądane, identyfikator pomocy należy przewidzieć nIDHelp.
W drugim przypadku wartością domyślną nIDHelp jest -1, która wskazuje, że identyfikator pomocy jest taka sama, jak nIDPrompt.Pomoc będzie działać tylko wtedy, gdy aplikacja jest włączona pomoc, oczywiście).0 powinien przewidywać nIDHelp, w razie potrzeby, że nie pomoc techniczna okna komunikatu.Jeżeli chcesz wiadomość do pomocy włączone, ale pragnienie identyfikator pomocy innego niż nIDPrompt, po prostu podać wartość dodatnią dla różni się od nIDPrompt nIDHelp.