TN028: Kontekstową Pomoc techniczna
Uwaga ta opisuje zasady przypisywania identyfikatorów kontekstów pomocy i innych kwestii pomocy w MFC.Wsparcie pomocy kontekstowej wymaga kompilatora pomocy, który jest dostępny w programie Visual C++.
[!UWAGA]
Oprócz wykonania pomocy kontekstowej, używając programu WinHelp, MFC również obsługuje korzystanie z pomocy HTML.Aby uzyskać więcej informacji dotyczących tego wsparcia i programów z pomocy w formacie HTML, zobacz pomocy w formacie HTML: Context-Sensitive pomoc dla programów Your.
Rodzaje pomocy, obsługiwane
Istnieją dwa rodzaje pomocy kontekstowej w aplikacji systemu Windows.Pierwszy, zwanego "F1 Pomoc" obejmuje uruchamianie WinHelp w kontekście właściwe na podstawie aktualnie aktywnego obiektu.Druga jest tryb "Shift + F1".W tym trybie kursor zmienia kształt na kursor pomocy, a użytkownik przechodzi do kliknij obiekt.W tym punkcie WinHelp jest uruchamiane udzielenia pomocy dla obiektu, który kliknął użytkownik.
Microsoft Foundation Classes wykonania obu tych formach pomocy.Ponadto w ramach obsługuje dwa polecenia Pomoc prosty indeks pomocy i korzystanie z pomocy.
Pliki pomocy
Microsoft Foundation classes przyjmuje pojedynczy plik pomocy.Ten plik pomocy musi mieć tę samą nazwę i ścieżkę jako aplikacja.Na przykład jeśli plik wykonywalny jest C:\MyApplication\MyHelp.exe plik pomocy musi być C:\MyApplication\MyHelp.hlp.Ustawianie ścieżki poprzez m_pszHelpFilePath zmienną z Klasa CWinApp.
Zakresy kontekstu pomocy
Domyślna implementacja MFC wymaga program niektóre reguły dotyczące przypisania kontekstu pomocy identyfikatorów.Zasady te są zakres identyfikatorów przydzielone do określonych kontroli.Zasady te można zastąpić, dostarczając różne implementacje różne funkcje związane z pomocy Członkowskich.
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 implementowane przez Microsoft Foundation Classes polecenia Pomoc:
ID_HELP_INDEX, który jest realizowany przezCWinApp::OnHelpIndex
ID_HELP_USING, który jest realizowany przezCWinApp::OnHelpUsing
Pierwsze polecenie wyświetla indeks pomocy dla aplikacji.Drugi pokazuje pomoc użytkownika przy użyciu programu WinHelp.
Pomoc kontekstowa (F1 Pomoc)
Klawisz F1 zazwyczaj jest tłumaczony na polecenie z Identyfikatorem ID_HELP przez akcelerator umieszczone w tabeli accelerator głównego okna.ID_HELP Polecenie może być również generowany przez przycisk z Identyfikatorem ID_HELP na polu głównego okna lub okna dialogowego.
Niezależnie od sposobu ID_HELP polecenia jest generowany, aż osiągnie on obsługi polecenia jest przesyłana w normalnym polecenie.Aby uzyskać więcej informacji na temat architektury routing polecenia MFC odnoszą się do technicznej Uwaga 21.Jeśli aplikacja ma włączone, Pomoc ID_HELP polecenia będą obsługiwane przez CWinApp::OnHelp.Obiekt application odbiera komunikat pomocy, a następnie odpowiednio przekierowuje polecenia.Jest to konieczne, ponieważ routing polecenia domyślne nie jest odpowiedni dla określenia najbardziej specyficzny kontekst.
CWinApp::OnHelppróbuje uruchomić WinHelp w następującej kolejności:
Sprawdza, czy aktywnej AfxMessageBox wywołania z identyfikatorem pomocy.Jeśli okno komunikatu jest obecnie aktywne, WinHelp jest uruchamiane w kontekście odpowiednich do tego okno komunikatu.
Wysyła wiadomość WM_COMMANDHELP do aktywnego okna.Jeśli to okno nie odpowiada przez uruchomienie Pomocy systemu Windows, ten sam komunikat jest następnie wysyłane do przodków tego okna, aż do przetwarzania wiadomości lub bieżącego okna jest okno najwyższego poziomu.
Wysyła polecenie ID_DEFAULT_HELP do głównego okna.Powołuje się na Pomoc domyślną.Polecenie to zazwyczaj jest mapowany na CWinApp::OnHelpIndex.
Aby globalnie zastąpić domyślne wartości podstawowy identyfikator (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 ustalona w kontekście pomocy, powinien obsługiwać komunikat WM_COMMANDHELP.Możesz routują bardziej szczegółowych pomocy niż przewiduje w ramach, jak tylko trafia w bieżącym oknie podrzędnych MDI głębokie.Można również dostarczać bardziej szczegółowe pomoc dla danego okna lub okna dialogowego, być może na podstawie bieżącego stanu wewnętrznego obiekt lub aktywny formant 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 złożono wniosek o pomoc.Gdy okno otrzymuje tę wiadomość, może wywołać CWinApp::WinHelp z kontekstem, odpowiadający okna stanu wewnętrznego.
lParam
Zawiera obecnie dostępnych kontekstu pomocy.lParamjest równa zero, jeśli brak kontekstu pomocy zostały ustalone.Implementacja OnCommandHelp można użyć Identyfikatora kontekstu w lParam do określenia inny kontekst lub po prostu można przekazać je do CWinApp::WinHelp.wParam
Nie jest używana i będzie równa zero.
Jeśli OnCommandHelp działać wywołania CWinApp::WinHelp, powinna zostać zwrócona TRUE.Zwracanie TRUE Zatrzymuje routing tego polecenia do innych klas i innych okien.
Tryb Pomoc (Shift + F1 Pomoc)
Jest to drugi formularz pomocy kontekstowej.Ogólnie w tym trybie jest wprowadzana przez naciśnięcie klawiszy SHIFT + F1 lub za pośrednictwem narzędzi/menu.Jest zaimplementowana 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 podczas stosowania jest wykonywania pompy głównym wiadomości (CWinApp::Run).
Po wprowadzeniu tego trybu, kursor myszy pomocy jest wyświetlany nad wszystkich obszarów aplikacji, nawet wtedy, gdy aplikacja normalnie byłby wyświetlony własnej kursor dla tego obszaru (na przykład zmiany rozmiaru obramowania okna).Użytkownik jest w stanie użyć myszy lub klawiatury, aby wybrać polecenie.Zamiast wykonywania polecenia, uzyskać pomoc na temat tego polecenia jest wyświetlany.Ponadto użytkownik może kliknąć obiekt widoczny na ekranie, takich jak przycisk na pasku narzędzi i pomocy będzie wyświetlany dla tego obiektu.Ten tryb pomocy jest dostarczana przez CWinApp::OnContextHelp.
Podczas wykonywania tej pętli, wszystkie naciskane jest nieaktywny, z wyjątkiem klucze dostępu z menu.Polecenie tłumaczenia również jest nadal wykonywane za pośrednictwem PreTranslateMessage Aby zezwolić użytkownikowi na klawisz skrótu i uzyskać pomoc dotyczącą tego polecenia.
Jeśli istnieją szczególne tłumaczenia lub działań należy umieścić w PreTranslateMessage funkcji, która nie powinno mieć miejsce SHIFT + F1 Pomoc w trybie należy sprawdzić m_bHelpMode członek CWinApp przed wykonaniem tych operacji.CDialog Wykonania PreTranslateMessage to sprawdza przed wywoływaniem IsDialogMessage, np."Okno dialogowe nawigacji" klawiszom niemodalny okna dialogowe to wyłącza w trybie SHIFT + F1.Ponadto 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 kliknie przycisk widoczny obszar okna aplikacji, czy jest nonclient lub kliknij klienta dokonywana jest ustalenie.OnContextHelpMapowanie uchwyty nonclient klika automatycznie kliknięć klienta.Jeśli jest kliknij klienta, następnie wysyła WM_HELPHITTEST do okna, który został kliknięty.Jeśli okno zwraca wartość niezerową, tej wartości jest używany w kontekście dla pomocy.Jeżeli zwraca wartość zero, OnContextHelp próbuje okna nadrzędnego (a nie spełniając tego obiektu nadrzędnego i tak dalej).Jeśli kontekstu Pomoc nie może być określony, domyślnie jest wysłanie ID_DEFAULT_HELP polecenia do głównego okna, następnie (zwykle) jest mapowany na CWinApp::OnHelpIndex.
WM_HELPHITTEST
afx_msg LRESULT CWnd::OnHelpHitTest(WPARAM, LPARAM lParam)
WM_HELPHITTEST jest wiadomości prywatnych windows MFC, otrzymany przez aktywne okno kliknięty SHIFT + F1 Pomoc w trybie.Po oknie wyświetlany jest następujący komunikat, zwraca identyfikator pomoc DWORD do użytku przez WinHelp.
LOWORD(lParam)
zawiera współrzędnych urządzenia osi X, gdzie myszy kliknięty został względem obszaru klienckiego okna.HIWORD(lParam)
zawiera współrzędnej osi Y.wParam
nie jest używana i będzie równa zero.Jeśli wartość zwracana jest różna od zera, w tym kontekście nazywa się WinHelp.Jeśli wartość zwracana jest wartość zero, okna nadrzędnego jest badany pod kątem pomocy.
W wielu przypadkach mogą korzystać z kodu badania hit, może już.Zobacz wykonania CToolBar::OnHelpHitTest na przykład obsługa WM_HELPHITTEST wiadomości (kod wykorzystuje kod hit test używane przyciski i etykietki narzędzi w CControlBar).
Obsługa Kreatora aplikacji MFC i MAKEHM
Kreator aplikacji MFC tworzy pliki niezbędne do utworzenia pliku pomocy (pliki .cnt i .hpj).Zawiera także liczbę plików .rtf wbudowane, które są akceptowane przez kompilatorem Pomocy.Wiele tematów są kompletne, ale niektóre mogą muszą zostać zmodyfikowane dla konkretnej aplikacji.
Automatyczne tworzenie pliku "pomoc mapowania" jest obsługiwane przez narzędzie o nazwie MAKEHM.Narzędzie MAKEHM można tłumaczyć ZASOBU aplikacji.H pliku 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óra mapuje identyfikatorów kontekstu (liczby po prawej stronie) z nazwy tematu (symbole po lewej stronie).
MAKEHM kod źródłowy jest dostępny w próbce narzędzia programowania MFC MAKEHM.
Dodawanie obsługi pomocy po uruchomieniu Kreatora aplikacji MFC
Najlepszym sposobem dodania pomocy aplikacji jest sprawdzenie opcji "Pomoc Context-sensitive" na stronie Zaawansowane funkcje Kreatora aplikacji MFC przed utworzeniem aplikacji.W ten sposób Kreator aplikacji MFC automatycznie doda wpisy map niezbędne wiadomości do użytkownika CWinApp-klasy do obsługi pomocy.
Pomoc na temat okna komunikatów
Uzyskać pomoc na temat okna komunikatów (czasami nazywany alerty) jest obsługiwane przez AfxMessageBox funkcja, otoki dla MessageBox API systemu Windows.
Istnieją dwie wersje AfxMessageBox, jeden do użycia z identyfikator ciągu, a drugi do użytku z wskaźnik 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 identyfikator opcjonalne pomocy.
W pierwszym przypadku nIDHelp domyślną jest 0, co oznacza nie pomocy dla tego okna komunikatu.Jeoli użytkownik nacionie klawisz F1, 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ść domyślna dla nIDHelp jest -1, który wskazuje, że identyfikator pomoc jest taki sam, jak nIDPrompt.Pomoc będzie działać tylko wtedy, gdy aplikacja jest włączone pomocy oczywiście).Jeśli chcesz, że okno komunikatu nie pomoc techniczna, należy podać 0 dla nIDHelp.Należy wiadomość ma pomoc włączone, ale pragną identyfikator pomocy innego niż nIDPrompt, po prostu podać wartość dodatnią nIDHelp innym niż nIDPrompt.